Skip to main content
Version: MVP

Stigmem documentation reconciliation demo

6 min readFor first-time operatorsUpdated 2026-05-19

What you'll do

Run Craik's first end-to-end demo — reconciling Stigmem documentation against observed runtime state without editing files by default. The workflow exercises case-file assembly, receipts, handoffs, memory proposals, contradictions, deterministic provider runs, and a task-scoped work-graph export.

This is the accepted release-acceptance workflow.

Every v0.x.0 candidate must pass this demo from a clean install.

What the demo does​

Registers Stigmem repo

As a Craik project.

Checks Stigmem node

Optional — if URL configured.

Creates a reconciliation task

Assembles a case file

Repository docs · ADRs · repo state · optional GitHub state.

Surfaces findings

Stale-risk and boundary issues.

Proposes doc updates

Public-safe suggestions only.

Records a receipt

Creates a handoff

Creates a memory proposal

Local — direct writes need a grant.

Opens a contradiction report

Local.

Runs provider paths

Deterministic OpenAI + Anthropic.

Exports work graph

Task-scoped.

Run it​

From a Stigmem repository checkout:

export CRAIK_HOME=/tmp/craik-demo
export CRAIK_STIGMEM_URL=http://127.0.0.1:18765
export CRAIK_STIGMEM_API_KEY=<api-key>

uv run --python 3.12 --extra dev craik demo stigmem-docs --repo-path .

For an offline local run without GitHub or live Stigmem:

uv run --python 3.12 --extra dev craik demo stigmem-docs --repo-path . --no-github

Offline = CI quickstart smoke path.

The --no-github form is the smoke path CI runs.

To limit deterministic provider execution to one provider while debugging:

uv run --python 3.12 --extra dev craik demo stigmem-docs --repo-path . --no-github --provider-id provider_openai

The command prints a craik.demo.stigmem_docs_reconciliation JSON payload.

Expected artifacts​

Artifact
Kind
ID
Project
deterministic
project_stigmem
Task
deterministic
task_stigmem_documentation_reconciliation
Case file
deterministic
case_stigmem_documentation_reconciliation
Receipt
deterministic
receipt_demo_stigmem_documentation_reconciliation
Handoff
deterministic
handoff_stigmem_documentation_reconciliation
Graph
deterministic
graph_task_stigmem_documentation_reconciliation
Local memory proposal
created
One.
Local contradiction report
created
One.
Provider runs
summary
OpenAI + Anthropic under provider_executions.

Inspect follow-up artifacts:

craik case show task_stigmem_documentation_reconciliation
craik contradictions list --task-id task_stigmem_documentation_reconciliation
craik memory list --task-id task_stigmem_documentation_reconciliation
craik handoff show task_stigmem_documentation_reconciliation
craik graph export --task-id task_stigmem_documentation_reconciliation

Boundary behavior​

ADRs and immutable paths are evidence.

The demo never edits repository files. Proposed documentation updates are emitted as reviewable suggestions in the JSON payload. Public docs do not receive internal-only labels, private planning names, local filesystem paths, or secrets.

Memory behavior​

The demo creates a local memory proposal. It does not write directly to Stigmem because direct durable memory writes require explicit policy grants. The JSON payload includes memory_write.status = "proposal_created" so release acceptance can verify the memory-write path remained explicit.

Provider behavior​

The demo exercises provider_openai and provider_anthropic through the deterministic provider-backed runner. These runs normalize provider payloads, record provider receipts, create run-scoped handoffs, and do not require live OpenAI or Anthropic credentials.

Expected output shape​

{
  "schema": "craik.demo.stigmem_docs_reconciliation",
  "status": "runnable",
  "case_file_id": "case_stigmem_documentation_reconciliation",
  "receipt_ids": ["receipt_demo_stigmem_documentation_reconciliation"],
  "handoff_id": "handoff_stigmem_documentation_reconciliation",
  "memory_proposal_ids": ["memprop_..."],
  "memory_write": {"status": "proposal_created"},
  "contradiction_ids": ["contradiction_..."],
  "provider_executions": [
    {"provider_id": "provider_openai", "run_status": "completed"},
    {"provider_id": "provider_anthropic", "run_status": "completed"}
  ],
  "work_graph_id": "graph_task_stigmem_documentation_reconciliation"
}

Troubleshooting​

Symptom
Cause
Fix
stigmem_backend_status.status = "not_configured" or "error"
offline backend
Demo still runs — these statuses are informational, not blocking.
GitHub unavailable
network
Use --no-github. The case file will include an open assumption or stale-risk warning that GitHub state was not loaded.
No ADRs discovered
repo layout
Confirm the repository has docs/adr/, or pass project registration options.
Not a Git repository
path
Pass --repo-path to a directory inside the Stigmem checkout.

What's next​

GuideQuickstartThe shorter introductory workflow.GuideConnecting StigmemSet up the optional live backend.GuideUsing case filesRead the case-file structure the demo produces.