punchtape logo

punchtape

0

A state machine that makes your AI get the entire job done — start to finish, with every claim proven. Any agent, any stack. Offline, MIT. done: true has to be earned.

1 skills

punchtape

An external state machine that makes AI coding agents earn done. Your words are the law of the task, every check runs outside the agent, and the finish is sealed with a checksum. Any agent with a shell, any stack. Offline, MIT.

# punchtape punchtape is an external state machine beside you: it holds the task's truth. The human's words sit in `.punchtape/demands.md`, verbatim, one demand a line - they are the law of the task. The machine measures your work against the claims you pin. You never self-certify: `done: true` is the completion act, and whether the work stands done is the machine's verdict, never your announcement. ## When to Use - The repo has a `.punchtape/` directory (check the current directory and every parent). - The human mentions punchtape or asks for machine-verified task completion. ## When NOT to Use - The repo has no zone and the human has not asked for punchtape: do not install or birth a zone on your own initiative. - The task is a one-line answer with no code or files to verify - answer directly. - The human wants a code review or a discussion partner - use a review skill. This skill is about earning a finish, not opinions. ## Prerequisites - punchtape installed (`command -v punchtape`). Homebrew: `brew install neurophant/tap/punchtape` (macOS, Linux x86_64). Other install paths and the full bootstrap live in the repo: https://github.com/neurophant/punchtape/blob/main/docs/BOOTSTRAP.md - Linux or macOS on amd64/arm64. Windows is not supported yet - say so to the human and stop. - A unix shell. Any agent with a shell works. The machine does not care which model stands behind it. ## Find the situation first 1. Check for a zone: a `.punchtape/` directory in the current directory or any parent. 2. Check the machine: `command -v punchtape` (empty output - not installed). Name the situation you found, offer two to four options, and WAIT for the human's pick. Never install, birth a zone, or start work on your own initiative. - **No machine, no zone.** Offer: install now and start this project under punchtape - install and just read the printed contract - not now. - **Installed, no zone in this project.** Offer: bring this standing project under punchtape - start a fresh task in a new folder - not now. - **A zone stands.** Do not offer to bypass it. Read `.punchtape/state.md` (the standing and the `next:` line), then `.punchtape/report.md` for the last facts, and propose the work the `next:` line names. ## Birth, once per project (only if the human picks it) 1. Run `punchtape`. With no zone yet it prints the whole contract and creates nothing - read it. That text is the law you will work under. 2. Create `.punchtape/demands.md` and put the human's words into it: verbatim, one demand a line, nothing of yours mixed in. 3. Run `punchtape` again - that run births the zone. ## The daily loop inside a zone - New words from the human enter `demands.md` at any moment: append them verbatim, one demand a line. - Files of the zone: `contract.md` (the law), `reference.md` (every door - read it first), `state.md` (standing + `next:`), `report.md` (last run's facts), `template.yaml` (the submission shape), `inbox.yaml` (submissions), `journal/` (the machine's own record). - Submissions go to `inbox.yaml` by the shape of `template.yaml`. - Never edit anything inside `journal/` by hand: the machine checks every record and rejects any mismatch. - When in doubt, run `punchtape` and read what it says. One line of terminal, nothing else. ## Refusals - A refused submission stays in `inbox.yaml`. The report names the exact place and the exact law: fix the file in place and run again. Nothing is lost. - The submission is YAML and YAML has sharp edges: quoting rules, no tabs. This is the most common refusal. Read the named place, fix it, run again. - A zone born on another version of punchtape is refused: archive it and start fresh. Do not work around it. ## Several agents Runs take turns automatically, one at a time. The machine does not split the work between agents - who does what is the human's call. ## Example A real zone, start to verdict (machine one-liners quoted from a live v0.5.1 session): 1. `demands.md` holds one line: `say hello and nothing else`. 2. The agent writes `hello` (prints exactly `hello`) and submits the document: an execute intent for D1 with `run: "./hello"`, plus a behavior `hello/say` whose row pins the exact bytes: ```yaml work: first document - a hello script, pinned to the demand's exact words intents: - {lines: [D1], outcome: execute, prose: the demand says hello and nothing else, run: "./hello"} remove: [] behaviors: - id: hello/say name: say hello prose: prints hello and nothing else claims: ["hello:1-2"] rows: - run: "./hello" expect: rc: 0 out: "hello\n" ``` 3. The machine answers, one line per run: ```text punchtape: run 1 - 9 uncovered lines - submit their claims or loud exclusions to .punchtape/inbox.yaml punchtape: run 1 - all green - write done: true to .punchtape/inbox.yaml and run to record the verdict punchtape: run 1 - verdict #1 standing - show .punchtape/state.md to the human; new work goes to .punchtape/inbox.yaml as a document ``` Expected result: the uncovered lines (the machine's own AGENTS.md block) are excluded loudly with a citing reason, the check runs green with a proof hash, and `done: true` lands a standing verdict with a signature. The agent never announces done - the machine does. ## Limitations - Offline and local: the machine makes no network calls, has no account, no telemetry. - The machine compares real output byte by byte. It never reads meaning. A recorded finish proves the checks passed exactly as written - the last look stays with the human. - It cannot know a word that was never written down: demands come from `demands.md`, never from your chat. - One zone, one machine version. Cross-version zones are refused. ## Safety and side effects - The machine runs only when called. Whatever a command left running dies with it. No background processes. - Commands inside checks execute with the agent's shell permissions - propose only what the human asked for. - Nothing hides: every refusal names its exact place and law, and every exclusion is loud, with a reason. ## Ground rules - Work from what you can see: quote what commands really printed. Never invent a terminal line, a file's content, or a result. - Green, red, stale, verdict - those words mean what `.punchtape/state.md` and `.punchtape/report.md` record, nothing else. ## Sources - Repo: https://github.com/neurophant/punchtape - Bootstrap: https://github.com/neurophant/punchtape/blob/main/docs/BOOTSTRAP.md - Site with a recorded session: https://punchtape.dev