Reference on processkit

apiVersion Policy

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

processkit uses a Kubernetes-style apiVersion field on every entity:

apiVersion: processkit.projectious.work/v2

The group

The group processkit.projectious.work is a reverse-DNS name anchored on the owning organization (projectious.work) with processkit as a subcomponent. This prevents name collisions if other organizations fork or publish compatible primitives under their own domains.

The form <reverse-dns-group>/<version> is the Kubernetes-idiomatic shape — exactly one slash. Tools that split on / expect exactly two parts.

Evolution rules

apiVersion	Status	Meaning
apiVersion	Product line	Status
—	—	—
`processkit.projectious.work/v1`	v0.x	Current v0.x entity format
`processkit.projectious.work/v1beta1`	none	Reserved; not used
`processkit.projectious.work/v2`	v1.x	Current v1.x entity format

The processkit product version, entity API version, schema-source format, and per-kind schema versions are independent axes. In particular, processkit v1.x deliberately uses entity API v2.

ID Formats

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

Entity IDs in processkit have the shape <PREFIX>-<id-body>. The prefix is determined by the primitive kind and is not configurable. The id-body has two independent configuration axes: format and slug.

Configuration

In the consuming project’s aibox.toml:

[context]
id_format = "word" # word | uuid
id_slug = false # true | false

The four combinations

`id_format`	`id_slug`	Example	Notes
`word`	`false`	`BACK-calm-fox`	Default. Short, memorable, solo-friendly
`word`	`true`	`BACK-calm-fox-add-lint`	Memorable + descriptive for prose contexts
`uuid`	`false`	`BACK-550e8400-e29b-41d4`	Uniqueness guarantees for large teams
`uuid`	`true`	`BACK-550e8400-add-lint`	UUID + readable context

Prefix registry

Primitive	Prefix
WorkItem	`BACK`
LogEntry	`LOG`
DecisionRecord	`DEC`
Migration	`MIG`
Artifact	`ART`
Note	`NOTE`
Actor	`ACTOR`
Role	`ROLE`
Binding	`BIND`
Scope	`SCOPE`
Category	`CAT`
CrossReference	—
Gate	`GATE`
Schedule	`SCHED` (legacy v1)
Constraint	`CONST`
Context	`CTX`
Discussion	`DISC`
Process	`PROC` (legacy v1)
StateMachine	`SM` (legacy v1)

Metric, Model, Process, Schedule, and StateMachine do not reserve first-class primitive prefixes in the v2 contract. The legacy prefixes remain documented so existing v1 contexts can be migrated and read correctly.

Version Migration

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

processkit is distributed as versioned releases. Upgrading pinned versions is deliberate: processkit does not silently rewrite a consuming project’s context. A version bump should produce a Migration document under context/migrations/pending/ that the user and agent work through together.

The model

processkit ships a generic diff script (scripts/processkit-diff.sh) that compares two tagged versions of any processkit-compatible source — upstream processkit, a company fork like processkit-acme, or any other downstream. The script reads src/PROVENANCE.toml at each tag (a single file mapping every shipped file to the tag in which it last changed) and emits a structured diff: added, removed, changed, unchanged.

Privacy Tiers

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

processkit recognizes three privacy tiers for entities under context/. The tier is declared via an optional privacy: field in metadata and enforced by directory layout + a .gitignore rule.

The three tiers

Tier	Default?	Git status	Typical use
`public`	no	tracked	identity.md, README, public roadmap
`project-private`	yes (default if omitted)	tracked	workitems, decisions, logs, working-style.md
`user-private`	no	NOT tracked	team-and-relationships.md, personal scratch notes

Most entities omit the field entirely and inherit project-private.

v2 Contracts

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

SmoothTiger/SmoothRiver v2 keeps durable facts in existing entity primitives and uses projection skills for runtime files. The source of truth remains processkit context; generated files are checked against that source.

Metric, Model, Process, Schedule, and StateMachine are legacy v1 migration-source kinds, not shipped v2 entity primitives. Model selection uses model-recommender roster/configuration data. Process definitions are Artifacts plus process-instance WorkItems. Schedule semantics use Binding(type=time-window). Runtime state-machine YAML files remain implementation contracts, not user-authored StateMachine entities.

v1 Alpha Release Facts

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

Do not edit this page by hand. Its authoritative source is release/v1-release-facts.json.

Fact	Value
Release	`v1.0.0-alpha.5`
Status	exact-pin prerelease
Signature	`Ed25519`
Installer protocol	`processkit.projectious.work/installer/v1alpha1`
Entity API version	`processkit.projectious.work/v2`

Native Assets

processkit-v1.0.0-alpha.5-x86_64-unknown-linux-gnu
processkit-v1.0.0-alpha.5-aarch64-unknown-linux-gnu
processkit-v1.0.0-alpha.5-x86_64-apple-darwin
processkit-v1.0.0-alpha.5-aarch64-apple-darwin

Every published asset has a checksum sidecar and is bound into the signed release envelope. The public release is the authority for final checksums and host provenance.