Introducing a new way to review your PRs.

Read the announcement

affaan-m / ecc

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

View on GitHub

30 documents · Updated Nov 20, 2026

docs / context-selection-and-retrieval

Context selection and retrieval

Context selection and retrieval turns a task into a small, checked set of ECC guidance. It discovers the skills that a profile may use, ranks applicable skills, loads only accepted source data, and keeps the result separate from provider permissions. The managed profile is the source of truth; a carrier or native assistant environment is a checked projection of that state. See Context profiles and delivery for the wider delivery model.

Context profile model

Profile scope

A context profile defines the initial skill set, the required entries, the routing mode for the remaining skills, and an 8,000-token discovery budget. lean@1 starts with three required skills and blocks an over-budget estimate. full@1 exposes the full canonical skill set as a report-only proposal. Both profiles leave native activation outside the profile contract.

References: manifests/…/lean@1.json• L1-11 manifests/…/full@1.json• L1-11 schemas/context-profile.schema.json• L4-27 scripts/…/context-profiles.js• L12-31

Capability registry

The capability registry is the checked view of canonical skills that a profile can select. It finds skill entry points under the skills root, links each entry to one owning module, records declared dependencies and resources, and binds the result to source digests. This makes a pack a source-backed capability set rather than a promise that a provider has loaded or run it.

References: manifests/…/skill-registry@1.json• L1-9 scripts/…/context-pack-registry.js• L29-37 scripts/…/context-pack-registry.js• L81-125

Native capability discovery

Native discovery checks what the assistant host can see after a carrier is prepared. For Codex, the system uses an isolated provider home and asks the native app server for its skill list. The observed result must match the selected carrier, the project binding, the expected files, and the supported provider version before the environment is marked ready.

References: scripts/…/context-profile-native-discovery.js• L14-63 scripts/…/context-profile-native.js• L233-256 scripts/…/context-profile-native.js• L172-195

Selection and retrieval

Pack and carrier selection

Profile compilation separates skills into selected, routed, and excluded groups. Explicit includes add their dependency closure, required entries cannot be excluded, and explicit exclusions prevent selection. Carrier planning then maps selected skill trees into a host layout for supported targets such as Codex, Claude, Pi, OpenCode, and Cursor. It creates a read-only file proposal and does not itself write or activate a host.

References: scripts/…/context-profiles.js• L45-71 scripts/…/context-profiles.js• L89-130 scripts/…/context-carriers.js• L13-19 scripts/…/context-carriers.js• L133-172

This diagram shows how a profile becomes a source-bound carrier without changing the host.

flowchart LR
    P[Profile and include/exclude choices] --> R[Context registry]
    R --> C[Compiled context plan]
    C --> D{Supported target layout?}
    D -->|yes| K[Carrier file and manifest proposal]
    D -->|no| U[Unsupported carrier]
    K --> V[Digest and resource checks]
    V --> N[Optional native preparation]

Task retrieval

Task retrieval ranks routed skills from the task query with two deterministic signals: weighted term matching over skill metadata and character n-gram similarity over names and descriptions. Trigger phrases add routing vocabulary, while query coverage and anchor terms prevent a single common word from producing a suggestion. The result is reproducible without a model or network.

Auto mode admits one skill only when the evidence is strong and clearly separates the top result from the next result, or when the query gives one direct canonical skill instruction. Questions, negations, reported instructions, indirect mentions, and several named skills do not silently load context. Other matches remain a bounded proposal for the assistant. A non-empty proposal that admits nothing may use a lower evidence bar; an explicitly empty proposal means no context.

References: scripts/…/context-retrieval.js• L3-15 scripts/…/context-retrieval.js• L104-135 scripts/…/context-retrieval.js• L137-203 scripts/…/context-selection.js• L309-323 scripts/…/context-selection.js• L359-395

Context loading

Loading reads the selected skill entry point and its declared resources from the canonical source. Every resource must still match its recorded digest and byte count, use UTF-8 text, and fit within the 32,000-byte task context limit. The resolver rejects skills that require manual invocation, native authority, or dynamic content unless the selection rules allow the required explicit path. It returns context as reference data, so retrieval does not grant tools, hooks, network access, installation rights, or other execution authority.

References: scripts/…/context-selection.js• L217-237 scripts/…/context-selection.js• L248-279 scripts/…/context-selection.js• L294-305

Selection receipts

Each resolution produces a receipt that binds the task, profile, target, routing policy, trigger data, registry, and selected IDs. A later call can reuse a matching pinned decision or require the caller to present the returned selection digest before loading. This prevents stale or cross-task context from silently entering a session.

References: scripts/…/context-selection.js• L281-288 scripts/…/context-selection.js• L333-355 scripts/…/context-selection.js• L396-423

Profile state and assistant environments

Managed profile state

The managed store persists the current carrier generation, selection, revision, and immutable receipts in a private dedicated directory. It publishes a new generation through a locked transaction, keeps the prior generation for rollback, and marks interrupted work for recovery. The store remains the authority for later resolution and native preparation.

References: scripts/…/context-profile-store.js• L21-45 scripts/…/context-profile-store.js• L178-223 scripts/…/context-profile-store.js• L225-295

Project context memory

Context Keeper gives each registered project a persistent memory record alongside the managed profile state. Initialization creates a project directory and registry entry, while a save records the session state, refreshes the human-readable view, and may write a compact entry to the assistant's native memory. This preserves work across sessions without making the generated view the source of truth.

The removal path treats the project directory as untrusted state. It deletes the directory only when it resolves strictly inside the shared contexts directory, then removes the project from the registry. Names that produce no safe directory slug use a stable path-based fallback, so an invalid name cannot resolve to the shared root.

References: skills/…/save.mjs• L47-94 skills/…/save.mjs• L100-164 skills/…/save.mjs• L164-210 skills/…/forget.mjs• L21-49 skills/…/shared.mjs• L48-66

Native assistant environment

Native preparation projects the current managed Codex generation into a separate private provider home. It copies no credentials, verifies the executable and provider version, registers the carrier, checks native discovery, and records the observed file state in a native receipt. The result is a disposable environment for a new session, not a change to the user's normal provider home.

References: scripts/…/context-profile-native.js• L49-79 scripts/…/context-profile-native.js• L299-360 scripts/…/context-profile-native.js• L172-195

Compatible task launch

Task launch resolves context before it starts the assistant. Auto mode may ask the target assistant for one bounded proposal when local ranking is not decisive; an empty proposal is a valid decline, while a non-empty proposal that admits nothing can use the guarded fallback. The launcher then sends the task and selected resources to Codex or Claude with the provider's existing policy, or with a verified isolated environment when one was prepared.

References: scripts/…/context-profile-launch.js• L17-35 scripts/…/context-profile-launch.js• L44-78 scripts/…/context-profile-proposal.js• L5-27

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep profile selection rules, registry IDs, dependency closure, and the profile schema aligned. A change in one can invalidate stored plan and carrier digests.
  • Keep retrieval fields, trigger manifests, exact-name routing, citation scope rules, and the selection receipt binding aligned. Otherwise a saved decision can be reused for different routing inputs.
  • Keep carrier layouts and generated discovery manifests aligned with each supported host. A valid carrier descriptor can still produce no native capability if the host path or manifest contract changes.
  • Keep managed-store revisions and native-store bindings aligned. Native preparation must refuse a carrier that no longer matches the managed generation.
  • Keep launcher adapters, isolated environment variables, executable fingerprints, and native readiness checks aligned. A changed provider boundary must stop the launch rather than use an unverified environment.
  • Keep project-directory naming and deletion checks aligned. A new naming rule must still produce a non-root path, and removal must still reject paths outside the shared contexts directory.
  • Keep session serialization, generated context views, project registry timestamps, and native memory writes aligned. A save must not report a complete session record while its persistent sources disagree.

Important failure modes

TriggerConsequenceGuard
The registry, profile, or source bytes change after a plan is madeSelection or carrier planning stops instead of using stale skill dataCompare the bound digests and recompile the current plan
Auto retrieval has several close candidates or no strong matchThe task remains pending for a bounded proposal, or runs without injected context after a declineRequire an explicit ID or valid one-skill proposal
A query names a skill only in a question, rejection, example, or reported instructionThe named skill is not admitted as implicit contextRequire a direct request or strong independent retrieval evidence
A selected skill needs native authority, dynamic content, or manual invocationThe candidate is not admitted as ordinary task contextUse a native, reviewed path or keep the skill out of automatic loading
A source file changes during selection or materializationThe operation fails and does not publish a mixed generationRe-read and verify each source descriptor before publication
A managed or native transaction is interruptedThe profile reports recovery required and does not claim a ready environmentRun the explicit recovery operation before another apply or launch
Native discovery differs from the carrier or the executable changesThe native environment is stale and task launch is blockedPrepare a fresh isolated generation and verify discovery again
A project name has no usable ASCII slugInitialization could target the shared contexts root if it creates an empty directory nameUse the stable path-hash fallback for the project directory
A registry entry points to the shared contexts root or outside itForget stops without removing context or changing the registryRequire a non-empty relative path inside the contexts directory
Native memory cannot be written during saveThe structured context remains saved, but the assistant may not receive the native memory entryTreat the warning as non-fatal and use the structured context on the next load

Key files

FileWhy to read it
scripts/…/context-pack-registry.jsDefines the source-backed capability registry and dependency view.
scripts/…/context-profiles.jsShows how profile rules become selected, routed, and excluded skills.
scripts/…/context-retrieval.jsDefines the deterministic hybrid ranking contract for task queries.
scripts/…/context-selection.jsConnects profile compilation, candidate admission, loading, and receipts.
scripts/…/context-carriers.jsMaps selected skills to host-specific carrier proposals.
scripts/…/context-profile-store.jsDefines persistent generations, revisions, receipts, rollback, and recovery.
scripts/…/context-profile-native.jsShows the boundary between managed profile state and verified Codex discovery.
scripts/…/context-profile-launch.jsDefines task resolution and launch behavior for compatible assistant targets.
skills/…/save.mjsRecords project sessions and updates the persistent context views.
skills/…/forget.mjsEnforces safe project-context removal.
skills/…/shared.mjsDefines project registry, context storage, and generated-view boundaries.
manifests/…/lean@1.jsonGives the narrow profile's intended eager and required context.
manifests/…/full@1.jsonGives the complete discovery projection and its report-only budget mode.
schemas/context-carrier.schema.jsonDefines the carrier contract shared by planning and materialization.