Skip to content
HedronitePublic

About

Protocol and drop-in kit for Go that is correct, dense, and fast.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

314 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Go-TOPS

Go-TOPS product mark and wordmark

A protocol and drop-in kit for Go that is correct, dense, and fast.
A written spec, a JSON Schema, per-class profiles, and a thin orchestrator (`gotops`) for the Go tools you already run.

Go 1.26 language floor Hedronite Protocol 0.4.4 License: MIT OR Apache-2.0 CI workflow: ci Docs workflow

Quick start · What you get · How it works · Status · Protocol · Harness · Changelog

Built by Hedronite. Structure adapted from Rust-TOPS.
CRAP scores use the 2007 Change Risk Anti-Patterns formula. This kit did not originate that metric.


Go-TOPS (Go Testing and Optimization Protocol Suite) is a protocol: a written spec, a JSON Schema, per-class profiles, and the gotops CLI that runs the Go tools you already use. This repository is the public kit for that protocol.

It is for authors of Go libraries and binaries, and for the people who own their CI, who want one gate order: hygiene, tests, coverage and CRAP, then the later layers the class names once those layers land. A legacy repository can adopt it under ratchet, where a debt ledger holds the line and counts only fall.

The package is unreleased (0.0.0-dev). There is no git tag and no module version to install. Run gotops from this tree. One public repository, vigil, runs the gate beside its own CI under ratchet; the kit is not yet a release you can pin.

Pins

Plane Pin Where
Protocol 0.4.4 GO_TOPS.md, go-tops.yaml, go-tops.lock, and the schema protocol constants
Package 0.0.0-dev gotops version. No tag exists. A release will set this at link time
Language floor Go 1.26 go.mod and toolchain.go_floor in go-tops.yaml
Toolchain go1.27.4 go-tops.lock
Launch classes three profiles/: binary-cli, binary-service, library-core

Quick start

From a clone of this repository:

go run ./cmd/gotops version
go run ./cmd/gotops check
go run ./cmd/gotops gate

check validates go-tops.yaml and go-tops.lock against their schemas, then the semantic rules. gate runs every enabled layer at tier 1 (hygiene, tests, coverage, CRAP) and writes .go-tops/report.json. This repository's CI runs go run ./cmd/gotops gate and then asserts the report.

To adopt it in another module, gotops init --class accepts binary-cli, binary-service, or library-core, and gotops baseline --init writes the first .go-tops/baseline.json ledger for the ratchet mode. The go-tops-adopt, go-tops-gate and go-tops-review skills under .agents/skills/ walk an agent through the same steps.

What you get

go test and linters alone This kit
Contract Docs and tests you arrange Protocol 0.4.4 and JSON Schemas for the config, the gate report, and the tool lock
Class floors None Three launch profiles
Orchestrator You sequence the commands gotops version, check, init, gate, report, lock, doctor, baseline
CRAP A separate tool, if any Native CRAP on every production function: complexity, guard-neutral coverage, exemptions
Legacy code All or nothing ratchet: a debt ledger records only what is over the line, and counts only fall
CI on this repo — One gate job (Linux, macOS, and the language floor), then a report assertion, plus docs CI

What you do not get

Claim Reality
A released module or tag The package is 0.0.0-dev. Nothing is published
Mutation testing Not yet. It is the next milestone (M4)
A laws layer that judges this repo Analyzer laws land at M5. Until then this repository gates itself under advisory, and CI asserts the gates that exist
A test framework gotops runs go test and the pinned tools; it does not replace them

How it works

Write the oracle from the contract, then the smallest production code that meets it. A test taken from the function body freezes current behavior, including bugs.

gotops gate runs enabled layers at or below --max-tier (default 1), laws last. An enabled layer with no command is not-run and fails the gate. A layer that was not evaluated is reported as not evaluated, never as a pass. Layers end in an outcome and laws in a verdict, with one exit table in GO_TOPS.md.

Path Role
GO_TOPS.md The protocol, 0.4.4
schema/ JSON Schemas: configuration, gate report, tool lock, and shared core definitions
cmd/gotops/, internal/ The gotops CLI: one file per command, and the layers, CRAP, ratchet, runner, lock, report and init packages behind them
go-tops.yaml, go-tops.lock, tools/ This repository gating itself: configuration, tool pins, and module tools
.github/workflows/ci.yml The one gate job
profiles/ Launch profiles
calibration/ The calibration records behind the CRAP caps: the 2026-11 probe and the native CRAP re-measure
.agents/skills/ The adopt, gate and review skills (mirrored for other agent harnesses)
scripts/docs/ The docs checker that docs CI runs
config/AGENTS.template.md The AGENTS.md section gotops init writes into an adopting repo
AGENTS.md Editing harness for this repository (CLAUDE.md imports it)

Status

Draft. Protocol 0.4.4. Package 0.0.0-dev. No tag.

Milestones M1, M2 and M3 are done. The gotops CLI judges hygiene, tests, coverage and native CRAP at tier 1, and under ratchet it holds a legacy repo to a debt ledger. This repository gates itself with go run ./cmd/gotops gate and runs advisory until the laws layer lands. vigil, the first adopter, runs the gate beside its own CI under ratchet. Mutation and the laws layer do not run yet, and nothing here is released.

Milestone Contents
M0, M0.5 spec GO_TOPS.md 0.4.0, three schemas, profiles for three launch classes, a calibration record, docs CI
M1 CLI (done) init, check, gate at tier 1 (hygiene, tests, coverage), report, lock, doctor, report.json; Go-TOPS gates itself under the advisory bootstrap rule
M2 CRAP and ratchet (done) Native CRAP: complexity, guard-neutral coverage, exemptions; baseline and the ratchet judge; Go-TOPS gates itself with CRAP on
M3 first adopter (done) vigil gated under ratchet; the first ledger written on the pull request; the adopt, gate and review skills
M4 (next) Mutation: a gremlins adapter and the survivor ledger
M5 Laws v0.1: 16 of 43 laws judged by analyzers; the kit switches its own gate to hard
M6–M7 Deep layers and the second and third adopters; the release tier and protocol 1.0

The full roadmap is in GO_TOPS.md §19. Version history is in CHANGELOG.md.

Contributing

Read GO_TOPS.md and AGENTS.md first. Work on a branch and open a PR ready for review when the step is complete. A change to laws, schema, profiles, thresholds or normative spec text is a protocol change: it carries the protocol-change label, a changelog entry, and a protocol version bump.

Credits and license

Built by Hedronite. Structure and many rules are adapted from Rust-TOPS. CRAP scores use the 2007 Change Risk Anti-Patterns formula (Savoia and Evans); this kit did not originate that metric.

Licensed under MIT OR Apache-2.0, at your option. See LICENSE, LICENSE-MIT, and LICENSE-APACHE.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

About

Protocol and drop-in kit for Go that is correct, dense, and fast.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages