# Context Engineering

## Purpose
Context engineering gives authors and reviewers the minimum source-grounded context needed to draft accurately without rediscovering the corpus from scratch.

It separates orientation material from source authority so public RFC text stays accurate, compact, and auditable.

## Layer model
Use three layers together:

1. **Project-pack orientation context**
   - Curated concepts, terminology, component maps, prior synthesis, and open questions supplied by the selected pack or built for the run.
   - Optimized for orientation and shared language.
2. **Source-discovery layer**
   - Graphs, indexes, inventories, relationship extracts, direct-source routing tables, or other source-derived discovery surfaces anchored to the corpus.
   - Optimized for evidence discovery, coverage checks, and contradiction detection.
3. **Run artifacts**
   - Context packets, scout reports, claim ledgers, capability matrices, validation reports, and correction logs.
   - Optimized for proving one RFC run.

Orientation context helps the run start correctly. Source discovery grounds the run. Run artifacts preserve the proof chain.

## Orientation record types
Orientation material should use stable record types where possible:

- **Concept** — term, definition, aliases, related concepts, source hints.
- **Component** — subsystem, responsibilities, boundaries, inputs, outputs.
- **Workflow** — ordered behavior, actors, states, failure modes.
- **Capability** — visible or testable behavior.
- **Interface** — command, API, schema, message, or protocol surface.
- **Example** — scenario, assumptions, expected behavior, validation status.
- **Caveat** — limitation, contradiction, or known gap.
- **Glossary** — preferred terms and forbidden synonyms.
- **Source note** — short pointer into the corpus.

Recommended fields for orientation records used in RFC work:

- [ ] `id`
- [ ] `title`
- [ ] `type`
- [ ] `status`
- [ ] `summary`
- [ ] `source_refs`
- [ ] `relationships`
- [ ] `known_constraints`
- [ ] `open_questions`
- [ ] `last_verified`

Orientation records may summarize, but they do not authorize public technical claims by themselves.

## Source-discovery model
If a source-discovery layer exists, preserve enough structure to explain why a result matters.

Useful node or entry types include:

- Source file or section.
- Symbol or interface entry.
- Schema element.
- Fixture, packet, or example.
- Concept.
- Claim candidate.
- Capability.
- Validation case.

Useful relationship or routing types include:

- `defines`
- `implements`
- `constrains`
- `depends_on`
- `reads`
- `writes`
- `generates`
- `validates`
- `contradicts`
- `exemplifies`
- `covers`
- `supersedes`

Each preserved result should keep:

- [ ] A stable result ID.
- [ ] Source ID and locator.
- [ ] Relationship or query type.
- [ ] Confidence, staleness, or equivalent caveat when available.
- [ ] Neighboring context needed for interpretation.
- [ ] Known contradictions.

When no map layer exists, use a direct-source inventory that records the same practical information: what source unit matters, where it is, why it matters, and what remains unresolved.

## Context packet build order
Build context packets in this order:

1. [ ] State the RFC objective.
2. [ ] Load orientation records for concepts, components, workflows, interfaces, and capabilities.
3. [ ] Extract vocabulary, constraints, and open questions.
4. [ ] Query the source-discovery layer or direct-source inventory for matching source units and relationships.
5. [ ] Expand only the neighbors that explain behavior, coverage, or contradiction.
6. [ ] Assign source scouts to missing, stale, or conflicting areas.
7. [ ] Summarize accepted context in a compact packet.
8. [ ] Mark every context-only item as unconfirmed.
9. [ ] Feed source-backed items into the claim ledger before drafting public prose.

## Context packet shape
A context packet should contain:

- RFC objective.
- Public deliverable target.
- Included orientation record IDs.
- Included discovery query IDs or equivalent references.
- Key vocabulary.
- Source-backed facts.
- Unconfirmed context-only summaries.
- Known contradictions.
- Required scout assignments.
- Candidate claim IDs.
- Candidate capability rows.
- Open questions.
- Exclusions.

## Source scout use
Dispatch source scouts when:

- [ ] A context summary lacks source confirmation.
- [ ] The source-discovery layer shows contradiction, staleness, or missing coverage.
- [ ] A capability row lacks evidence.
- [ ] An example relies on behavior not yet proven.
- [ ] A public section would otherwise be drafted from inference alone.

Scout outputs should stay narrow: what the source says, where it says it, what was observed, and what remains uncertain.

## Anti-drift controls
Run these controls before drafting and before final packaging:

- [ ] No public claim depends only on orientation context.
- [ ] No discovery-aided claim lacks primary source confirmation.
- [ ] No stale term conflicts with current source vocabulary.
- [ ] No capability row is missing source coverage.
- [ ] No example demonstrates behavior outside the accepted claim set.
- [ ] No correction updates public prose without updating the claim ledger first.

## Refresh policy
Refresh context when:

- The source corpus changes.
- The source-discovery layer changes.
- Orientation records used by the run change.
- A review finding challenges source faithfulness.
- An example result contradicts the expected behavior.
- Clean-room proof exposes ambiguity.

After refresh, re-run only the affected gates unless the authority hierarchy or RFC objective has changed.