Runtime Contracts
What you'll find here
The JSON-shaped catalog of every persisted Craik contract — task request, project profile, policy envelope, capability grant and receipt, case file, intent lock, agent role, worker result, handoff, memory proposal, memory-backend capabilities, contradiction report, work-graph event. Use this when you need to know the wire shape an adapter or plugin must produce.
The product spine.
Craik is built around stable, versioned contracts. Adapters, agents,
memory backends, and future plugins integrate through them. The
typed Python implementation lives in src/craik/contracts/
and is documented in Schema reference.
Contract examples below use JSON-like shapes for clarity. The shipped implementation defines them as strict Pydantic models with validation.
Versioning
Every persisted contract should include:
{
"schema": "craik.<contract-name>",
"version": "0.1.0"
}
Breaking changes require a new version and migration path.
Task Request
Defines work requested by a user, system, or another agent.
{
"schema": "craik.task_request",
"version": "0.1.0",
"id": "task_...",
"title": "Review documentation against implementation state",
"objective": "Find stale docs and propose updates.",
"project_id": "project_...",
"requested_by": "user:...",
"priority": "normal",
"mode": "plan|review|implement|verify",
"constraints": ["Do not edit ADRs."],
"expected_outputs": ["case_file", "findings", "handoff"],
"created_at": "..."
}
Project Profile
Defines a project Craik can reason about.
{
"schema": "craik.project_profile",
"version": "0.1.0",
"id": "project_...",
"name": "stigmem",
"repo": {
"type": "git",
"local_path": "/path/to/repo",
"default_branch": "main"
},
"docs": {
"paths": ["README.md", "docs/"],
"immutable_paths": ["docs/adr/"]
},
"memory": {
"backend": "stigmem|local|ephemeral",
"scope": "team"
},
"policies": ["policy_no_adr_edits"]
}
Policy Envelope
Defines what the runtime is allowed and obligated to do.
{
"schema": "craik.policy_envelope",
"version": "0.1.0",
"id": "policy_...",
"task_id": "task_...",
"actor": "agent:...",
"profile": "strict|trusted-local|automation|custom",
"fail_open": false,
"allowed_capabilities": ["repo.read", "repo.write.docs", "shell.test", "memory.propose"],
"denied_capabilities": ["repo.write.adr", "git.force_push"],
"approval_required": ["github.create_pr", "memory.write.policy"],
"verification_required": ["git.diff_check"],
"handoff_required": true,
"receipt_required": true
}
Capability Grant
Represents a concrete permission for an action family.
{
"schema": "craik.capability_grant",
"version": "0.1.0",
"id": "grant_...",
"task_id": "task_...",
"capability": "repo.write.docs",
"target": {
"repo": "eidetic-labs/stigmem",
"paths": ["docs/**", "README.md"],
"exclude": ["docs/adr/**"]
},
"operations": ["read", "write", "patch"],
"expires_at": "...",
"reason": "Documentation reconciliation task.",
"approved_by": "user:..."
}
Capability Receipt
Records important actions.
{
"schema": "craik.capability_receipt",
"version": "0.1.0",
"id": "receipt_...",
"task_id": "task_...",
"actor": "agent:...",
"capability": "shell.test",
"target": "uv run pytest node/tests/plugins",
"policy_profile": "strict",
"fail_open": false,
"reason": "Validate plugin registry docs against test suite.",
"result": {
"status": "passed",
"summary": "43 passed, 12 skipped"
},
"created_at": "..."
}
Case File
The case file is assembled before execution.
{
"schema": "craik.case_file",
"version": "0.1.0",
"id": "case_...",
"task_id": "task_...",
"objective": "...",
"policy_envelope_id": "policy_...",
"intent_lock_id": "intent_...",
"facts": [],
"docs": [],
"adrs": [],
"repo_state": {},
"github_state": {},
"recent_handoffs": [],
"stale_risks": [],
"contradictions": [],
"verification_plan": []
}
Intent Lock
Captures accepted task intent and scope boundaries before execution.
{
"schema": "craik.intent_lock",
"version": "0.1.0",
"id": "intent_...",
"task_id": "task_...",
"original_request": "Review documentation against implementation state",
"objective": "Find stale docs and propose updates.",
"accepted_interpretation": "Review docs and propose updates only.",
"in_scope": ["README.md", "docs/"],
"out_of_scope": ["ADR edits"],
"allowed_autonomy": ["Inspect repository files"],
"stop_conditions": ["The task requires changing immutable docs"],
"scope_change_rules": ["Ask before expanding beyond documentation review"],
"created_at": "..."
}
Agent Role Manifest
Defines what an agent role is for.
{
"schema": "craik.agent_role",
"version": "0.1.0",
"id": "role_docs_reviewer",
"name": "Docs Reviewer",
"purpose": "Review docs against implementation state.",
"allowed_modes": ["review"],
"required_context": ["case_file", "policy_envelope"],
"default_capabilities": ["repo.read", "memory.read"],
"output_contract": "craik.worker_result"
}
Worker Result
Specialists return typed results.
{
"schema": "craik.worker_result",
"version": "0.1.0",
"id": "result_...",
"task_id": "task_...",
"worker_role": "Docs Reviewer",
"status": "completed|blocked|failed",
"findings": [],
"artifacts": [],
"proposed_facts": [],
"open_questions": [],
"receipts": []
}
Handoff
The durable run summary.
{
"schema": "craik.handoff",
"version": "0.1.0",
"id": "handoff_...",
"task_id": "task_...",
"project_id": "project_...",
"intent_lock_id": "intent_...",
"agent": "agent:...",
"status": "completed|incomplete|blocked|failed",
"summary": "...",
"self_audit": {
"schema_validated": true,
"redaction_reviewed": true,
"receipts_reviewed": true,
"assumptions_reviewed": true,
"validation_recorded": true,
"policy_exceptions_disclosed": true,
"notes": []
},
"completed_actions": [],
"files_changed": [],
"artifacts": [],
"commands_run": [],
"tests_run": [],
"assumptions": [],
"context_debt": [],
"policy_exceptions": [],
"facts_learned": [],
"facts_invalidated": [],
"contradictions_opened": [],
"risks": [],
"next_steps": [],
"receipt_ids": [],
"memory_proposal_ids": [],
"created_at": "..."
}
Memory Proposal
Agents propose memory updates through a reviewable structure.
{
"schema": "craik.memory_proposal",
"version": "0.1.0",
"id": "memprop_...",
"task_id": "task_...",
"operation": "add|update|invalidate",
"fact": {
"entity": "repo:...",
"relation": "codex:current_state",
"value": "...",
"source": "agent:...",
"confidence": 0.95,
"scope": "team",
"trust_class": "observed|reported|inferred|policy|external|stale-risk"
},
"evidence": [],
"requires_approval": true,
"status": "pending|approved|rejected",
"decision_reason": null,
"decided_by": null,
"decided_at": null
}
Memory Backend Capabilities
Craik should persist detected backend capabilities.
{
"schema": "craik.memory_backend_capabilities",
"version": "0.1.0",
"backend": "stigmem",
"node_url": "http://127.0.0.1:18765",
"node_id": "stigmem:node:...",
"auth_required": true,
"required": {
"health": true,
"metadata": true,
"fact_write": true,
"fact_query": true,
"fact_get": true,
"fact_provenance": true
},
"optional": {
"recall": true,
"conflicts": true,
"source_attestation": "warn|enforce|off",
"federation": false
},
"checked_at": "..."
}
Contradiction Report
Captures incompatible assertions.
{
"schema": "craik.contradiction_report",
"version": "0.1.0",
"id": "contradiction_...",
"facts": ["fact_a", "fact_b"],
"summary": "Docs say feature is planned; implementation shows it is merged.",
"affected_artifacts": [],
"proposed_resolution": "...",
"status": "open|resolved|ignored",
"owner": "user:..."
}
Work Graph Event
Events update the graph.
{
"schema": "craik.work_graph_event",
"version": "0.1.0",
"id": "event_...",
"task_id": "task_...",
"type": "created|depends_on|verified_by|contradicts|supersedes|implements|blocks",
"from": "node_id",
"to": "node_id",
"metadata": {},
"created_at": "..."
}