A deterministic compiler that turns rough work intent into governed, reproducible, model-specific prompt packages — and never calls a language model.
Canonical facts
Domain
content-platform
Version
0.2.0-pre
Updated
2026-07-02
Maintainer
azwerks
Proof
supported
!Pre-release (v0.2.0-pre): this record covers the compiler's design and determinism contract; the internal implementation remains private.
▸How the record thinks
02
Key decisions
04
▸Decision
How should the compiler behave given the same input twice?
ChosenByte-for-byte identical output. The compile path may not use Math.random, Date.now, network calls, or any model API.
Reproducibility is the whole product. Governed work needs an output you can re-derive and audit, not one you hope to recreate.
Alternatives considered
×Call an LLM to "enhance" the prompt at runtime — Non-deterministic and unauditable — the opposite of the goal.
×Seed randomness for "reproducible" variety — Still hides intent in a seed; variation should be explicit config, not chance.
Consequences accepted
→No runtime creativity — every difference must come from explicit configuration, rules, or policy.
→A determinism test runs the compile twice and blocks the build on any drift.
Enforced by
determinism.test.ts
▸Decision
One prompt path, or many?
ChosenSeven intent lanes routed through a typed intermediate representation (WerkformIR) — visual-generation, development-task, engineering-audit, documentation-spec, product-spec, design-system, and release-prep.
A single visual path couldn't express operational intent like implement, audit, or specify. Intent-aware routing keeps each lane's normalization and renderer honest.
Alternatives considered
×Keep the single visual-generation path from the prototype — Couldn't express implement / audit / document / specify intent.
Consequences accepted
→More surface to maintain — seven renderers instead of one.
→processAlgorithmicCompile is kept as a compatibility entry for legacy visual callers.
Entry
compileWithWerkform
▸Decision
How do packages stay valid and governed?
ChosenA typed IR plus a package validator, a policy eligibility gate, and a compilation manifest that carries intent, target agent, validation state, repair state, and review-required outcomes.
Governance has to be a structural property, not a review afterthought. The manifest makes every package's posture machine-readable.
Alternatives considered
×Validate the final string with regex / heuristics — Can't reason about intent or carry posture forward.
→A policy eligibility gate can hold a package back for review.
Shape
WerkformIR
▸Decision
What happens with vague work language like "clean it up" or "fix everything"?
ChosenRefuse to guess. Vague requests produce explicit validation risks and derived scope constraints instead of a confident but invented plan.
Vague intent is the primary failure mode of prompt tooling. Surfacing the risk is more useful than papering over it.
Alternatives considered
×Best-effort guess at what the user probably meant — Produces confident, wrong scope — the exact failure mode being designed out.
Consequences accepted
→Terms like clean it up, fix everything, modernize, and optimize everything raise validation risks and derived scope constraints.
Detected by
work-vague-terms
▸Lineage
03
History
Operations
milestone
milestone2026-04
completed
Clean-package cut from the promptwerks prototype
Extracted the compiler engine from the promptwerks prototype into a standalone, strictly-typed package.
Intent
Separate the reproducible compile core from the app shell so it could be governed and tested on its own.
Action
Carved out the compile path and added the strict TypeScript + vitest + tsup toolchain.
Result
werkform v0.2.0-pre — the first clean-package cut.
milestone2026-06
current
Multi-lane migration
Migrated from the single visual-generation path to seven intent lanes routed through WerkformIR.
Intent
Express operational intent — implement, audit, specify — that the single visual path could not.
Action
Introduced the typed IR, per-lane normalizers and renderers, and the policy eligibility gate.
Result
Seven lanes live; the visual and development lanes are proven by test.
product-spec, design-system, and release-prep lanes remain partial on validation coverage.
▸How do you know?
04
Evidence
03
determinism.test.ts
verified
Runs the same compile twice and asserts byte-identical output across the visual and development lanes. If any nondeterminism creeps in, CI goes red.
File:
test/determinism.test.ts
Suite:
vitest
Gate:
CI blocking
Covers the visual and development lanes directly; other lanes inherit the same pure compile path but are asserted through their own contract tests.
Eight pinned contract tests
verified
determinism, buzzwords, development-task, non-visual-routing, lane-coverage, normalization, policy-gates, and work-vague-terms — each pins a specific behavior of the compiler.
File:
test/
Count:
8 pinned contracts
CI on every push and PR
verified
tsc --noEmit (strict), vitest run, and a tsup build (ESM + CJS + type declarations) all run on every push and pull request to main.
File:
.github/workflows/ci.yml
Checks:
lint · test · build
Trigger:
push + PR to main
COLOPHON · № 08REC / werkform
Created
Updated
Record ID
REC / werkform
Version
0.2.0-pre
State
candidate
Maintained by
azwerks
Derived from
Extracted from the promptwerks prototype; the compiler engine that powers it.
LimitsPre-release. The determinism contract and lane design are public; internal implementation stays private until the stable release.