v0.0.1-pre · public build

Agents do the work.
Punk keeps it bounded.

A local-first work kernel for contract-tracked, eval-gated, proof-bearing AI work. Personal experiment. Built for researchers and experimenters. It may break at any time and is not guaranteed to work end-to-end.

▸ follow the build read the roadmap →

core-first / personal experiment / may break / modules later / building in public

∎ punk / guide online · local

PUNK KERNEL · 0x8A…F4

quills out. scope tight.

goal

contract

run

gate

proof

// receipt.0x8a2f · spec a4c1 · gate 14/14 ✓ · by @mira

§ 01

the drift

AI agents are powerful.
Projects still drift.

A model can write the patch in 12 seconds. The project takes three weeks because decisions, context, and proof live in five different places — and none of them trust each other.

one bounded flow

goal → contract → run → gate → proof

One markdown goal. One signed contract. One replayable run. One gate that either passes or does not. One proof that survives the people.

✓ contract hashed

✓ run budgeted

✓ gate automated

✓ proof receipted

✓ memory appended

§ 02 · the eight laws · a manifesto

Principles most teams print on a wall. Punk runs them.

They are not prompts. They are runtime boundaries — the kernel refuses work that violates them.

A principle a team can ignore is decoration.
A principle the runtime enforces is a law.
Punk ships the second kind.

LAW · 01

Contract first

Nothing runs until the spec is hashed, signed, and scope-bound.

01 / 08
LAW · 02

Flow before features

Harden the work loop before you decorate it. Kernels before cosmetics.

02 / 08
LAW · 03

Eval before expansion

A capability ships the gate first. No eval, no merge.

03 / 08
LAW · 04

Gate writes the decision

Deterministic checks decide accept/reject. Humans review the exceptions.

04 / 08
LAW · 05

Proof before acceptance

Every accepted run emits a replayable receipt: spec + seed + diff + checks.

05 / 08
LAW · 06

Research before decisions

Major moves ride on written memos. ADRs are mandatory, not optional.

06 / 08
LAW · 07

Memory from day zero

Context is a first-class, append-only artifact. It outlives people.

07 / 08
LAW · 08

Public build from day zero

The repo is the source of truth. Work happens where strangers can read it.

08 / 08

∎ enforced at: contract.lock · gate.default.yml · receipt.v0

§ 03

lifecycle

One loop. Seven artifacts.

Every piece of work travels the same path. When it closes, the project's memory is a little longer and a little more honest.

∎ work.flow.v0 loop closes → memory grows

01

goal

plain-markdown promise

→

02

contract

hashed · signed · scoped

→

03

run

agents on a leash

→

04

receipt

tool calls · diff · seed

→

05

gate

deterministic evals

→

06

proof

replayable artifact

→

07

memory

append to the kernel

next run reads the memory

// receipt.0x8a2f

spec: goals/payments-auth.md@a4c1

seed: 0x00e7…3b

agents: 2 · tool_calls: 18

budget: $0.42 / $5.00

diff: +182 −94 · sha256:ff…91

gate: 14/14 ✓

status: accepted · by @mira

// contract.lock

hash: sha256:c2…9a

grants:

fs:rw on src/auth/**

fs:ro on docs/**

no-net

checks: tests/auth/** · p99 < 180ms · 0 new 401s

budget: $5.00 hard cap

signed: @mira · 2026-04-18T14:02Z

§ 04

the repo is the room

Public build.
Core-first. No ta-da.

Everything in Punk is being built where you can read it. The repo layout mirrors the laws — and vice versa. The roadmap is the folder structure.

~ / punk / main ● tree

punk/

├── work/

│ └── goals/ // the 'why'

│ ├── payments-auth.md

│ └── onboarding-v2.md

├── knowledge/ // project memory

│ ├── context.append.log

│ └── glossary.md

├── public/ // build-in-the-open

│ ├── BUILDLOG.md

│ └── weekly-digest/

├── flows/ // the 'how'

│ ├── goal-to-contract.yml

│ └── run-to-proof.yml

├── evals/ // the gate

│ ├── gate.default.yml

│ └── checks/*.yml

└── docs/

└── adr/ // decisions, dated

├── ADR-001-contract-first.md

├── ADR-002-gate-writes.md

└── ADR-007-modules-later.md

~ / punk · BUILDLOG.md · follow week 003

$ punk log --since=monday

# week 003 · 2026-04-13 → 18

mon hashed first contract.lock format · ADR-001

tue wired gate.default.yml to block on red evals

wed wrote ADR-007: modules land after core freeze

thu receipt.v0 emits signed diff + seed

fri guide refuses out-of-scope questions (good)

next: harden contract grants. no modules yet.

— ∎ —

$ punk status

kernel: ● compiling · laws: 8/8 · gate: live

module: ○ not yet · devpunk / pubpunk staged

guide: ● online · scope: laws only

§ 05

roadmap · staged

Modules wait on the core.

Nothing below is shipping. Everything below is a commitment about order: the laws harden first, then a module gets to land.

§ 01

kernel

compiling

now · v0.0.1-pre

§ 02

devpunk

staged

after kernel freeze

§ 03

pubpunk

staged

after devpunk

§ 04

—

open

rfc window

§ 02 · devpunk

next · after kernel

DevPunk

The engineering surface. Agents on your repo, your machine, under a signed contract. Editor and shell; no cloud.

grants

fs:rw · scoped

runtime

local · bring-your-own model

output

signed receipt · replayable

intent

merge only on gate-pass

LATER

§ 03 · pubpunk

PubPunk

The public surface. Not in scope yet. Notes only.

○ weekly digest of the build

○ signed public receipts

○ read-only · no telemetry

blocked on: kernel freeze

§ 04 · open slot

—

Reserved. If you have a module idea that needs a kernel this strict, write an RFC against the laws.

▸ propose a module on GitHub ↗

∎ no dates, no waitlist. the order is the promise.

§ 06 · the guide

A narrow assistant.

Guide answers about Punk — laws, roadmap, build. It refuses the rest. The scope is the feature.

the contract it reads from

"Answer about the kernel. Cite the law. When asked anything else, step back."

answers

+ what a law means

+ why a law exists

+ what is staged next

+ which ADR to read

refuses

− generic coding help

− roadmap dates

− opinions on other tools

− anything off-contract

// guide.contract.md · network: none · cite: always

∎ transcript · punk/guide online

you

"what is law 04?"

guide · cites § laws/04

Gate writes the decision. Runs land on pass/fail from a deterministic eval. Humans only review exceptions.

you

"write me a React login form."

guide · out of scope

Not my contract. For code, open a goal, sign a contract, and run an agent under it.

you

"when does pubpunk ship?"

guide · cites § ADR-007

After the kernel freezes. No date. Modules are explicitly a later problem.

> ask about a law, an ADR, or what is staged…

§ 07 · the invitation

Read the kernel
while it is still wet.

Punk is a kernel, not a product. We ship one law at a time, in the open. If that is your speed — walk in.

primary

Follow the build

repo-tracked public artifacts

open public artifacts ↗

secondary

Read the roadmap

core first, modules later

// honest status

v0.0.1-pre · kernel compiling / no waitlist / no pricing / no download yet

the repo is the product until the core freezes

Agents do the work. Punk keeps it bounded.

AI agents are powerful. Projects still drift.