feat: session continuity — context-refresh command + warm session start pattern for Claude Code

[stackbilt-admin]

Problem

Claude Code sessions start cold. Even with CLAUDE.md and memory files, the AI has to rediscover current project state (open issues, pending work, recent decisions) at the start of every session. This creates cognitive overhead and missed context.

charter serve already exposes ADF context as an MCP server — the foundation is there. What's missing is a first-class way to assemble live project state into that context before a session starts.

Proposed additions

1. charter context-refresh command

A new command that assembles a live project snapshot and writes it to .ai/context.adf and optionally CONTEXT.md:

charter context-refresh [--output CONTEXT.md] [--sources git,github,d1]

Sources:

• git — last N commits, current branch, uncommitted changes
• github — open issues with specified labels, recent PRs, CI status
• d1 — pending work items from a Cloudflare D1 table (configurable endpoint + query)
• aegis / custom — extensible via .charter/context-sources.json

Output shape (written to .ai/context.adf):

# Live Context — 2026-05-22T11:00:00Z

## Open Work
- [repo/issues tagged `auto-fix`]
- [pending D1 queue items]

## Recent Activity  
- [last 5 commits]
- [recently merged PRs]

## Pending Decisions
- [items awaiting human approval]

2. Session start hook integration

A Claude Code SessionStart hook (or UserPromptSubmit on first message) that calls charter context-refresh automatically:

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "*",
      "hooks": [{"type": "command", "command": "charter context-refresh --once"}]
    }]
  }
}

--once flag: only runs if context.adf is older than N minutes, not on every message.

3. charter serve MCP exposure of context.adf

charter serve already works. Enhancement: expose a charter_context tool that returns the current context.adf contents as a structured object, so the LLM can call it directly rather than reading a file.

4. ADF warm-start instruction in CLAUDE.md

charter adf init should generate a ## Session Start section in CLAUDE.md that tells Claude Code to:

1. Call charter_context (MCP tool) to load live state
2. Read CONTEXT.md if available
3. Check memory files for recent decisions

Why this belongs in charter

Charter already owns:

• ADF format (.ai/*.adf)
• charter serve (MCP server)
• Project governance context

Session continuity is the natural next layer. The governance evidence charter tracks (commit trailers, policy stamps, blast radius) is exactly the signal that makes a warm session start meaningful — not just "what files changed" but "what decisions were made and why."

Real-world validation

This pattern was developed for the CodeBeast autonomous review agent (Stackbilt internal). CodeBeast uses charter for governance, tarotscript for symbolic decision oracles, and Claude Code as the primary dev interface. The missing piece is always session startup — rediscovering where we left off costs 5-10 minutes per session and loses nuance that can't be captured in static memory files.

A charter context-refresh that knows about D1 queue state, open GitHub issues, and recent decide receipts would make the session start ritual automatic and complete.

Implementation notes

• context-refresh should be composable: users define sources in .charter/context-sources.json
• D1 source requires CLOUDFLARE_API_TOKEN + database ID — pull from env or .charter/config.json
• GitHub source uses GITHUB_TOKEN — already expected by charter
• Output should be idempotent: safe to run on every session start
• charter serve MCP tool charter_context should return structured JSON not raw markdown

[stackbilt-admin]

Processed status update:

This issue remains open because the core requested feature set is not yet implemented end-to-end.

What exists today:

• charter context (bounded repo brief generation)
• charter_brief MCP tool

What is still missing relative to this issue:

1. charter context-refresh command with pluggable live sources (git/github/d1/...) writing .ai/context.adf
2. first-class MCP exposure for that live context object (separate from charter_brief markdown)
3. documented warm-start hook pattern that runs refresh on first-session/TTL (--once semantics)

Recommended implementation sequence:

• Phase 1: context-refresh (git-only source + output contract + tests)
• Phase 2: source adapters (github, configurable external source), schema for .charter/context-sources.json
• Phase 3: MCP charter_context structured tool + docs/session-start integration

If you want this issue closed via incremental delivery, we can track those phases as child issues and close this parent once all three land.

[stackbilt-admin]

Phase 1 shipped on main in commit c5e90fd.

What landed:

• New command: charter context-refresh
  • Writes live snapshot to .ai/context.adf
  • Supports --sources (Phase 1: git only), --output <path> markdown mirror, and --ai-dir <dir>
  • Supports --format json machine-readable output for automation
• CLI wiring + help text (charter context-refresh ...)
• Docs update in docs/cli-reference.md
• Regression tests:
  • non-git fallback snapshot
  • git repo branch/dirty/recent-commit capture + markdown mirror
  • unsupported source rejection in Phase 1

Validation run:

• pnpm exec vitest run packages/cli/src/__tests__/context-refresh.test.ts
• pnpm exec vitest run packages/cli/src/__tests__/context.test.ts packages/cli/src/__tests__/score.test.ts
• pnpm exec tsc --noEmit -p tsconfig.json

Issue status:

• Keeping this issue open because requested Phase 2/3 surfaces are still pending:
  1. pluggable non-git sources (github, d1, configurable adapters)
  2. MCP structured charter_context exposure for refreshed live context
  3. first-session/TTL warm-start orchestration (--once behavior + docs integration)

[stackbilt-admin]

Phase 2 shipped on main in commit 5fb4a44.

Delivered scope:

• charter context-refresh now supports git + github sources
• writes both:
  • .ai/context.adf
  • .ai/context.snapshot.json
• added TTL / refresh controls:
  • --once
  • --ttl-minutes <n>
  • --force
• config contract support via .charter/context-sources.json
  • default sources
  • default TTL
  • max item limits
  • github repo + strict label filter config
• fail-closed github behavior:
  • if GITHUB_TOKEN is missing, refresh does not crash
  • sources.github.available = false
  • warning emitted in payload
• derived aggregate arrays are generated from source payloads at refresh time (openWork, recentActivity, pendingDecisions) to avoid dual-source drift.

Validation:

• pnpm exec vitest run packages/cli/src/__tests__/context-refresh.test.ts packages/cli/src/__tests__/context.test.ts packages/cli/src/__tests__/score.test.ts
• pnpm exec tsc --noEmit -p tsconfig.json

Remaining for full issue closure (Phase 3):

1. MCP charter_context structured tool (read + optional refresh path)
2. documented warm-start hook orchestration around --once session usage

[stackbilt-admin]

Documentation pass completed for next-session resume readiness (commit 2aa727a).

Added canonical handoff doc: docs/context-refresh-resume.md with:

• current shipped status + commit anchors
• remaining Phase 3 scope
• restart plan
• validation + smoke commands

Also updated README.md, docs/getting-started.md, docs/cli-reference.md, and CHANGELOG.md so the resume path is discoverable from primary entry points.

[stackbilt-admin]

Canonical post-release recap (v0.16.0)

Release and governance cleanup chain is complete:

• PR merge train landed: fix(score): filter URLs, env-vars, Windows paths, and HTTP routes from grounding checker #168, fix(context): use CLI package version when repo is a private workspace root #169, feat(setup): detect npm/yarn workspace monorepos + brief stack fallback #170, chore: add keywords, author, and provenance to all 12 packages #171, test: export boundary tests for @stackbilt/ci, classify, and validate #174, feat(dogfood): bootstrap .charter governance to score 80/100 on own audit #175, feat(ux): risk-first posture view for installed repos, adoption pitch for new ones #176
• Hygiene follow-up merged: docs(ci): add VERSIONING.md documenting unified workspace versioning invariant #177 (VERSIONING invariant doc)
• Closed issues: ci(release): document unified-versioning invariant; make guard per-package if versioning ever diverges #122, ci(release): unify tag-format validation across publish-release and publish-npm #123, oss: add CODE_OF_CONDUCT, CodeQL workflow, and expand CODEOWNERS coverage #166, blocker: Claude content filter blocks OSS security-posturing tasks (CodeQL, CODEOWNERS, CODE_OF_CONDUCT) #172

Release verification:

• GitHub release published: https://github.com/Stackbilt-dev/charter/releases/tag/v0.16.0
• Release workflow run succeeded: https://github.com/Stackbilt-dev/charter/actions/runs/26329944543
• npm publish confirmed for all 12 packages at 0.16.0:
  @stackbilt/types, @stackbilt/core, @stackbilt/adf, @stackbilt/git, @stackbilt/classify, @stackbilt/validate, @stackbilt/drift, @stackbilt/blast, @stackbilt/surface, @stackbilt/policies, @stackbilt/ci, @stackbilt/cli.

Next active stream remains this issue (#155), Phase 3:

• charter_context MCP tool exposure + refresh/read behavior
• warm-start docs + hook wiring guidance

[stackbilt-admin]

Phase 3 kickoff skeleton is now open as draft PR #178: #178

This PR adds the execution checklist/DoD for charter_context and codifies the post-release verification gates we used for v0.16.0.