tik

No fold step reads the future — the claimed clock is clamped to the evaluated clock

Wed, 05 Aug 2026 00:00:00 +0000

ADR 0022: No fold step reads the future

Decision

Every step of evolve evaluates guards at the event’s own claimed :event/at, clamped to the read’s evaluated now: min(at, now). No step may act as though more time has passed than actually has at the moment of the read.

Derivation stays exactly what it was — a pure function of (events, now) — and reduction order is untouched: events still fold in (at, id) order, and only the instant each step’s guards are evaluated at is clamped. Logs whose events are all dated at or before the read derive byte-for-byte as they did before, so the clamp changes the answer only for the case it exists to fix.

Coordination-free horizontal scaling — no leader, no lock, no consensus

Tue, 14 Jul 2026 00:00:00 +0000

ADR 0021: Coordination-free horizontal scaling

Decision

tik’s second law, standing beside derived-beats-declared: every operation must be correct on arbitrarily many replicas that share nothing and reconcile only by eventually unioning their grow-only, content-addressed event sets. No feature may require leader election, a distributed lock, a quorum/consensus round, or any synchronous cross-replica coordination to be correct.

This is not an aspiration to bolt on later; it is a constraint every feature is checked against now, exactly like the first law. Three consequences are load-bearing and must stay true:

Artifacts — the hash is in the trust domain, the blob is not

Thu, 09 Jul 2026 00:00:00 +0000

ADR 0014: Artifact semantics

Decision

An :artifact/attach event binds a path label to a content hash. The permanent answers:

The hash is inside the trust domain; the blob is not. The event (signed, hashed, parented) proves that an actor attached exactly these bytes at a claimed time. The bytes themselves are payload: stored by hash, transferred lazily, verifiable on arrival.
Blobs are immutable — a “changed” artifact is a new hash attached by a new event; the old attachment remains history.
Deletion removes availability, never history (GDPR, leaked secrets). The event stands, the hash stands, and verify L3 reports verifiable absence — “blob absent” is a truthful verification outcome, not a failure to be papered over. This is a designed property; transcripts from real environments contain things that must be deletable (PLAN §13).
Metadata is descriptive, never authoritative. The path label, media type, and any annotations are the attaching actor’s claims about the bytes — disputable like any claim — not properties the kernel vouches for. A guard trusting path = "repro/…" trusts the attacher’s labeling; when it matters, processes require an attestation about the content, not a filename shape (PLAN §18, evidence flooding).
Two hashes are two artifacts. Logical identity across encodings (“the same report as PDF and HTML”) is not a kernel concept; if a process needs it, it is asserted as a fact and carries its asserter’s accountability.

Context

Artifacts are where the trust domain touches arbitrary external bytes, and every mistake here has the same shape: attributing to the blob a guarantee that only the event about the blob carries. Keeping the boundary explicit — evidence about bytes vs. the bytes — is what lets blobs be deleted, lazily transferred, and quota-limited without any of it touching the integrity story.

Canonical serialization is a versioned wire protocol

Thu, 09 Jul 2026 00:00:00 +0000

ADR 0008: Canonical serialization is a protocol boundary

Decision

Canonical EDN is a versioned wire protocol, not an implementation detail. A format version defines the complete byte representation; implementations MUST NOT serialize equivalent structures differently. The permanent answers, per format-version 1:

Numbers: integers only, printed as longs. Floats, ratios, and bigdecimals are rejected at emit — no numeric normalization exists because no ambiguous numerics are admitted.
Keywords and symbols: printed textually (:ns/name, name); namespaces are part of identity forever.
UUIDs: lowercase textual form, tagged (#uuid "...").
Timestamps: UTC, truncated to millisecond precision, tagged (#inst "..." in java.time.Instant ISO-8601 form).
Maps: entries sorted by the canonical encoding of the key (never by a host-language print function — pr-str was tried and is identity-hash-unstable for types without a print-method).
Sets: members sorted by their canonical encoding.
Vectors and seqs: preserve order ([..], (..)).
Unknown types: rejected at emit, never “best-effort” printed.
Whitespace: single space between elements; no other whitespace.

Any change to canonical output — however “equivalent” — is a format-version bump.

Conformance is defined by the corpus, the laws, and normative sweep semantics

Thu, 09 Jul 2026 00:00:00 +0000

ADR 0018: Second-implementation conformance

Decision

The corpus, not the Clojure, is the definition of tik. A conforming implementation must agree on all five layers:

Canonical bytes (ADR 0008): identical serialization for every supported value, byte for byte.
Event validity (ADR 0004, 0009): minting rules (mandatory parents, root uniqueness), totality over unknown types.
Reduction: identical ticket state from identical event sets — ordered by (at, id), deduplicated by id, handler semantics per the closed vocabulary.
Fixpoint semantics: the synchronous sweep is normative (ADR 0005) — all enabled stages added per sweep against the sweep-start snapshot. Fire-one-stage-at-a-time iteration is nonconformant even on stratification-clean processes; spec/ChaoticFixpoint.tla exhibits the divergence and the corpus case sweep-order-negation pins the correct result.
Explain laws: soundness (every block re-derivable, nothing speculative) and completeness (every unreached-with-prereqs-reached stage appears) — the data contract of ADR 0016.

Conformance is demonstrated by passing the corpus and the property laws, not by code review of the implementation.

Definition hash is identity; publication signatures are authority

Thu, 09 Jul 2026 00:00:00 +0000

ADR 0015: Process definition trust

Decision

A process definition’s hash is its identity (ADR 0002/0006); a detached signature sidecar over its canonical bytes is publication authority — who vouches that this definition is an approved rule set. The two are independent: an unsigned definition is still a definite, pinnable identity; a signature adds “and Compliance published it”.

The permanent answers:

Signatures are over canonical definition bytes (the ADR 0007 pattern), never over the hash string alone — signing a name instead of content is how substitution bugs are born.
Multiple signatures accumulate as sidecars (author, security review, compliance) without touching identity.
Who may publish is deployment policy, expressed as which publisher keys a deployment accepts — checked at ticket creation and by lint/CI, not by the kernel at derivation time: a ticket pinned to a definition derives under it regardless, because reproducibility of past conclusions must not depend on today’s trust list.
Revocation is prospective: revoking a definition (an attestation by its publisher) means “create no new tickets under this; migrate existing ones”. Existing tickets keep deriving under their pin — ADR 0002’s reproducibility — while lint, next, and migration sweeps surface them as work. Retroactive invalidation would rewrite what past conclusions meant, which is the exact audit hole pinning closes.

Context

A process definition is executable governance: publishing a bad one is the definition-poisoning attack (PLAN §18), and the kernel is correctly neutral about it — the verifier proves correct evaluation, not good policy. What the kernel can do is make authorship and endorsement of definitions first-class evidence, so “who allowed these rules” is a log question with the same answerability as “who asserted this fact”.

Derived material may be cached only if disposable and untrusted

Thu, 09 Jul 2026 00:00:00 +0000

ADR 0013: Derived state is never persisted as authoritative

Decision

Derived material — stages, frontiers, explain output, totals, indexes, reduction summaries — may be cached, indexed, or materialized only if it is disposable and verification never trusts it. Deleting any cache must be a no-op for correctness. verify re-derives from the log, always; it never reads a cache, an index, or a checkpoint as input.

Checkpoints (a verified reduction summary pinned to a head) are untrusted accelerators: an implementation may use one to skip work, but replay always outranks it, and any disagreement is resolved in favor of replay.

Effects observe derivation; transport is not a domain concept

Thu, 09 Jul 2026 00:00:00 +0000

ADR 0019: Effects observe derivation

Decision

Derivation is pure; effects observe derivation. An effect planner watches derived frontier transitions and fires outbound integrations — webhooks, mail, chat — under these rules:

Delivery never touches truth. Success or failure of an outbound call changes nothing in any ticket’s log.
No transport event types, ever. There is no :webhook/sent, no :email/delivered, no :kafka/published — transport is not a domain concept. When the business outcome matters (“customer was notified”), it re-enters as a fact or attestation asserted by the notifying actor, accountable like any claim.
Idempotency is structural, not stateful: the effect key is the content hash of (ticket, stage, sink identity), so replays and re-derivations dedupe without a delivery-state machine — and any delivery ledger an effect runner keeps is disposable porcelain (ADR 0013). The key deliberately excludes the head: a head moves with every appended event, so keying on it would re-notify the same stage on every subsequent write — the opposite of dedup.
Structural dedup is scoped to one runner’s ledger, not to the estate. The key is stable across replicas, but the ledger recording which keys were sent is local, so N runners observing the same transition deliver N times. Under the horizontal scaling ADR 0021 calls preferred, that is the narrow per-pipeline delivery lease ADR 0021 admits as its one exception — the only place coordination is allowed, and it serializes DELIVERY, never the log. Until a runner takes such a lease, run exactly one effect runner per estate.
Inbound is symmetric and already covered: an external system’s webhook is just another actor whose bridge validates, authenticates, and appends signed events (ADR 0001, 0011).

Context

The first integration author under deadline pressure will want to record “the webhook succeeded” in the ticket — and each such record is a transport detail promoted to domain truth, the exact accretion path by which event vocabularies grow to CommentEdited/EmailSent size. The rule that prevents it is cheap and total: effects are a lens with side effects, downstream of truth, never upstream.

Events are never deleted; blobs may be; nothing is compacted into authority

Thu, 09 Jul 2026 00:00:00 +0000

ADR 0017: Deletion, retention, and compaction

Decision

Events are never deleted. History is the truth substrate; an event store that forgets events is corrupt (missing parents, ADR 0004), not compact.
Blobs may be deleted. Deletion removes availability, never history: the attach event and hash remain, and verify L3 reports verifiable absence (ADR 0014). This is the designed answer to GDPR erasure, leaked secrets, and retention policy — personal data and sensitive payloads belong in blobs, precisely so they are deletable.
No cryptographic compaction of event history. Any “verified reduction summary” is derived state: usable as an untrusted accelerator, never as a replacement for the events it summarizes (ADR 0013). A store that can no longer replay is a store that can no longer verify.

Context

Long-lived append-only systems always eventually ask “can we delete old events?”, usually citing storage cost or privacy law. The two motives have different correct answers, and blurring them is the danger: storage cost is a payload problem (blobs, quotas, lazy transfer — events themselves are tiny), while privacy law is about content, which is why deletable content lives behind hashes rather than inside events. The design keeps a sharp line: verification reports absence; it never rewrites truth.

Explain's structured reasons are the stable API; renderings are not

Thu, 09 Jul 2026 00:00:00 +0000

ADR 0016: Explain stability contract

Decision

Explain output is structured data with stable semantics; rendering is not stable. Clients — web UIs, MCP agents, chat surfaces, dashboards — bind to the reason data (:reason keywords like :fact/missing, :role/unsatisfied, plus their payload keys), never to English strings.

The compatibility rules:

Reason keywords and their payload keys are versioned with the guard vocabulary: a guard-vocab version enumerates exactly which reasons can occur (a closed vocabulary implies a closed reason set).
New reasons appear only additively under a version bump; existing reason keywords never change meaning or payload shape within a version.
The block structure (:stage, :satisfied, :missing, :blocks, :hint) is part of the same contract, backed by the property-tested soundness/completeness laws (PLAN §8).
Renderings may change freely — wording, ordering, localization, ranking, capability-based redaction (IDEAS) are all lens behavior. A client that greps CLI text has no compatibility claim.

Context

Explain is the product surface, which makes it the API everyone will integrate against. Without this contract, MCP and UI clients would inevitably couple to English strings, and improving a message would become a breaking change — freezing exactly the layer that must stay free to improve. The kernel-speaks-data rule (PLAN §5) already provides the mechanism; this ADR adds the promise.

Signatures establish authorship; authorization is derived

Thu, 09 Jul 2026 00:00:00 +0000

ADR 0010: The authority model

Decision

Signatures establish authorship. Authorization is derived — from identity attestations, role facts, and process guards. The kernel never interprets a signature as permission by itself; there is no code path where “validly signed” alone unlocks anything.

The permanent answers:

Revocation is prospective, not retroactive. A key revocation is an attestation event. Signatures made before revocation remain valid authorship claims forever — the log is immutable and history does not get rewritten (ADR 0002’s reproducibility applies to trust too). Whether the author was authorized is evaluated against role validity at the relevant time.
Role membership is time-dependent. “Alice was a triager when she triaged” is the derivable question; the three clocks (PLAN §5) decide which “when” — claimed by default, witnessed where the process demands it.
Delegation is an attestation with scope and expiry (:valid-until, capability), including human→agent delegation. An authority chain (Alice ← Bob ← Compliance) is derivation over delegation attestations.
Key compromise does not invalidate history; it changes interpretation. The response is evidence: revoke (attestation), dispute facts the compromised key asserted, and let derivation regress what depended on them. A lens may flag “signed by a later-revoked key”; the kernel keeps the record.

Context

Someone will eventually read [:signed-by :manager] and conclude the signature system is the authorization system. It is not: that guard expands to authorship (the signature) plus role derivation (is the author in the role, at the right time, per the identity attestations). Losing this distinction is how “it’s signed” quietly becomes “it’s approved” — the sidecar-discovery footgun (ADR 0007) and role-decay attack (PLAN §18) are both instances.

The EventStore contract every backend must honor

Thu, 09 Jul 2026 00:00:00 +0000

ADR 0020: The EventStore contract

Decision

Any storage backend (file/git today; SQLite next; anything later) is valid iff it honors this contract:

Append-only: no operation deletes or mutates an event, ever (ADR 0017; blobs are separate and deletable, ADR 0014).
Append is idempotent by id: appending an already-present event id is a no-op — union semantics are the store’s job to preserve, which is what makes replica merge trivial.
Events are returned unordered: the reducer orders by (at, id); a store that returns “helpful” ordering invites callers to depend on it (ADR 0004: parents are not ordering either).
has-event? is the reconciliation primitive: sync between any two stores is git-style have/want set reconciliation over event ids; a server is just a well-connected replica.
The store holds bytes, not interpretations: no store may index its way into authority — any derived index it keeps is disposable (ADR 0013). For the file store this is literal (sha256sum(file) = filename = id, ADR 0007); other backends must preserve the exact canonical bytes so the same guarantee is testable (events(id TEXT PRIMARY KEY, bytes BLOB) — never a parsed-columns schema that re-serializes on read).

Context

The storage seam is where “just this once” optimizations concentrate: a parsed-column schema that re-serializes (hash fork risk, ADR 0008), a store that orders by insertion (hidden coupling), a cleanup job that prunes “obsolete” events (corruption, ADR 0004). Writing the contract before the second backend exists means SQLite gets built against rules, not against the file store’s incidental behavior.

The log admits all well-formed claims; trust is evaluated, not filtered

Thu, 09 Jul 2026 00:00:00 +0000

ADR 0011: Event existence vs. participation in truth

Decision

The log contains all received well-formed claims. Derivation consumes the whole set. Trust is never a silent reducer filter — it is expressed where it is visible: in guards (:signed-by, and any future trust-conditions) and in the verify ladder (L1 authenticity). A fact asserted by an actor lacking the required role exists, is derived over, and fails the guard with an explainable reason (:role/unsatisfied, naming the actor) — it is never treated as nonexistent.

Three clocks; claimed is the default; the clock is part of the guard

Thu, 09 Jul 2026 00:00:00 +0000

ADR 0012: Time semantics are part of the process contract

Decision

Three clocks, never conflated:

Claimed — :event/at, asserted by the actor, inside the hashed region.
Observed — witness countersignature over a head: “this history existed no later than T”.
Evaluated — the explicit now argument to derivation; never an implicit system clock.

Claimed is the default clock for guards. A guard opts into observed time with {:clock :witnessed} where backdating matters. Evaluation time is always explicit — the kernel has no ambient “now” (CLAUDE.md: no kernel I/O includes no clock reads).

Unknown data handling differs by layer, on purpose

Thu, 09 Jul 2026 00:00:00 +0000

ADR 0009: Unknown data policy

Decision

Three layers, three different answers — because the cost of being wrong differs:

Layer	Unknown data
Event types	preserved, hashed, ignored by the reducer
Guard operators	rejected: lint error at authoring, throw at eval
Definition fields	carried and hashed, never interpreted

Context

Events must tolerate the future: a replicated store cannot retroactively reject an event that already exists on three replicas, so the reducer is total — unknown types stay in the log (and in the hash domain) and simply do not contribute to ticket state. Ignoring is safe because an event the reducer skips cannot silently change truth.
Guards must not tolerate the unknown: a guard the evaluator does not understand would change truth if guessed at. There is no safe default for “some condition I cannot evaluate” — neither satisfied-by-default nor failed-by-default is honest. So the guard vocabulary is closed (ADR 0001, PLAN §5): unknown operators are lint errors, and evaluation throws rather than improvising.
Definitions may carry annotations (:hint, :purpose, lint config): they are part of the pinned bytes — two definitions differing only in annotations are different definitions, honestly — but the kernel never reads them; only lenses do.

Consequences

Forward compatibility is asymmetric by design: new evidence flows through old kernels harmlessly; new semantics (guards) require a version bump everywhere.
tik lint’s closed-basis check is the enforcement point for the middle row; the reducer-totality property test enforces the top row.
Nobody gets to add meaning by sneaking a field into a definition: if the kernel doesn’t interpret it, it is annotation, whatever it is named.

Concurrent conflicting assertions block guards; humans resolve

Wed, 08 Jul 2026 00:00:00 +0000

ADR 0003: Conflicts are facts about disagreement

Decision

When causally concurrent assertions (neither an ancestor of the other via :event/parents) target the same fact path with different values, the fact becomes conflicted. A conflicted fact — like a disputed one — does not satisfy guards. explain surfaces both claims, both actors, and asks for a superseding assertion. Resolution is a new signed event: a human judgment on the record.

tik ships no conflict-resolution policy language. No latest-wins, no role-priority, no per-process resolution rules.

Event parents are mandatory; the log is a Merkle DAG

Wed, 08 Jul 2026 00:00:00 +0000

ADR 0004: Mandatory parents — the log is a Merkle DAG

Decision

Every event carries :event/parents: the set of head event ids the actor observed when minting. :ticket/create is the unique root with #{}; for every other event type an empty parent set is a mint-time error. Since parents are inside the content-addressed, signed region, the log is a Merkle DAG: one head hash commits to the entire history.

Context

Parents are not metadata — they change what kind of object the log is: without them, an append-only collection of claims; with them, an authenticated history graph where every claim carries what its author knew. Parents were originally optional “Phase 1” metadata. Review of the axes showed that optionality here is ambiguity, not flexibility, and that mandatory parents simplify or strengthen nearly every other axis simultaneously:

SHA-256 content addressing, self-describing ids, one algorithm per store

Wed, 08 Jul 2026 00:00:00 +0000

ADR 0006: Hash policy

Decision

Content addresses are SHA-256 over canonical bytes, written as self-describing ids: sha256-<hex>.
Exactly one algorithm per store per format-version. Verifiers reject stores mixing algorithms within a format version — hash agility in the format, discipline in the policy, because “verifier accepts whatever” is a downgrade-attack surface.
Migration, if ever needed, is additive: a format-version bump after which new events use the new prefix while old events remain exactly as signed. Mixed-prefix DAGs verify as long as the verifier implements both prefixes. No rewrite of history, ever.
The format version defines the trust contract, not the identifier syntax. A verifier implementing a format version must support exactly the hash algorithms that version requires; support for other algorithms is never inferred from a self-describing prefix alone. A generic hash-registry verifier (“dispatch on whatever the prefix says”) would recreate the downgrade surface rule 2 exists to close.

Context

The argument for SHA-256 is ecosystem weight, not a prediction about cryptography: it is sufficiently deployed that the verification ecosystem around it currently outweighs the benefits of any alternative. git’s own hash transition targets SHA-256 (SHA-512, SHA-512/256, BLAKE2 and K12 were considered and rejected), OCI digests, Sigstore/in-toto/DSSE, Nix SRI, FIPS 180-4 — and sha256sum in coreutils, which is what keeps verify level 0 checkable with tools from 1995. Should that balance ever shift, rule 3 is the exit.

Stage negation must be stratified

Wed, 08 Jul 2026 00:00:00 +0000

ADR 0005: Stratified negation over stages

Decision

A stage may apply [:not [:stage-reached X]] only to stages in a strictly earlier stratum of the process graph (stratum = longest :after path depth). tik lint enforces this as an error. (A dedicated :not-stage alias for the same guard existed through plan v5 and was removed in the v6 subtraction — one spelling means the linter polices one shape.)

Context

[:not [:stage-reached X]] is negation inside a fixpoint — non-monotone. Without stratification, two stages in the same stratum can both derive in the same fixpoint sweep against the pre-sweep snapshot (e.g. :escalated guarded by [:not [:stage-reached :triaged]] co-deriving with :triaged), producing a state that is deterministic only by accident of iteration strategy. Datalog solved this decades ago: evaluate strata in order, negate only what earlier strata have finished deciding. Adopting the same rule makes determinism provable rather than incidental and connects the guard language to well-understood theory.

Stored bytes are exactly the hashed region; signatures are detached

Wed, 08 Jul 2026 00:00:00 +0000

ADR 0007: Stored bytes = hashed region; detached signatures

Decision

An event file contains exactly the canonical bytes of the hashed region — the event map WITHOUT :event/id (the filename is the id; storing it inside would be redundant and, decisively, breaks sha256sum(file) = filename). Signatures never live inside the event either: :event/key/:event/sig are removed from the schema entirely; signatures are detached sidecar files (<event-id>.sig.<key-fingerprint>) verifying against the exact stored bytes, allowing multiple signatures per event without touching the hashed region.

The event-log acceptance test for all features

Wed, 08 Jul 2026 00:00:00 +0000

ADR 0001: The event-log acceptance test

Decision

A feature proposal must be expressible as one or more of:

(a) new event or attestation types over the existing append-only log, (b) new guard vocabulary evaluated purely from (events, now), (c) porcelain or lens behavior deriving from (a) and (b).

Proposals requiring stored mutable state, imperative stage transitions, or verification paths that leave the log are rejected or redesigned.

One carve-out, so the test cannot be misread: features necessary to preserve the integrity, authenticity, or reproducibility of the log itself — canonical serialization, signature algorithms, hash migration, witness sidecars, store verification — are trust substrate, governed by their own ADRs (0004–0007), not by this test. The substrate may never introduce domain truth outside the log; it exists to make (a)–(c) trustworthy. “A new signature algorithm is neither an event nor a lens, therefore rejected” is a misreading, not an application, of this ADR.

Tickets pin their process definition hash; migration is an event

Wed, 08 Jul 2026 00:00:00 +0000

ADR 0002: Pinned process versions, explicit migration

Decision

Tickets pin the process definition hash in effect at creation — the hash is the identity (ADR 0006); the human-readable version number is a label carried as metadata. Re-evaluation under a newer definition happens only via an explicit, signed :process/migrate event carrying the new hash. tik migrate --dry-run shows the derived-stage diff before anyone commits to it — a migration is a consequence-bearing decision (“under the new rules, security-review is now missing”), not a version-number edit.

Claude Code skill

Mon, 01 Jan 0001 00:00:00 +0000

Install the tik skill into Claude Code and Claude gains working knowledge of tik: it recognises a store, records facts with tik set rather than inventing a status field, reads tik explain before asking a person anything, and authors process definitions whose stages derive from evidence instead of listing activities.

That last part is the reason the skill exists. The failure mode for any model writing a tik process is a task list wearing a process costume — stages named after activities, with nothing following from anything. The skill carries the design law that rules it out, along with the closed guard vocabulary and the authoring loop that checks the result.

Derived beats declared

Mon, 01 Jan 0001 00:00:00 +0000

If something can be derived, storing it as authoritative state is a bug. That is the whole law, and every design question in tik resolves against it.

A ticket’s stage is the obvious case. It is never written down anywhere. It is f(events, now) — a pure function of the ticket’s own event log, the process definition that ticket pinned, and the instant you are asking about. Ask twice with the same inputs and you get the same answer, forever.

Events and facts

Mon, 01 Jan 0001 00:00:00 +0000

A ticket is an append-only set of events. Everything else about it is computed.

Seven event types

The vocabulary is closed and versioned, because the semantics of a verifiable kernel have to be enumerable:

Event	Meaning
`:ticket/create`	the ticket exists, pinned to a process definition by hash
`:fact/assert`	a claim about a path: `[:severity] = :high`
`:fact/retract`	withdraw a claim, with no replacement
`:fact/dispute`	reject a claim, with a reason
`:artifact/attach`	a file, stored and addressed by its hash
`:attestation/add`	a signed claim the kernel does not interpret
`:process/migrate`	re-pin this ticket to a newer definition

Things that look like they need their own type turn out not to. Comments are artifacts — text blobs attached by hash. Links are facts under a [:link …] path. Work records are :work attestation claims. Witness countersignatures are detached sidecars over a head rather than events, because an event would move the very head it witnesses.

Explain

Mon, 01 Jan 0001 00:00:00 +0000

A traditional tracker exposes state. tik exposes justification: what is true, why it is true, and what evidence is missing next. tik explain is where that surfaces, and every other view is a rendering of it.

$ tik explain 3184
To reach :resolved:
 ✓ [:fact [:resolution :ref]]
 ✗ attach an artifact whose path starts with "repro/"
 blocks: :closed
 (see: kb/runbooks/support-request-resolved.md)

Nothing in that block is speculation. The checkmarks are guards that already hold, the crosses are structured reasons produced by guard evaluation, blocks is the downstream closure, and the hint is the runbook the definition declares for that stage.

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

A working ticket system in under five minutes: no server, no database, no account, no YAML. Tickets are plain files in a directory you own; everything else — stages, boards, inboxes — is computed from them when you ask.

Guards

Mon, 01 Jan 0001 00:00:00 +0000

Guards

Deterministic pure functions of (events, now) from a closed, versioned vocabulary (tik.guard). Never effectful: verify must re-evaluate them identically, offline, years later. Effectful validation lives only in edge admission checks (CLI porcelain, server ingest), before events are minted.

Design law: facts over flags. A bare boolean guard is a checkbox with extra steps; tik lint warns. Prefer facts useful downstream — categories that route branches, artifacts, signed approvals.

hypothesis / :captured

Mon, 01 Jan 0001 00:00:00 +0000

Runbook: hypothesis / :captured

A belief worth testing exists. Capture it even half-formed — but do not state it until you can also state what would kill it. A hypothesis you cannot lose is marketing.

hypothesis / :killed

Mon, 01 Jan 0001 00:00:00 +0000

Runbook: hypothesis / :killed

Assert verdict=:killed and evidence of the kill: which criterion fired, observed how. A kill is a RESULT — it retires a belief and usually implies design work (the roadmap says what dies with it: kill H1 and the core loop is wrong, not under-featured). Write the evidence so the next design argument can cite it. Judgment stage, same rules as :validated: sign reasoning a stranger could dispute.

hypothesis / :running

Mon, 01 Jan 0001 00:00:00 +0000

Runbook: hypothesis / :running

Assert experiment: what is actually being run, on what, measured how. If the full experiment cannot start yet, name the leg that can and the leg that waits (H3 is the template). While running, record datapoints as comments — negative ones ESPECIALLY; an experiment that only logs good news is not running, it is performing.

hypothesis / :stated

Mon, 01 Jan 0001 00:00:00 +0000

Runbook: hypothesis / :stated

Assert statement (the falsifiable claim) and kill (what counts as losing, decided NOW, before any work). Write the kill criterion as an observable event, not a feeling: ‘abandoned within a month’, ‘requires prompt-side enforcement’. The process will not let a verdict through without this — that is the point.

hypothesis / :validated

Mon, 01 Jan 0001 00:00:00 +0000

Runbook: hypothesis / :validated

Assert verdict=:validated and evidence that a stranger could check: what ran, what was observed, why the kill criterion never fired, and any scoping decisions that bound the claim. Sticky — later doubts are a NEW hypothesis, not an edit. This stage is judgment: the process cannot verify your evidence is sufficient, only that you signed it. Leave enough that someone can dispute you specifically.

identity-registry / :registry

Mon, 01 Jan 0001 00:00:00 +0000

identity-registry: registry

The registry ticket accumulates signed :identity attestations, each binding an IdP subject to an actor’s public key. The ticket is always in this stage — bindings are evidence, not workflow.

Recording a binding

tik bridge oidc --registry <id> --actor <name> runs the device-flow login and appends the binding, signed by the bridge’s TIK_KEY.
Rotation and re-attestation are newer attestations by the same bridge; readers take the latest binding per (issuer, subject).
Revocation is a dispute of nothing — attestations are claims by the bridge; a binding the bridge no longer stands behind simply stops being re-attested, and lenses can require freshness via :attested-within.

Reading bindings

tik log <registry-id> shows every binding with its signature; tik verify <registry-id> checks them offline — no IdP call, ever.

Install

Mon, 01 Jan 0001 00:00:00 +0000

Each release publishes two downloads, a SHA256SUMS file covering both, and a cosign keyless signature over those checksums.

Download a release

From the releases page :

tik-linux-amd64-glibc — the native binary, no runtime needed. It is labelled for exactly what it is: linux/amd64 against glibc.
tik.jar — the uberjar, for macOS, Windows, and arm. Runs on any JDK 21: java -jar tik.jar --help. The container image is the universal deployment path.

chmod +x tik-linux-amd64-glibc
./tik-linux-amd64-glibc --help

Verify before trusting. The checksums cover the downloads, and the cosign bundle covers the checksums:

Lint, simulate, test

Mon, 01 Jan 0001 00:00:00 +0000

Three checks, in the order you reach for them.

Lint

tik lint processes/support-request.edn

The linter enforces what the kernel cannot:

The closed guard basis — only operators the declared :process/guard-vocab admits.
Graph sanity — every :after names a stage that exists, and no cycles.
Stratified negation — [:not [:stage-reached …]] may only name a stage in a strictly earlier stratum, which is what makes the fixpoint provably deterministic.
Facts over flags — a warning where a bare boolean stands in for information worth recording.
Prefix boundaries — an :artifact prefix that does not end at a path boundary matches more than its author expects.

With no argument it lints the store instead: open tickets missing descriptions, titles, or signatures.

MCP server

Mon, 01 Jan 0001 00:00:00 +0000

TIK_ACTOR=bot TIK_KEY=~/.config/tik/bot_ed25519 tik mcp

tik mcp speaks the Model Context Protocol over stdio and exposes one store as a tool surface. The tools an agent is offered are exactly the steps the frontier admits for its role at that moment, so the tool list is the authorization boundary.

Why the boundary holds

An agent’s permission to act is derived from the same guards a person’s is. A step whose :signed-by names a role the agent is not in never appears as an available tool, and calling it anyway is refused with the derived reason rather than a generic denial.

Reading a store

Mon, 01 Jan 0001 00:00:00 +0000

Every view here is computed when you ask, so none of them can be stale.

What should I do?

tik next --actor alice
tik next --role :triager
tik explain 3184 --actor alice

next ranks by how much downstream work each step unlocks, with quiet tickets rising. explain is the per-ticket answer: what is missing, whose signature it needs, and which stages it blocks. See Explain for the model behind them.

The board

tik ls
tik ls --all --long
tik ls --where 'stage=:blocked and fact:severity=:high and not disputed'
tik search firefox login

A selector is space-separated terms, all ANDed, each optionally negated: stage=:blocked, fact:severity, fact:severity=:high, actor=seb, disputed, conflicted, unsigned, derived-from=<hash>, ~text. The same grammar drives search, and tik dupes reports near-title lookalikes.

Recording work

Mon, 01 Jan 0001 00:00:00 +0000

You record evidence. Stages follow.

Create a ticket

tik new support-request --title "login fails on Firefox"

The ticket pins the process definition’s content hash at creation, so it is judged by the rules it was minted under until somebody deliberately moves it with tik reprocess.

Created beneath a store, a ticket inherits its context as signed facts: repo=<name> from the enclosing git repository, plus any .tik-facts.edn maps on the way down, nearest winning, with anything explicit beating both.

release / :attested

Mon, 01 Jan 0001 00:00:00 +0000

release: attested

The container image exists, an SBOM and build provenance were produced for it, and the checksums carry a signature.

tik set <id> image=ghcr.io/metio/tik@sha256:... --actor ci
tik set <id> signature.bundle=<sha256 of SHA256SUMS.bundle> --actor ci
tik attest <id> :sbom --body '{:format "spdx-json" :digest "sha256:..."}' --actor ci
tik attest <id> :provenance --body '{:format "slsa-v1" :digest "sha256:..."}' --actor ci

The guard checks that a trusted attester said an SBOM exists. It does not read the SBOM — guards never query anything, which is what keeps evaluation offline and reproducible forever. The derivation is therefore exactly as trustworthy as :ci, and that is a property to state plainly rather than bury.

release / :built

Mon, 01 Jan 0001 00:00:00 +0000

release: built

The artifacts for this version exist and the pipeline has said which commit produced them.

tik set <id> version=2026.8.5204821 commit=<sha> --actor ci
tik attach <id> checksums/SHA256SUMS

commit must be signed by a member of :ci: the pipeline is the only party that can honestly say which source produced these bytes, and a human asserting it is a claim about something they did not observe.

release / :published

Mon, 01 Jan 0001 00:00:00 +0000

release: published

A maintainer decided to ship, and that maintainer is not the party that built it.

tik set <id> approval=:ship --actor seb

The :different-person guard compares who asserted commit with who asserted approval. The pipeline cannot approve its own release — not because a rule forbids it, but because the two facts would carry the same signature and the guard would not hold.

release / :scanned

Mon, 01 Jan 0001 00:00:00 +0000

release: scanned

A vulnerability scan ran against this version’s dependencies, found nothing, and said so recently enough to be about today’s advisories.

tik attest <id> :vulnerability-scan --body '{:tool "clj-watson" :db "github-advisory"}' --actor ci
tik set <id> scan.result=:clean --actor ci

Both halves are needed and they say different things. The fact records the verdict; the attestation records that a scan happened and when. The one-day freshness window is what makes replay useless — a scan from last month is cryptographically valid and fails this guard honestly, because the advisory database it consulted no longer exists.

release / :withheld

Mon, 01 Jan 0001 00:00:00 +0000

release: withheld

A maintainer decided this version does not ship.

tik set <id> approval=:hold --actor seb
tik comment <id> "held: the scan is clean but the advisory for the transitive dep is unresolved upstream"

Recorded with the same weight as shipping, because the reason a version never shipped is worth as much a year later as the reason one did — and it is the question nobody can answer from a green pipeline.

Replication

Mon, 01 Jan 0001 00:00:00 +0000

A tik store replicates by copying files. Two clones append independently, merge by set union, and derive the same answer — because derivation is a pure function of the event set and events are addressed by their content.

git pull && git push # this is the replication protocol

Why the merge is trivial

Every event lives in its own file whose name is the SHA-256 of its bytes. Two people adding evidence to the same ticket create different files, so the merge is a union of directories and git never sees a conflicting hunk. Two people making the identical claim produce byte-identical files with the same name, and the union keeps one — deduplication for free.

Roles and authority

Mon, 01 Jan 0001 00:00:00 +0000

A role is a name a definition uses in its guards. Membership is store state that decides who is in that role today.

Declaring a role

:process/roles
{:triager {:members ["seb"]}
 :approver {:members ["alice" "bob"]}}

Guards refer to the name:

:guards [[:signed-by :triager [:category]]]

That guard holds when the fact at [:category] was asserted by a member of :triager. It is a statement about evidence — who put this claim on the record — rather than a permission check performed somewhere else.

Stages

Mon, 01 Jan 0001 00:00:00 +0000

A process defines stages. Each stage names its prerequisites (:after) and the conditions that must hold to reach it (:guards). Reaching a stage is never an action somebody takes; it is a conclusion.

{:stage/id :resolved
 :after [:triaged]
 :guards [[:fact [:resolution :ref]]
 [:or [:not [:fact= [:category] :technical]]
 [:stage-reached :reproducible]]]}

That second guard reads “technical implies reproduced” — material implication written out, because the vocabulary has :or and :not and needs no separate conditional.

The reached set is a fixpoint

Derivation computes the set of reached stages by iterating to closure: every stage whose prerequisites are reached and whose guards hold joins the set, which may in turn enable further stages, until nothing changes.

Store administration

Mon, 01 Jan 0001 00:00:00 +0000

Identity

tik actor add alice ~/.config/tik/id_ed25519.pub
tik sign 3184
tik witness 3184

actor add registers a signer in the store’s allowed-signers registry. Exporting TIK_KEY signs every write as it happens; sign catches up on your own earlier events, and only your own — signing somebody else’s would assert something false. witness countersigns a ticket’s head, and one signature timestamps the entire ancestry beneath it.

Roles

tik roles
tik roles add triager alice
tik roles remove triager bob

A process definition declares which roles exist and who starts in them; the store’s register decides who is in one today, for every ticket at once. Use it for a hire or a departure — it takes effect on in-flight tickets immediately, with no definition version bump and no per-ticket migration. See Roles and authority .

support-request / :closed

Mon, 01 Jan 0001 00:00:00 +0000

Runbook: support-request / :closed

Sticky milestone: only the customer’s acknowledgement closes, and a later retraction will NOT reopen (the log shows both truths). Ask for the ack explicitly — the customer information-request pattern. If the customer goes silent, the ticket honestly stays at :resolved; do not assert the ack on their behalf, ever (authorship is the whole point, ADR 0010).

support-request / :escalated

Mon, 01 Jan 0001 00:00:00 +0000

Runbook: support-request / :escalated

This stage derives on its own: 48 hours without a category. There is no action that produces it — the runbook is for reacting to it. An escalated ticket means triage is the bottleneck: find why (nobody on rotation? report unintelligible?) and either triage it now or record what blocks triage. Escalation clears itself the moment a category lands (fact-level negation).

support-request / :received

Mon, 01 Jan 0001 00:00:00 +0000

Runbook: support-request / :received

A new report exists; nothing is known yet. Read the title and any attached artifacts. Your job is to move it toward triage: get a category and a severity asserted by a triager. If the report is unintelligible, ask the reporter (a comment or an information-request effect) rather than guessing a category — a wrong category asserted confidently is worse than an honest gap.

support-request / :reproducible

Mon, 01 Jan 0001 00:00:00 +0000

Runbook: support-request / :reproducible

Attach a reproduction under repro/ — a script, a request trace, a recording; the smallest artifact that makes the failure happen again. If you cannot reproduce it, say so in a comment with what you tried; do not attach a placeholder to satisfy the guard (evidence theater, PLAN §18). A technical ticket without a repro simply is not resolvable yet — that is the process being honest, not slow.

support-request / :resolved

Mon, 01 Jan 0001 00:00:00 +0000

Runbook: support-request / :resolved

Assert resolution.ref pointing at the fix (commit, config change, knowledge-base answer). For technical tickets the reproduction must exist first — ‘fixed it but can’t show the bug’ does not resolve. Resolution is a claim the customer has not yet accepted; do not consider the work done here.

support-request / :triaged

Mon, 01 Jan 0001 00:00:00 +0000

Runbook: support-request / :triaged

Assert category and severity — both must come from a triager (the :signed-by guard checks the role, not the values). Category is a claim about what KIND of problem this is; when genuinely unsure, pick the closest and say why in a comment — a later dispute is cheap and leaves better history than stalling. Severity reflects impact on the customer, not effort to fix.

The event log

Mon, 01 Jan 0001 00:00:00 +0000

The event log

A ticket is an append-only set of immutable, content-addressed events (canonical-EDN SHA-256). Replica merge is set union: replicas converge without coordination — merge is conflict-free by construction, truth is deliberately not. Conflicting claims are never hidden or resolved by merge; they remain in the log and surface as derived fact states (decisions/0003 ). Ticket state and stage are pure functions of the log; any materialized view is a rebuildable cache (decisions/0001 , decisions/0013 ).

The witness

Mon, 01 Jan 0001 00:00:00 +0000

The witness

Servers countersign events at ingest: “I saw hash H at time T.” Trusted signing time is the load-bearing input for “actor held role R at signing time” and the moment a stage’s social meaning solidifies.

witnessed.dev productizes this as a neutral third-party witness: countersigning event hashes only (no content leaves the organization), giving self-hosted instances independent timestamping evidence for audits.

tik-dev / :captured

Mon, 01 Jan 0001 00:00:00 +0000

Runbook: tik-dev / :captured

A thought exists; the ticket preserves it. Give it a title that will mean something in six months. Nothing else is required — capture must stay cheap or ideas stop being written down. Move to triage when you can honestly write one summary sentence and name the kind.

tik-dev / :implemented

Mon, 01 Jan 0001 00:00:00 +0000

Runbook: tik-dev / :implemented

Assert commit naming the commit that does the work. The commit must exist before the fact does — the fact is a claim about evidence, and the evidence is the git history. One feature, one commit, stacked on main (this repo’s workflow).

tik-dev / :landed

Mon, 01 Jan 0001 00:00:00 +0000

Runbook: tik-dev / :landed

Assert gate=:green only after the FULL local gate: kaocha, kondo (0/0), eastwood, splint, cljfmt, tla, process tests, reuse, typos, markdown. Not the one check your change touched — all of them. Sticky: a later gate dispute does not un-land; file a new bug ticket instead. If the gate is red, assert gate=:red honestly and fix forward.

tik-dev / :parked

Mon, 01 Jan 0001 00:00:00 +0000

Runbook: tik-dev / :parked

Assert parked.reason — the reason is the deliverable. Cite the verdict that parks it (a PLAN §19 entry, a trigger condition not yet met). Parked is not closed: the ticket stays visible on the board and can resume by simply asserting the missing facts. Parking without a real reason is deferral theater.

tik-dev / :triaged

Mon, 01 Jan 0001 00:00:00 +0000

Runbook: tik-dev / :triaged

Assert summary (what and why, one breath) and kind (feature/bug/docs/spike) as a maintainer. If it duplicates existing work, link it (link.duplicate-of=<uuid>) instead of triaging twice. If it should wait, this is also where you park it — with the reason, not silently.

track / :done

Mon, 01 Jan 0001 00:00:00 +0000

track: done

The thing ended — say how:

tik set <id> outcome="shipped in v2; see order #1234"

A few honest words beat a closed flag: the outcome is the only thing anyone will want from this ticket in a year.

track / :open

Mon, 01 Jan 0001 00:00:00 +0000

track: open

The ticket exists. There is no workflow to satisfy — record what is true as it happens:

tik set <id> key=value for facts worth keeping.
tik comment <id> <text> for anything else.
tik attach <id> <file> for evidence.

When several track tickets start following the same informal shape, run tik author and give that shape a real definition.

Writing a definition

Mon, 01 Jan 0001 00:00:00 +0000

The design law

A stage is defined by what must be TRUE to reach it, never by who moved what. Ask of every stage: what evidence, on record, would convince a sceptical auditor a year from now? Write that as guards. If the honest answer is “somebody said so”, then make that the fact — a named person’s signature on a named claim — rather than a status somebody sets.