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 — routes there at write time, in the commit that lands the change it explains. A rejected alternative and why it was set aside stay on the decision line of the unit's record (Intent binding below), where a later session meets a re-raise first; the commit that lands the change cites that line by its id rather than restating it. 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.

Protocol Index

This section indexes the protocol catalog rather than mirroring it: it points to where each protocol fact lives so a running conversation can fetch it on demand. (The rest of this file still explains the repo's machinery and holds the maintainer-facing umbrella statement, per docs/mission-bridge.md.)

This repository packages epistemic dialogue protocols as plugin skills; each transforms a specific interaction deficit into a resolution object (e.g. ContextInsufficient → SufficientContext via /inquire).

Runtime Contract

• Runtime users interact with packaged SKILL.md files plus plugin metadata. Discovery metadata routes; SKILL.md carries the normative user contract.
• SKILL.md must be self-contained. Do not require runtime readers to chase contributor-only docs, axiom identifiers, rule paths, design-philosophy documents, or mission/vision prose to understand the skill contract.
• Prescriptive changes that affect protocol behavior must be compiled into the relevant SKILL.md Rules sections.
• Claim strength differs by surface and the difference is load-bearing. The packaged SKILL.md is the normative contract. A plugin description is routing metadata written under a length budget, so it is judged for routing clarity rather than semantic completeness. How a host realizes the contract is platform realization and not part of it — a protocol that looks broken on another host may simply be satisfied differently there. Model judgment and soft safeguards are advisory, carrying no runtime guarantee for a reader to design against.
• The formal blocks are part of the runtime-normative SKILL.md contract — they type the prose and constitute protocol identity, not contributor spec. Their anatomy (a contributor guide about the blocks, distinct from the blocks themselves) is documented in docs/structural-specs.md.

Progressive Disclosure

• Keep this file focused on high-risk decisions and commands needed before search.
• Do not mirror long protocol descriptions, utility-skill internals, CI workflow details, or full architecture trees here when a linked source is authoritative.
• Use README.md, docs/, .claude/rules/, .claude/principles/, .claude/skills/verify/, and per-skill SKILL.md files as the next layer of detail.
• When adding guidance, first ask whether rg, find, or a linked doc would recover it cheaply at the point of need. If yes, add a pointer rather than copying the content.

Design Placement

• .claude/rules/ is for prescriptive rules that must be active without a reader fetching them, unscoped when they bind at per-turn runtime. A paths scope narrows delivery to the moment a matching file is open, so a rule whose moment is narrower than the session does not charge every session for it — but that scoping is one host's optimization and never the only route: keep a platform-neutral pointer on a surface every intended reader reaches at or before the rule binds.
• .claude/principles/ is for lazy-loaded architectural principles.
• Grounded exposition, investigation writeups, and evidence reviews go to the deliberation surface (issue or PR body), never to a file under docs/ — they are then-records, and nothing on a state surface re-runs them; what the deliberation settles reaches the ledger through the commit that lands it.
• A contributor reference serving one skill lives in that skill's own references/, so it loads when the skill is triggered rather than when someone remembers it exists. docs/ keeps what no single skill owns — a reference cited from several surfaces at once, or a contributor surface a public README reader is sent to.
• New rule proposals require a placement judgment against the existing docs/rules surface; do not add a runtime rule just because a concept is philosophically attractive.

Development

• Node.js 22+ is required; CI pins Node 22.
• Plugin code uses Node.js standard library only.
• Static checks: see ## Verification below for the command.
• Tests: node --test $(git ls-files '*.test.js' '*.test.mjs' | grep -v '^.claude/skills/verify/scripts/static-checks.test.mjs$')
  • .claude/skills/verify/scripts/static-checks.test.mjs runs the verifier over the live tree, so it takes its own node --test invocation for the same reason /verify does — see the concurrency note under ## Verification.
• Packaging: node scripts/package.js [--dry-run]
• Changelog: node scripts/generate-changelog.js
• Installer: scripts/install.sh; README.md is the source of truth for the install set.

Verification

Run /verify before commits. The decisive static verification command is:

node .claude/skills/verify/scripts/static-checks.js .

Do not run scripts/package.test.js concurrently with static protocol verification when liveness tests may mutate live SKILL.md files.

After protocol predicate refactors, run a lexical sweep for stale vocabulary using the verification guidance rather than hardcoding predicate inventories here.

Details: .claude/skills/verify/references/verification.md.

Editing Conventions

• Git and editing rules are auto-loaded via .claude/rules/editing-conventions.md.
• Any protocol change requires the relevant plugin.json version bump plus /verify.
• Co-change patterns are tracked in .claude/skills/verify/references/co-change.md.
• When editing protocol prose, prefer positive predicates over negated anchoring, preserve composability while making morphism completion explicit, and verify the runtime contract view rather than source prose alone.
• For protocol edits, run a semantic-closure sweep whenever changing terminal conditions, state transitions, or result types. Align TYPES, PHASE TRANSITIONS, LOOP, CONVERGENCE, TOOL GROUNDING, and Rules so every new condition has a type, guard, state update, termination path, and result equation. Static checks do not prove this; manually verify before commit.
• A paths-scoped file under .claude/rules/ opens by stating the moment it binds, so that a reader arriving without it auto-loaded can tell when it fires; write that opening when authoring one. Read the ones scoped to protocol SKILL.md before editing a protocol, and .claude/rules/instruction-surface-revision.md before changing this file or a rule. A host that loads them on the matching path delivers them without this bullet; a host that does not is why the bullet is here.

Delegation Notes

Protocol-specific delegation notes belong in the relevant SKILL.md. Actual subagent use remains subordinate to the active runtime/tool policy and requires explicit user authorization when that policy requires it.