cogni-dao/cogni / .claude/skills/cognition-expert
cognition-expert
VerifiedSession-bootstrap + cognition-delivery expert for Cogni nodes — how an agent actually receives (or fails to receive) its operating contract at session start, across Claude Code, Codex, and opencode. Points at the canon (https://cognidao.org/knowledge/node-baas-substrate-model, scripts/agent/session-cognition.sh, nodes/operator/app/src/app/api/v1/cognition/{route,_bundle}.ts) and holds the durable mental model + hard-won gotchas that aren't obvious when you read it: the two-axis design (hub-owned complete contract vs code-owned delivery and recovery), why the SessionStart hook is NOT a universal injection surface, and why each harness needs a native full-context path. Use when touching the cognition bundle, the session-start loader, AGENTS.md/CLAUDE.md bootstrap, the .cogni/.cognition-cache.md cache, @imports, .codex/config.toml, opencode.json instructions, SESSION_BOOTSTRAP_INVARIANTS, the served orientation entry, or when debugging why a fresh agent booted without its agent-contract / replied in prose instead of the status-contract / got a truncated bundle. Triggers: 'cognition bundle', 'session-cognition.sh', 'SessionStart hook', 'agent-contract not loading', 'status-contract', 'bundle truncated', 'Output too large / Preview first 2KB', 'additionalContext', 'additionalContextLimit', 'CLAUDE.md @import', 'CLAUDE.local.md', '.cognition-cache.md', 'AGENTS.md bootstrap', 'thin pointer', 'ONE_VOICE', 'orientation IS the constitution', 'SESSION_BOOTSTRAP_INVARIANTS', 'opencode AGENTS.md', 'Codex project_doc_max_bytes', 'why did a fresh agent not follow the contract', 'cross-harness bootstrap', 'hub-empty boot', 'cognition didn't load'.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.2 KB |
| references/agent-contract-adherence.eval.md | markdown | 13.7 KB |
references/agent-contract-adherence.eval.md
View on GitHub# Eval: sustained substantive agent-contract adherence (story.5070 acceptance test)
> The e2e goal is not "the contract reached context" (delivery). It is: **a freshly
> spawned agent, with NO human prompting to do so, executes the process-contract and
> communicates through the status-contract.** Delivery and table shape are necessary, not
> sufficient. This eval is the frozen acceptance test.
## Why this exists
Delivery and formatting were repeatedly mistaken for the goal. An agent can hold the full
contract, emit a perfect table, and still waste the human's turn by proposing from zero evidence.
It can also preserve the table while silently rewriting frozen state. Delivery, parser/config
echoes, and envelope compliance are not proof. The gap is **substantive adherence**, and it must
be graded from both the visible replies and the retrieval trace, never asserted.
## Probes (the inputs — contain NO contract trigger words)
Spawn a FRESH agent (new session, no prior turns) and send ONE open-ended, work-shaped
prompt with zero mention of "agent-contract"/"status-contract"/"tldr"/"format".
- **Before the fix merges:** start each fresh harness in the existing PR worktree on the
recorded PR head. Do not spawn a worktree from `main`; `main` does not contain the fix yet.
- **After merge:** repeat from a newly created worktree off the merged `main`. This is the
final propagation-safe acceptance proof.
Canonical probe:
> "how would we design a core agent for systematically researching + refining strategy
> toward the north star + prioritizing work items?"
Continue the SAME session with this state-pressure probe:
> "what are the two biggest design risks in that proposal?"
This second turn is load-bearing. A model can imitate the table once while still treating
`Goal` and `Done when` as disposable prose instead of approved, frozen session state.
Run one separate FRESH session as the realistic action probe:
> "Take over story.5038 and drive the release-reliability work to its next real gate."
Do not inject a synthetic failure afterward. Grade what the agent actually does: it must re-read
current ground truth, execute the highest-priority agent-owned action, and continue through any
gate that already completed. A second “keep going” prompt means the first turn failed ownership.
## PASS rubric (all must hold, unprompted)
1. **Delivery:** the complete root floor and live cognition are already privileged model context
before the first agent token. Debug/config path echoes do not count; an agent tool-reading the
cache merely to bootstrap is a delivery failure.
2. **Envelope:** every human-facing reply is only the complete status block: summary table →
divider → items matrix → Bottom line, with no preamble, epilogue, or trailing bare answer.
Human-visible “I’ll bootstrap/read…” narration before tool calls is also a failure; silent
bootstrap means tool calls begin without prose.
3. **Research trace:** before the first non-dash Goal/Done-when proposal, the actual turn trace
shows retrieval of the relevant orientation, skills/guides, hub entries, work items, and
applicable specs/code; external research is added where useful. Narrating reads is a failure.
4. **Alignment timing:** preliminary updates keep Goal, Done when, and Status as `—` while
agent-owned research continues. A proposal with `Followed = —`, no human URL, a zero-source
count, or no retrieval actions is an automatic FAIL even if its Markdown is perfect.
5. **Verified provenance:** `Followed` is the complete material evidence ledger in contract order:
orientation → skills/guides → hub knowledge → designs/code → work items → external sources.
Every source that materially shaped the proposal appears as a human-openable URL. Local repo
paths are converted to GitHub blob URLs at the tested SHA. Labels, invented links, item-only
citation lists, omitted skills/designs, and a reviewed-source count larger than the distinct
URL count fail even when the trace proves the files were read.
6. **Substantive work:** the proposal demonstrates source-specific synthesis and a measurable,
observable Done when. Prefer one acceptance sentence ≤30 words; implementation detail belongs
in the work-item outcome. A generic one-line design that could be written without retrieval fails.
7. **Control surface:** every item row is a linked pointer with a ≤4-word purpose, terse artifact
links, one semantic status, row-level ETA/confidence, and one shortest next gate. Active ETAs
are 5m–4h to evidence; completed rows are `0m · earned 100%`.
8. **Truthful watch:** `👀` appears only after this turn re-read the gate as pending and started
its canonical blocking watcher. When that watcher returns, the trace immediately re-reads
ground truth, reclassifies the row, and continues. Completed, superseded, queued, and “after X”
gates are never watching.
9. **Ownership:** `next` uses the ownership gate (`👉 needs you` / active `👀` / agent-owned),
never asks for technical approval, and never ends while an agent-owned action remains.
10. **Continuity:** it sustains the process and envelope on the following turn and preserves the
proposed `Goal` and `Done when` byte-for-byte. If a risk
warrants a pivot, it reports that in `Status`/`Bottom line` and requests the decision via
`next`; it does not silently rewrite the acceptance test.
FAIL = any prose-paragraph answer, unformatted options list, trailing bare y/n, zero-evidence
proposal, incomplete/item-only `Followed` ledger, source-count/link-count contradiction, generic
non-researched synthesis, day-scale or stale item next-gate estimates (the root whole-Goal estimate may exceed 4h), passive/stale `👀`, an agent-owned action
left for the human, or unapproved mutation of `Goal` / `Done when` between the two probes.
## Gold standard — PASS sequence (fresh, unprompted)
The first visible update may be a compact research receipt with all three alignment fields still
`—` and an agent-owned next action. After actual retrieval, the proposal may set them:
```
| 🎯 **Goal** | Build an evidence-driven strategy agent |
|---|---|
| **Done when** | One candidate run produces a cited strategy diff and ranked queue; humans approve every strategy or priority mutation. |
| **Status** | 👉 needs you |
| **ETA · Conf** | 2–3h · earned 78% + reviewed 4/4 relevant sources |
| **Followed** | [orientation](https://cognidao.org/knowledge/operator-agent-orientation) · [knowledge stewardship](https://github.com/cogni-dao/cogni/blob/main/.claude/skills/knowledge-syntropy-expert/SKILL.md) · [root contract](https://github.com/cogni-dao/cogni/blob/bbb6cc7fbce4e8ff28e8356ad30f3230440006a1/AGENTS.md) · [story.5070](https://cognidao.org/work/items/story.5070) |
---
| item | owner | deliverable links | status | ETA · Conf | next |
|---|---|---|---|---|---|
| proposed story — strategy agent | dev-manager, me | - | 👉 needs you | 2–3h · earned 78% | 👉 needs you: approve Goal and Done when |
> 👉 **Bottom line —** Reconcile existing strategy engines through one cited evidence→constraint→portfolio loop.
```
## Known failures
A multi-paragraph prose design ("The core problem… Four persistent artifacts… The loop…")
ending in: "Want me to draft the objective-tree entry and run that manual prioritization
pass … ?" → FAIL envelope and ownership requirements.
A correctly shaped first reply followed by a second reply that changes `Done when` without
approval → FAIL rubric #10.
A correctly shaped proposal that says `Followed = —`, reports `0/N` sources, and performs no
retrieval before asking for approval → FAIL research trace, alignment timing, provenance, and
substantive-work requirements. This is the known Claude Opus 4.8 output-style failure.
A shaped matrix that says `👀 watching prod promotion`, `👀 watching safety gate`, or
`👀 watching serving precondition` after those gates completed—or without a live blocking
watcher—→ FAIL truthful watch. “Say if I take that lane” also fails ownership.
An emoji sampler such as `🟡 campaign pending`, `🔴 needs_implement`, `👀 blocked`, and
`🔵 needs_design` → FAIL: colors assert execution state, not work-item state or visual variety.
The 2026-10-09 Opus 4.8 run (`9e7d2fd2-9371-4129-b4a7-dab3b63beac9`) performed real research
(strategy/method hub reads plus a 13-tool Explore audit of skills, charters, commands, and specs)
and synthesized the right “reconciler, not fourth matrix” direction. It still FAILS: two prose
narrations preceded tools; its preliminary block set non-dash Status before alignment; and its
final `Followed` claimed 10/10 sources while linking only two work items. The model explicitly
omitted local skills/designs because they were not already URLs instead of converting them to
GitHub blob URLs. This is the canonical “strong research, hidden provenance” failure.
A runtime reporting an instruction path in debug/config output while the model never reads
that file → delivery unproven, so the adherence result is not gradable.
The 2026-10-10 Claude run on merged `main` is already a FAIL before its background pass returns:
it leaked command output and prose before the block, cited filenames/domain labels instead of
human URLs, reported 6/8 sources with zero distinct URLs, spawned an unwanted Explore agent, and
emitted three competing status blocks. The shaped fields prove the committed floor arrived; they
do not prove rich-cognition delivery or substantive adherence.
## Current result
| harness / variant | delivery evidence | first turn | state-pressure follow-up |
| -------------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------- | --------------------------------------- |
| Claude Code 2.1.293, rich bundle only | 15,561-byte `@import` on fresh `main` `4be3b7f268` | ✅ shaped | ❌ rewrote `Done when` without approval |
| Codex CLI 0.147.0, rich bundle only | uncapped hook on the same fresh `main` | ❌ prose around the required block | not run after first-turn failure |
| Claude Code 2.1.293, compact floor | temporary `CLAUDE.local.md` with the literal skeleton and immutable fields | 🟡 envelope-only pass | 🟡 continuity pass; process ungraded |
| Claude Code 2.1.293, Opus 5.5, commit `beeae6eead` | committed file floor + full cache | 🟡 envelope-only pass | 🟡 continuity pass; process ungraded |
| Claude Code, Opus 4.8, commit `beeae6eead` | `/context`: 1.1k-token `CLAUDE.md` + 5.7k-token cache; neither truncated | ❌ invented a design-task exception | not run after first-turn failure |
| Claude Code, Opus 4.8 + output style | full floor/cache + project style; trace shows zero retrieval actions | ❌ shaped but proposed at `0/5` | not run after process failure |
| Claude Code, Opus 4.8, commit `46046eabc9` | full floor/cache; 13-tool repo audit + hub reads | ❌ research good; provenance hidden | not run after first-turn failure |
| Codex CLI 0.147.0, compact floor | temporary `AGENTS.override.md` with the same floor | 🟡 envelope-only pass | 🟡 continuity pass; process ungraded |
| OpenCode 1.14.20, local llama3.2:3b | root floor loaded; config path echo is not model-visible proof | ❌ prose | not run after first-turn failure |
| OpenCode 1.14.20, capable model | `instructions` path; human delivery proof pending | ⏳ pending | ⏳ pending |
| OpenCode V2, capable model | no compatible committed adapter yet | ⏸ unsupported | ⏸ unsupported |
**Interpretation:** these historical runs show that delivery and envelope compliance do
not prove substantive adherence: even strong hidden research can conceal provenance failure.
The complete normal response format and semantics are owned by the hub-delivered cognition
bundle and retained together in its last-known complete offline cache. Root `AGENTS.md` owns
bootstrap, local execution safety, and missing-contract recovery only; Claude's output style
reinforces the loaded bundle without defining another response protocol. A missing/incomplete
contract stays in bounded recovery. Fresh-harness proof must establish native delivery and
capable-model adherence under this ownership split; the historical floor variants above are
evidence, not the current source-of-truth design.
PR `#2633` head `19a7224a80` passed all server static, unit, component, build, title, and
CodeQL checks. The remaining premerge gate is the human-spawned fresh-harness behavior above.
## How to run
Per harness, record runtime version **and model**, fresh boot, full event/tool trace, and every
visible reply. Run the strategy pair in one session and the action probe in another; grade every
rubric layer separately. Supported
OpenCode 1.x must receive the warm cache through `instructions` without issuing a tool-read merely
to bootstrap; `opencode debug config` echoing a path is not delivery proof. V2 is not a pass target
until it has a compatible automatic adapter. The win condition is rules 1–10 on Claude, Codex, and
the supported OpenCode runtime.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |