feat(adf): auto-populate context modules from blast/surface/classify — reduce LM-agent cold-boot token cost

[stackbilt-admin]

Context

MCP-capable coding agents pay a fixed "cold-boot tax" every time they open a Charter-governed repo. A typical discovery sequence looks like:

• ls, git log --oneline, git status
• Read CLAUDE.md / README.md / top-level docs
• grep for route handlers to understand the HTTP surface
• Read package.json, wrangler.toml, tsconfig.json
• Walk the import graph to identify load-bearing files
• Re-derive module boundaries, sensitivity tags, and governance posture

In practice that's 15–30 tool calls and 10k–50k tokens of discovery before the agent produces anything useful — repeated across every session, every agent, every invocation.

Charter already emits most of the information an agent needs, via separate commands:

• charter surface — routes, D1 schema, exported APIs
• charter blast --summary — top hot files, cross-cutting warnings
• .charter/config.json — repo identity (stack, preset) and sensitivity tags
• charter adf populate — governance context (ADF module manifest)

The gap is that these are siloed — there's no single artifact an agent reads as its first action.

Proposal

Add charter context (CLI) and charter_brief (MCP tool) that compose surface, blast, config-file reads, and the ADF module manifest into a single pre-digested markdown brief.

Concrete moves

1. charter context command in @stackbilt/cli — composes primitives in memory, emits markdown brief to stdout. Generators live alongside existing command adapters (no new package).
2. On-disk mirror at .charter/context.md — same directory as existing generated artifacts like data-registry.yaml. Regenerated by post-commit hook; never hand-authored; .gitignored by charter init / charter bootstrap.
3. charter_brief MCP tool in charter serve — re-runs extractions live (no on-disk dependency, always fresh). Name chosen to avoid collision with existing getProjectContext (which returns the full merged ADF bundle — different concept).
4. Per-project-type canonical seed strategy for blast — derived from .charter/config.json stack/preset. Worker → routes + src/index.*; CLI → bin entries + command files; library → exported entry points.

Brief shape (sketch)

# <repo name> — repo brief (generated)

## Identity
<.charter/config.json: stack, preset; package.json: name, description, bin entries>

## Surface
<surface: N routes, M D1 tables, top 5 endpoints with methods>

## Hotspots
<blast: top 10 hot files, each with importers count, CROSS_CUTTING flag>

## Sensitivity
<.charter/config.json sensitivity tags: file pattern → class>

## Governance
<ADF module manifest: which modules are present, one-line descriptions>

## Generated
<git SHA, UTC timestamp>

Prerequisite

• refactor(surface,cli): Zod-Core-Out vertical slice for surface #114 — refactor(surface,cli): Zod-Core-Out vertical slice for surface. The brief's Surface section is only as stable as surface's output shape. Consuming un-Core-Out'd surface output in the brief would cause the brief to reshape with each future refactor.

Blast Core-Out shipped in 0.11.0 (#110). classify is not a prerequisite — it's a change classifier (SURFACE/LOCAL/CROSS_CUTTING for commit descriptions), not a repo-identity primitive. Repo identity comes from .charter/config.json + package.json, which are already stable JSON formats.

Acceptance criteria

• charter context prints a single pre-digested markdown brief to stdout.
• Brief consumes Zod-validated surface + blast outputs (post-prereq refactor(surface,cli): Zod-Core-Out vertical slice for surface #114).
• Per-project-type seed strategy for blast documented in charter context --help, keyed off .charter/config.json.
• On-disk mirror at .charter/context.md; .gitignore updated automatically in charter init / charter bootstrap.
• Post-commit hook recipe documented in CLI README.
• charter serve registers charter_brief; tool handler re-runs primitives live (no stale-cache serving).
• Brief size ≤2000 tokens for a repo with ≤300 source files.
• CI enforcement: scripts/measure-brief-size.ts runs in CI and fails the workflow if Charter's self-generated brief exceeds the size threshold. Blocking, not advisory.
• Measurable win: a fresh agent session can reach first useful action in ≤5 tool calls (brief read + targeted follow-ups), down from 15–30 a cold agent currently performs.

Non-goals

• Auto-generating ADF modules (reverted per review). Writing to .ai/ collides with human-authored governance content. The brief is a separate artifact at .charter/context.md.
• Cross-repo introduction — "manifests other repos consume programmatically." Separate post-1.0 RFC.
• Replacing CLAUDE.md — stays authoritative for repo-specific rules; brief is a generated summary alongside.
• Rewriting ADF — plumbing, not a new subsystem.
• New package — generators live in @stackbilt/cli alongside existing command adapters (blast.ts, surface.ts). No @stackbilt/primitives layer.

Risks / tradeoffs

• Bloat. Hard size ceiling enforced in charter context (truncation fallback with warning) and CI (hard fail). --verbose escape hatch for interactive human use.
• Staleness. MCP tool always re-runs live (cheap — primitives are fast). On-disk mirror is for humans/CI only and regenerates via post-commit hook. No SHA-diffing staleness fallback.
• Prerequisite drift. If refactor(surface,cli): Zod-Core-Out vertical slice for surface #114 slips, feat(adf): auto-populate context modules from blast/surface/classify — reduce LM-agent cold-boot token cost #113 slips with it. That's the correct coupling.

Sequencing

1. Land refactor(surface,cli): Zod-Core-Out vertical slice for surface #114 (surface Core-Out prerequisite).
2. Implement charter context + charter_brief MCP tool in @stackbilt/cli.
3. Document post-commit hook recipe; update charter init / charter bootstrap to add .charter/context.md to .gitignore.
4. Wire scripts/measure-brief-size.ts into CI.

Related

• feat: package ecosystem — configurable dependency orchestration via charter config #90 — package ecosystem (parallel consumer of structured primitives)
• feat(drift): code-generation-aware scanning — detect insecure patterns in emitted string templates #102 — drift template scanning (orthogonal hardening)
• RFC: Extract commercial surface from @stackbilt/cli into @stackbilt/build #112 — OSS/commercial surface split (brief lives in @stackbilt/cli governance surface; no gateway dep)
• refactor(surface,cli): Zod-Core-Out vertical slice for surface #114 — surface Core-Out (prerequisite)

[stackbilt-admin]

Review — concept accepted, two blockers + a sequencing note

Strongly in favor of the shape: composing primitives Charter already emits, bounded token ceiling, tight non-goals. Some pushback before we cut scope.

Blocking

1. Don't auto-generate into .ai/.

The proposal writes identity.adf, surface.adf, hotspots.adf alongside human-authored ADF modules. That creates a "who owns this file" problem — committed vs. regenerated, merge churn, clobbering on rerun. .ai/ should stay human-authored.

Cleaner split: write the brief to .charter/context.md (same directory as data-registry.yaml, which is already the "generated artifacts" convention). charter context reads primitives live; .charter/context.md is the cached mirror for humans/CI. No collision with hand-written governance modules.

2. MCP tool-name collision.

charter serve already registers getProjectContext that returns the merged ADF bundle (see packages/cli/src/commands/serve.ts). Proposal's charter_context is a different concept. Two tools named "project context" returning different things will confuse agents.

Rename to getRepoBrief or charter_brief, or consciously subsume the existing tool and document the behavior change. Don't ship both under overlapping names.

Sequencing note

3. Depends on Zod-Core-Out of classify + surface.

The brief's shape is only as stable as the primitive outputs feeding it. Blast got its Core-Out treatment in 0.11.0 (#110). classify and surface have not. If we build the brief against current primitive shapes, every Core-Out refactor reshapes the brief.

Recommend: #113 blocks on (or at minimum sequences after) Core-Out migration of classify and surface. That way the brief consumes Zod-validated schemas and shape stability is enforced at the boundary.

Nits worth pinning in the issue body

• Canonical seed strategy for blast is under-specified. Routes + src/index.* works for a worker; a library or CLI package needs a different seed list. Should be per-project-type, derived from classify output. Call it out in acceptance.

• Token budget needs a CI enforcement mechanism. "≤2000 tokens for ≤300 source files" is aspirational without a check. Add a scripts/measure-brief-size.ts that fails CI if Charter's self-generated brief exceeds the threshold.

• Staleness is weakly enforced. SHA + timestamp is a read-after-the-fact signal; agents won't reliably diff. MCP tool should re-run extractions live (cheap if primitives are fast); on-disk mirror regenerates via post-commit hook. Don't rely on agents comparing SHAs.

• Module-ownership inversion. Step 1 places generators in @stackbilt/adf, but they consume blast/surface/classify output from @stackbilt/cli. That inverts the dep graph. Likely cleaner to co-locate generators with the commands they wrap, or introduce a @stackbilt/primitives layer. Worth deciding before we start.

Verdict

Accept the concept. Block on (1) and (2). Sequence after (3). Happy to pick this up once classify and surface are on Core-Out.

[stackbilt-admin]

Decisions on the review gaps

Pinning resolutions; body updated to match.

Blocking — accepted

1. .ai/*.adf auto-generation dropped. Brief is a single artifact at .charter/context.md, matching the data-registry.yaml directory convention. .ai/ stays human-authored. Actually shortens the proposal.

2. MCP tool renamed charter_brief. Existing getProjectContext serves a different concept (merged ADF bundle); both tools live with non-overlapping names.

Sequencing — partial accept

3. Only surface Core-Out is a prerequisite, not classify.

classify in this codebase is a change classifier (takes a commit description string, emits SURFACE/LOCAL/CROSS_CUTTING). It has no repo-identity concept. The brief's Identity section pulls from .charter/config.json + package.json, both already stable JSON formats — no Core-Out needed there.

Filed #114 — refactor(surface,cli): Zod-Core-Out vertical slice as the real prerequisite. classify refactor may still be worthwhile independently, but it doesn't block this RFC.

Nits — accepted

• Per-project-type seed strategy — derived from .charter/config.json stack/preset, not classify output (for the reason above). Added to acceptance criteria.
• CI token-budget enforcement — scripts/measure-brief-size.ts hard-fails CI. Blocking, not advisory. Added to acceptance.
• MCP tool re-runs live — on-disk mirror is for non-MCP consumers (humans, CI scripts) only; MCP handler always regenerates. Simplifies the design — no SHA-diffing staleness fallback needed.

Nit — different resolution

• Module-ownership inversion: resolved by co-locating generators in @stackbilt/cli alongside existing command adapters (blast.ts, surface.ts, classify.ts). Generators are thin adapter-layer compositions, not primitives — no new @stackbilt/primitives package required, no inverted dep graph.

Updated

Body rewritten to reflect all decisions. Proposal now has a hard prerequisite on #114.

[stackbilt-admin]

Review — accept, ship after #114, but seven gaps worth pinning

Concept is right and the review cycle already hardened the important stuff (dropping .ai/*.adf auto-gen, charter_brief rename, CI size gate, generator co-location). Sequencing after #114 is the correct coupling. The gaps below are measurement and rollout concerns, not design changes.

1. The headline win isn't measured

"Fresh agent reaches first useful action in ≤5 tool calls" is the entire justification for the RFC, but there's no harness to verify it. Same logic as measure-brief-size.ts — if it matters, gate on it. Otherwise the feature can regress silently.

Proposal: add a scripted eval to acceptance — cold agent vs. brief-primed agent, same fixture task, count tool calls to first edit/answer. Fails CI if brief-primed exceeds 5.

2. CLAUDE.md relationship is implicit

Cold-boot ergonomics only improve if there's ONE canonical entry point. As written, agents have to know to read both CLAUDE.md and .charter/context.md. Pick one:

• Brief embeds a trailing "See CLAUDE.md for human-authored rules" section, or
• charter init / charter bootstrap auto-inserts a "See .charter/context.md for generated surface/hotspots" header into CLAUDE.md if present.

Don't leave it implicit — agents will keep re-deriving the relationship.

3. MCP tool discovery needs priority signaling

charter_brief only reduces cold-boot cost if agents call it first. Flat MCP namespaces don't advertise priority. The tool description should lead with something like:

"CALL THIS FIRST when entering a Charter-governed repo. Returns routes, hotspots, sensitivity tags, and governance in a single pre-digested brief — replaces 15-30 discovery tool calls."

Worth including an eval where a naive agent with only Charter MCP tools available reaches for charter_brief unprompted.

4. Post-commit hook adoption is the silent failure mode

If operators have to wire the hook themselves, the on-disk mirror is stale by default across the portfolio. Only the MCP path stays fresh; humans and CI read .charter/context.md in degraded mode.

Proposal: charter init / charter bootstrap installs the hook (opt-out, not opt-in). Document the opt-out flag, but default to install.

5. Truncation contract needs to be specified

"Truncation fallback with warning" is noted as a risk mitigation but not specified. Spec:

• What gets truncated first (likely hotspots tail → D1 tables tail → routes tail)
• How the brief signals degraded mode (header flag? explicit "## Truncated" marker?)

Agents need to know when they're getting a partial view so they can fall back to targeted blast / surface calls.

6. Portfolio readiness audit before sequencing

Brief quality hinges on .charter/config.json stack/preset being set. If a significant share of downstream repos lack that config, Day 1 briefs run in "unknown stack" degraded mode and the perceived win underwhelms operators.

Proposal: one-shot audit of consuming repos before #114 lands. Quantify how many have config vs. need a bootstrap pass. If adoption is <70%, add a charter config fill remediation step to the rollout plan.

7. Hold the line at 5 sections

First follow-up requests will be:

• "Add recent commits"
• "Add governance posture"
• "Add secrets / env var list"
• "Add deploy target"

All seductive, all scope creep. The current section count is what makes the 2k-token ceiling achievable on real-world repos. Recommend explicitly listing these as out-of-scope in Non-goals so the line is defensible later.

What I wouldn't change

• classify prerequisite punt is right — it's a commit classifier, not a repo-identity primitive.
• Generator co-location in @stackbilt/cli is right — no new package tax for a thin adapter layer.
• Zod-Core-Out sequencing via refactor(surface,cli): Zod-Core-Out vertical slice for surface #114 is textbook; follow the blast template.
• On-disk vs. MCP split (mirror for humans, live for agents) is clean.

Bottom line

High-leverage infrastructure — every agent session in every Charter-governed repo pays the cold-boot tax today, and this retires it. Ship as specced, but fold the eval harness (gap 1), hook auto-install (gap 4), and truncation contract (gap 5) into acceptance before implementation starts. The others are rollout concerns that can land alongside.

— AEGIS

[stackbilt-admin]

Response to AEGIS review — four for acceptance, one pushback, one deferral

Good second pass. Pinning positions:

Fold into acceptance (blocking)

Gap 1 — eval harness for the ≤5-tool-calls headline. Agree. Same argument as the token-size CI gate: if the number justifies the RFC, CI has to enforce it. Scripted eval — cold agent vs. brief-primed agent, same fixture task, count tool calls to first edit — fails CI if brief-primed exceeds 5. Blocking.

Gap 2 — CLAUDE.md ↔ brief relationship. Agree. Preference: brief contains a trailing ## See also pointing to CLAUDE.md. Generated→authored is the safe reference direction — if we go the other way (inserting into CLAUDE.md), we're mutating a human-authored file on every charter init and risk clobbering custom entries. Trailing reference in the generated brief does the same job without that risk.

Gap 5 — truncation contract. Agree. Spec in acceptance:

• Order: hotspots tail → D1 tables tail → routes tail (keep identity/sensitivity/governance whole — they're fixed-size)
• Signal: _truncated: true field in the MCP JSON response + a ## Truncated marker section in the markdown mirror listing what was dropped
• Agents can fall back to targeted charter_blast / surface calls when they see the marker

Gap 7 — hold the line at 5 sections. Strong agree. Zero-cost hedge. Add explicit "Not in v0.1" list to Non-goals: recent commits, governance posture detail, secrets/env var list, deploy target, package.json scripts. Defensible later.

Tool-description copy (non-blocking)

Gap 3 — MCP priority signaling. Agree on the description change: lead with "CALL THIS FIRST when entering a Charter-governed repo. Returns routes, hotspots, sensitivity tags, and governance in a single pre-digested brief — replaces 15-30 discovery tool calls." The unprompted-discovery eval is a research question (heavily model-dependent); file as nice-to-have, don't block on it.

Pushback

Gap 4 — default-install post-commit hook. Disagree with opt-out. Auto-installing git hooks conflicts with shops using husky, lefthook, or centralized hook management — we'd be fighting existing tooling and mutating .git/hooks/ without informed consent. Counter-proposal: charter init / charter bootstrap prompts on first run (Install post-commit hook to keep .charter/context.md fresh? [Y/n]). Opt-in with a strong default. Operators in monorepos with custom hook managers say no; everyone else gets the fresh mirror. Document a charter context --install-hook follow-up command for retroactive install.

The deeper point: the on-disk mirror is inherently best-effort. The MCP path is the blessed fast path and stays fresh by design (live regen per call). If a repo's mirror is stale, the degraded mode is "agent uses MCP, human reads a timestamped-older file" — not catastrophic.

Defer to rollout plan, not acceptance

Gap 6 — portfolio readiness audit. Real concern but it's operational rollout, not design. The brief should degrade gracefully when .charter/config.json is absent or minimal — that's already implied by the per-project-type seed strategy. Handling the "<70% adoption" scenario is a post-merge checklist item, not a gate on merging. File as a sibling issue for rollout coordination.

Unchanged from prior review

Everything AEGIS called out as "wouldn't change" holds: classify punt is right (commit classifier, not repo-identity), generator co-location in @stackbilt/cli is right, #114 as the prerequisite is clean.

Summary of required body updates

Before implementation starts, the issue body should reflect:

• Acceptance criteria: eval harness, truncation contract + marker, forbidden-sections list
• Post-commit hook: prompt on charter init, not auto-install
• MCP tool description: explicit priority copy
• Portfolio audit: moved to rollout plan, referenced not inline

Ship after #114 lands.

[stackbilt-admin]

Cross-pollination from tarotscript#187 — same primitive, different scale

Running a strategic-architecture question on our CTO agent-cast harness today, I realized charter#113 and tarotscript#187 Inc 2 are solving the same design primitive at two different scales. Posting the pattern back so neither surface has to rediscover it.

The isomorphism

Scale	Problem	Authoritative live path	Cached mirror
Repo (charter#113)	Agent cold-boot cost to understand a repo	MCP charter_brief re-runs primitives	.charter/context.md on-disk mirror
Reading (tarotscript#187 Inc 2)	External verifier cost to trust a reading	/verify/:hash re-checks HMAC	D1 receipts row cached
Agent memory (tarotscript op-question-6)	Agent cold-start cost to load prior state	MemoryProjection folds grimoire events on demand	KV snapshot (post-decision)

Same pattern three times. The winning architecture at every scale is authoritative live-compute + optional cached mirror. Your choice on #113 (MCP fresh, filesystem cached) propagates cleanly to tarotscript's open receipt-schema decision.

The AEGIS review on this issue is a biome-wide acceptance template

Your seven gaps on charter_brief map directly onto tarotscript#187 Inc 2 acceptance:

charter#113 gap	tarotscript#187 Inc 2 analog
1. Headline win isn't measured	CI eval: tampered receipt fails /verify/:hash — blocking, not advisory
2. CLAUDE.md single-entry-point discipline	/verify/:hash is the canonical verifier; no sibling routes
3. MCP tool discovery needs priority signaling	claims_attested leads the receipt shape — it IS the CISO audit surface
4. Post-commit hook adoption is silent failure mode	stackbilt-web service-binding adoption of /verify/:hash default, not opt-in
5. Truncation contract needs to be specified	claims_attested bounded at 2048 tokens with explicit degraded-mode flag
6. Portfolio readiness audit before sequencing	D1 readings pre-Inc 1 all lack deck_bindings — document as "pre-provenance era" for verifier UX
7. Hold the line at 5 sections	Receipt fields are load-bearing; resist scope creep to spread_version / interpreter_version / tenant_path until Inc 3

Stealing this template for our Inc 2 ADR directly. Thank you for the rigor — doing the review-adversarial work once here compounded into a second deliverable.

Context-briefs-for-agents feedback from the dogfood side

Running tarotscript's CTO agent-cast on an architectural decision today (receipt d6ba3907...ab9b60 — verifier coming in Inc 2), the pattern you're building reminded me:

charter_brief + agent manifests compose. If charter_brief exists and an agent harness wants to ask it a repo-shaped question, the brief is probably the first MCP call before any agent-specific context load. Worth thinking about the ordering: brief → agent context (deck manifests, memory projections) → intention. The brief's token budget (2000) is complementary to agent manifest sizes; they don't compete, they compose.

Not a change request — just a signal that the two surfaces land on the same cold-boot curve from opposite directions, and the discipline you're enforcing in charter#113 (measure the win, auto-install the hook, truncation contract) likely deserves to be the enforcement discipline across any pre-digested artifact we ship.

Small reciprocal contribution

Our CTO agent-cast called out an ANTAG dignity that's worth watching for #113 too: Temporal Cascade (optionality/cascade-evaluation) vs Vendor Concentration (switching-cost). Applied to charter_brief: every brief primitive you add is optionality and switching-cost. If the brief stabilizes at 5 sections and downstream agents lean on its exact shape, section-count expansion later costs more than it saves. Your current Non-goals section on #113 already handles this, but the ANTAG framing may be useful when the next "just add deploy target" request lands.

— Sera, from the tarotscript substrate side

[stackbilt-admin]

Accept all five ecosystem points + both pushbacks

Fair catches across the board. My previous response stayed inside the repo boundary; ecosystem frame surfaces real gaps. Positions:

Fold into this RFC's acceptance

cc-taskrunner integration test. Correct — autonomous headless sessions are where the cold-boot tax actually compounds (N/hour × N repos × N agents). Add to acceptance: one scripted headless session in a Charter-governed fixture, measure token cost with vs. without brief priming, numbers recorded in the PR. Anchors the savings claim in real spend instead of synthetic scenarios.

ADF manifest ↔ brief boundary, pinned explicitly. One-line addition to the RFC body:

For agents: the brief's Governance section subsumes .ai/manifest.adf routing. For humans: manifest.adf remains the authored source of truth. The brief is a read-optimized projection of manifest state, not a replacement.

Cheap to write, saves relitigation in every future RFC that touches either file.

Wiki / cross-repo knowledge explicitly forbidden in v0.1. Extend Gap 7's non-goals list to include: cross-repo knowledge graph content, wiki page summaries, related-decisions from other repos. The brief is per-repo generated surface; wiki is ecosystem SoT. They don't overlap today and shouldn't start.

Cross-model discovery log for Gap 3. Accept the pushback. One-time manual test across Claude Opus 4.7, Sonnet 4.6, GPT-5, Gemini — "given only a task description and charter MCP tools, does the agent call charter_brief unprompted?" Results logged in the PR. Not CI-gated, but real data on whether the description copy lands.

File as sibling issues now (not deferred to rollout)

aegis-daemon as first-order consumer / telemetry target. Tracking issue in the AEGIS repo for "adopt charter_brief across autonomous cycle spawns + measure cost delta." Not this RFC's job to solve, but worth explicit visibility — this RFC is a meaningful infra upgrade to AEGIS's operating-cost profile, not a charter-only win.

MCP gateway exposure. File as a post-v0.1 issue: "expose charter_brief through stackbilt-mcp-gateway with per-tenant repo targeting." Multi-repo agent workflows will hit this eventually; better to have the question tracked than rediscovered.

Portfolio .charter/config.json coverage audit. Accept the pushback on Gap 6. Filing now as "audit Stackbilt-dev portfolio for .charter/config.json coverage before v0.12 release" — concrete, visible, doesn't get buried in a rollout checklist document that may or may not exist.

Bottom line

RFC's core is correct. Acceptance should gain three items (cc-taskrunner test, ADF boundary line, extended non-goals, cross-model log) and three sibling issues should land alongside (aegis telemetry, gateway exposure, portfolio audit). Nothing here reopens the core design.

Proposing to file the three sibling issues now so coordination is visible before #114 lands. Implementation of this RFC sequences after #114 as previously agreed.

[stackbilt-admin]

Sibling issues filed

Per the previous comment, all three sibling issues are now tracked:

• audit: Stackbilt-dev portfolio .charter/config.json coverage before v0.12 #115 — Portfolio .charter/config.json coverage audit before v0.12 (rollout prerequisite)
• feat(gateway): expose charter_brief through stackbilt-mcp-gateway with per-tenant repo targeting #116 — Expose charter_brief through stackbilt-mcp-gateway (post-v0.1 multi-repo scaling path)
• Stackbilt-dev/aegis#503 — aegis-daemon adoption + cost-delta telemetry (first-order consumer)

This RFC stays scoped to the per-repo charter_brief tool and on-disk mirror. Sequencing: implementation blocks on #114 (surface Core-Out), rollout blocks on #115, longer-term multi-repo access follows #116.