context-precedence

Context Precedence

This skill is the canonical policy for resolving conflicts between project context sources. It is intentionally small: the MVP is an auditable decision rule for humans and agents, not an automated context router.

Canonical Rule

When two context sources conflict, use this order:

canonical docs > project skills > packs > handoffs > session memory > proposed context

This MVP is a decision policy, not a runtime merge engine.

Source Classes

• canonical docs: versioned project documentation that defines durable product, architecture, process, or operating rules. Examples: README.md, bundled policy skills under ai-specs/skills/, SDD/spec artifacts, and recorded project decisions.
• project skills: project-local agent skills under ai-specs/skills/ that encode repeatable workflows or conventions for this repository.
• packs: reusable imported or bundled context packages, including vendored skills, bundled commands, or future installable packs.
• handoffs: structured summaries from prior sessions that describe current state, next steps, blockers, or recent decisions.
• session memory: runtime memory observations captured during an active or prior agent session.
• proposed context: new assumptions, interpretations, plans, or content generated by an agent before they are accepted into a higher-precedence source.

Adapting the stack

The order above is the default MVP. Some teams treat the canonical-store capability (e.g. a vault) as the highest-authority layer for decisions and history; if your project bound a canonical-store provider for that role, follow it when it explicitly defines durable rules—even when generic “canonical docs” in the repo are silent. Do not silently demote skills: resolve conflicts using the published order plus any project skill that defines an override.

Conflict Examples

Docs vs session memory

If this skill says generated files must not be hand-edited, but session memory says a previous agent edited AGENTS.md directly, follow this skill. Treat the memory as historical context, not as the current rule.

Project skills vs packs

If a project skill says new implementation work must start from development in a dedicated worktree, but a vendored pack suggests branching from main, follow the project skill. Project-local skills are closer to the repository's current operating rules.

Handoffs vs session memory

If a handoff says a change is paused before apply, but session memory contains an older note that implementation already started, follow the handoff unless a higher-precedence doc or skill says otherwise.

Proposed context vs existing sources

If an agent proposes adding [precedence] to ai-specs/ai-specs.toml, but the Manifest V1 contract says new sections are out of scope, reject the proposal or turn it into a future OpenSpec change.

Audit Checklist

When resolving a conflict:

• Identify every source involved in the conflict.
• Classify each source using the source classes above.
• Pick the source with the highest precedence.
• If the lower-precedence source is still useful, convert it into a proposed change instead of silently applying it.
• Record any durable decision in the appropriate canonical location.

MVP Boundary

This rule MUST NOT require [memory], [precedence], [packs], or any other new manifest section.

This rule MUST NOT claim that conflicts are resolved automatically by runtime code. Future Context Router work may automate or refine this policy, but this MVP remains documentation-first.