The Governance Kernel

Most AI coding tools live inside a chat thread: work exists as messages, state evaporates when the session ends, and "approval" means typing looks good. SDTK inverts that. At its center is a governance kernel — a small, durable core that turns multi-step AI work into something you can pause, resume, audit, and approve like real engineering.

What the kernel is

The kernel (shipped in SDTK-AGENT) is a stateless CLI over a file ledger:

• Workflow DAG — a JSON graph of task and human_gate stages with depends_on edges, optional skip_when conditional-skip rules, retry/timeout policy, and declared output paths.

• Run ledger — every run lives at .sdtk/agent-runtime/runs/<run_id>/:

  runs/<run_id>/
  ├── request.md        # the original goal
  ├── workflow.json     # the DAG being executed
  ├── runtime-map.json  # role → adapter bindings
  ├── state.json        # current machine state
  ├── events.ndjson     # append-only event log
  ├── tasks/            # dispatched task records
  ├── evidence/         # evidence files per task
  ├── approvals/        # human gate decisions
  └── reports/          # rendered run reports

• Pure state machine — a reducer computes state + evidence + approvals → next state. No daemon, no in-memory session. Any process that can read the ledger can continue the run.

• Adapters — the kernel never executes work itself; it dispatches through an adapter contract (manual, shell, sdtk-cli, hermes-kanban) with allowlists and path containment. See Hermes Adapter for the fail-closed story.

Why files, not sessions

Durability. Close the terminal mid-run. state.json and events.ndjson hold everything. sdtk-agent run continue picks up exactly where the run blocked — tomorrow, on the same machine, from a different shell.

Auditability. The event log is append-only NDJSON. Every task dispatch, evidence intake, gate decision, and state transition is a line you can replay. sdtk-agent run report renders it into a human-readable report.

Human authority. human_gate stages block everything downstream until a named person decides:

sdtk-agent gate approve --run-id <run_id> --gate <gate_id> --approved-by <name>

The approval is a file in approvals/ — attributable and permanent, not a chat message.

Cost control. run start only creates the ledger; nothing executes until you run continue. A run can fan out into many agent tasks, so the kernel is deliberately propose-then-confirm.

The same idea everywhere

The kernel is the sharpest expression of a pattern every SDTK toolkit follows — state as files in your repo, transitions gated by humans, claims backed by evidence:

Layer	File-backed state	Gate
SDTK-SPEC	Discovery docs, PRD, specs, SHARED_PLANNING.md	Phase gates PM → BA → ARCH → DEV → QA
SDTK-DESIGN	Briefs, screen maps, prototype, review evidence	Design review before handoff
SDTK-CODE	Plans, guardrails, review packets	Review gate before ship
SDTK-OPS	Deployment plans, verification evidence	ops-verify closes every journey
SDTK-WIKI	Knowledge graph + docs pages	Safe-mode compile, --apply to commit
SDTK-AGENT	The run ledger itself	human_gate stages

Local-first, precisely

Ledgers, artifacts, graphs, and reports are files in your repository — they don't live on our servers. External model/API/runtime calls happen when you invoke your AI runtime (running /orchestrator in Claude Code, dispatching an agent task, asking sdtk-wiki ask). SDTK governs those calls; it doesn't hide them.

Where to go next

Workflows & GatesHow DAG stages, dependencies, and human gates compose.

Run the kernelA hands-on durable agent run, gate approval included.

SDTK-AGENT guideThe toolkit that ships the kernel.