Runtime instruction distillation workflow

2 min readReferenceUpdated 2026-05-19

What you'll find here

The 9-step pipeline that turns declared instruction files into reviewed, provenance-linked runtime constraints — and the operator rules that keep raw files from becoming automatic authority.

Raw instruction files are evidence, not authority.

Every step preserves provenance and keeps proposals inactive until a human approves them.

Workflow

1. Register declared sources with craik.instruction_source_registry.
2. Capture source identity with craik.instruction_source_snapshot.
3. Link extracted text with craik.instruction_provenance.
4. Create reviewable craik.distilled_instruction_proposal records.
5. Invalidate proposals when source snapshots change, go missing, are new, or are omitted from the current scan.
6. Open craik.contradiction_report records when authoritative instruction proposals conflict across sources.
7. Record craik.instruction_promotion_review decisions.
8. Create craik.promoted_instruction_constraint only for approved proposals.
9. Consume active constraints in case files, prompts, onboarding, and handoffs.

Operator rules

Inactive until approved

Proposed distillations are inactive until approved.

Visible but inactive

Stale, contradicted, rejected, and deferred distillations remain visible but inactive.

Override required

Approving stale or contradicted proposals requires an explicit override rationale on the promotion review.

Audit trail required

Active constraints retain source ID, source snapshot ID, provenance IDs, evidence IDs, and review links.

Stale-risk warnings

Case files and onboarding surface stale-risk warnings instead of treating stale distillations as facts.

CLI lifecycle

craik instructions registers sources, lists proposals, records approval decisions, and shows provenance through the active operator session.

Forward to next agent

Handoffs carry active instruction constraint IDs forward so later agents can audit what shaped the run.

Fixtures

The contract fixture file includes examples for the core v0.4.0 records.

craik.instruction_source

craik.instruction_source_registry

craik.instruction_source_snapshot

craik.instruction_provenance

craik.distilled_instruction_proposal

craik.instruction_promotion_review

craik.promoted_instruction_constraint

Runtime tests cover stale invalidation, contradiction handling, promotion review, and active-context consumption.

What's next

ReferenceInstruction sourcesRegistry boundaries, categories, and stale invalidation.ReferenceInstruction approvalReview receipts, override rationale, and active constraints.ReferenceInstruction distillation viewThe operator surface that audits proposals.ReferenceSchema referenceAll instruction-related contract shapes.