epistemic-protocols: Instructions file for Codex

AGENTS.md

This file provides always-loaded guidance for coding agents when working in this repository. Keep it short: put orientation, decision rules, and verification commands here; use linked docs and rg for recoverable detail.

Northstar

Epistemic Protocols is a domain-free metalanguage of structured types and morphisms that moves the cognitive load of human-AI collaboration from recall to recognition. Instead of recalling and writing up front every unknown, decision, and condition a task turns on, the person answers or recognizes each where it binds: unknowns are elicited into utterance, AI attention is constrained without bias, and interaction deficits are resolved at their root within bounded loops, before local misalignment hardens into system-wide rework.

Entry Path

For a reader who is understanding or evaluating the project rather than changing it — the sections after this one govern changing it:

• README.md orients: what the project is for, when to reach for each protocol, and how to install it.
• A protocol's skills/*/SKILL.md is that protocol's contract, its formal blocks included.
• route/ and premise/ are optional layers a user may install; premise/README.md names route as what delivers the premise index.
• lean/, .claude/, design/, and scripts/ are maintainer machinery for checking, packaging, and revising the contracts; using a protocol does not require reading them.
• When exploring a directory, read its AGENTS.md if present.

Settled Directions

Citable registry of conventions whose resolution direction is already constituted. The option-set relay test (defined in premise/interaction-factorization.md) cites a clause here to collapse settled-direction option-set entropy — a finding whose direction a clause below already determines is presented as relay, not gated. Maintained by hand: a direction recurringly constituted the same way graduates into a clause here.

• Count-free protocol cardinality: do not hardcode the protocol count in prose, comments, test names, or metadata descriptions — use count-free phrasing ("all core protocols", "every protocol plugin"). Completeness-sensitive code and tests compare exact protocol identities against the canonical registry (scripts/load-protocols.js CANONICAL_PROTOCOL_SET, the full identity set; CANONICAL_PRECEDENCE is the presentation-order subset it is built from) or derive displayed counts from it; a deliberate subset (e.g. the Codex submission set) states its inclusion policy explicitly.
• Multi-skill plugin description scope: a plugin bundling more than one skill (currently: epistemic-cooperative only) is not required to enumerate every skill's /command in its top-level plugin description to satisfy artifact-self-containment.js's hasRoutingCue check; single-skill plugin descriptions must still name their one skill's /command, enforced unchanged.
• Checkpoint policy stays at the meta layer: SKILL.md inscribes only when a checkpoint fires, what it presents, and each branch's state transition — never which branch is correct. General form: premise/tiering-and-scope.md §Checkpoint Policy Stays at the Meta Layer.
• Conditional-load cut criterion: what leaves a SKILL.md for its references/ surface is decided by structural belonging and the earliest loading tier the clause's need requires, never by length. A clause moved without a precise pointer that reaches it just before it binds is a defect rather than an optimization.
• Surface authority order: instruction surfaces rank premise/ → AGENTS.md → .claude/rules/ → .claude/principles/ → docs/, and where two disagree the higher one governs while the lower one is the thing to correct. A static check is an enforcement channel rather than a surface: it can block a commit, and a block whose basis contradicts a higher surface is a defect in the check — not a reason to abandon the work it stopped. A surface below AGENTS.md describes and explains; none of them establishes its own tier or another's, so a tier claim written inside the surface it grades carries no authority. Contributor and governance surfaces are never runtime dependencies of a packaged SKILL.md; artifact-self-containment enforces that against the packaged runtime-contract view.
• Assertion needs an enforcement channel: a state surface carries why a thing is shaped as it is, not a present-tense claim about what the repo currently contains. A coverage roster, a count, an inventory of which files carry what, a restatement of what a check enforces — each is admitted only where a channel re-runs it. Without one it keeps asserting an earlier reading with present authority, and being correct today is not the test: what fails is the day it silently stops being correct and blocks work that contradicts it. Where such a claim is worth keeping, give it a guard; otherwise state what it was guarding against and point at the source a reader can check. A declared policy is not such a claim and this does not reach it: a sentence fixing what this project treats as true — what counts as consent, which reading governs, what a default means — is made true by standing on the surface. The test is whether the sentence could be false while the surface is unchanged; where it could, it is an assertion and needs a channel, and where it could not, nothing re-runs it because there is nothing to re-run. Declaring a policy buys no exemption for a state claim made alongside it — what else exists, what nothing else does, what every adopter holds — and that half answers here like any other.
• Static verification boundary: a verdict goes to the channel that can see what it judges. Contract structure — what a protocol's Definition block declares and what follows from it — goes to Lean: declarations carry it, theorem modules prove its consequences, and the audit enforces declaration policy. Text-level static checks hold only predicates whose verdict follows mechanically from authoritative state of artifacts Lean does not see — schema, identity, exact reference resolution, or deterministic producer/consumer wiring — and of the bridge that hands those artifacts to Lean. A text check retires only when its replacement rejects the same counterexamples, or when the requirement it guards is deliberately withdrawn. Context-dependent meaning, including whether an answer type is realized as the right user-facing gate under the accumulated context and utterance, routes to /realize or review. Static checks may verify that those channels are wired and fail closed; they do not stand in for the judgment.
• Ledger binding: this project's canonical ledger is the commit-message history on the default branch. A "then"-record — narrative, provenance, a trade-off, a rejected alternative — routes there at write time, in the commit that lands the change it explains. Issues and pull requests are where a proposal is raised and deliberated, not ledger surfaces: what a deliberation settles reaches the ledger through the commit that lands it, so a record left only in an issue or a PR body has not been written down. What a change in flight is being built toward is not a then-record and does not route here; Intent binding below states where it goes.
• Intent binding: a change in flight carries its direction — what is wanted, why, under which constraints, and what is still open — in the record that anchors its unit, never in the tree. This repository's home for that record is the issue the branch or pull request names, and the pull request body where no issue anchors the change; where that issue lives in a tracker a reader of this repository cannot reach, the pull request body carries the record's current text as well, with the issue named as its source. Where an issue anchors the unit, the branch names it by carrying its identifier, so a session resolves the record from the branch name alone rather than through this repository's name, and that branch carries one unit — every pull request opened from it is filed under the identifier it carries. Where none does, there is no identifier to carry and the record is reached through the pull request the branch opens. The record's shape and lifecycle are in docs/intent-record.md. Before changing anything on a branch, read the record the branch points at.
• Academic grounding: the protocols take their motive from Stoic epistemology (katalēpsis), Husserlian phenomenology (synthesis of identification, horizon), Gadamerian hermeneutics (fusion of horizons), and cognitive psychology (generation effect, retrieval practice, structure-mapping). Which literature grounds which protocol — and whether that grounding ever reached a shipped surface — is a then-record and lives in the git record, not on a state surface here. When grounding a claim in literature, check the primary source rather than answering from recall, and carry the verification strength with the claim: verified (primary source checked in this session), mostly (core claim checked, surrounding detail synthesized), or reconstructed (volume/issue/pagination came from recall and needs a spot-check before publication). Name the weakest link explicitly. An effect that failed replication is a design warning, never a quantitative law — and an absence claim reaches exactly as far as the search that grounds it, so state the scope searched rather than concluding from a partial read.
• Session-handoff routing: work crossing a session boundary is handed over as a pointer into the canonical record, never as a re-authored copy of it. The author supplies purpose/frame and entry points only; what to carry over is derived by the recipient from that purpose, grounded with /inquire where available or its equivalent grounding pass — the moment the author selects the items, the corruption a pointer avoids re-enters at small scale.
• Harness boundary: this project unfolds the epistemic layer only. Harness concerns — tool schema limits, permission models, execution channels, state mutation — fall outside what these instruction surfaces govern: no rule is authored here for them, and no claim is made here about where they are settled instead, which would assign a responsibility this project has no means to discharge. A protocol names its delegation point — where execution hands off — and stops there, naming the capability the handoff requires rather than a tool that could supply it, so a contract stays readable where that tool is absent. The reasoning behind the handoff lives in this clause, not in the protocol. A utility skill that delegates to an external CLI may carry that CLI's invocation in its own references/ as platform realization, outside its contract, while a protocol still names only its delegation point.
• Premise surface boundary: premise/ carries the general principle; this project's instance of it, and any claim whose meaning depends on this repository's artifacts or conventions, stays on a project surface. Both directions of crossing and how a crossing is detected are stated in premise/README.md §Adapting — read them there rather than mirrored here. What this clause settles is that a crossing found on this repository's surfaces is repaired rather than kept.