prereg 0.1.0__tar.gz

prereg-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "prereg",
+  "owner": {
+    "name": "Elliot Tower"
+  },
+  "metadata": {
+    "description": "Freeze a plan before you run it, and record what changed after",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "prereg",
+      "source": "./plugin",
+      "strict": false
+    }
+  ]
+}

prereg-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install hatchling
+      - run: python -m hatchling build
+      - uses: pypa/gh-action-pypi-publish@release/v1

prereg-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.DS_Store
+*.egg-info/

prereg-0.1.0/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Elliot Tower
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+and associated documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

prereg-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.5
+Name: prereg
+Version: 0.1.0
+Summary: Freeze a plan before you run it, and record what changed after
+Author-email: Elliot Tower <elliot@elliottower.ai>
+License: MIT
+License-File: LICENSE
+Keywords: open science,osf,preregistration,reproducibility
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# prereg
+
+Freeze a plan before you run it, and record what changed after.
+
+## Install
+
+```bash
+pip install prereg
+```
+
+## Quick start
+
+```bash
+prereg new V16_reliability_ceilings
+# fill in the plan, commit it
+prereg freeze
+# run the experiment, then log what happened
+prereg log "tolerance now derived from fixtures" --access "no results seen"
+prereg check
+```
+
+```
+unchanged    V16_reliability_ceilings/PREREG.md
+```
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `prereg new <name>` | Scaffold a plan in OSF's headings |
+| `prereg freeze` | Record the commit and hash |
+| `prereg log <note>` | Append to the log without freezing |
+| `prereg check` | Has the plan changed since the freeze? |
+
+## One file, one rule
+
+```
+V16_reliability_ceilings/
+    PREREG.md      the plan, then a line, then an append-only log
+    tests/  results/
+```
+
+**Never edit above the line. Only append below it.**
+
+`prereg check` enforces it — the freeze records a hash of the plan, and any later edit to it
+fails the check. Appending to the log does not.
+
+## The log
+
+```
+2026-08-11  frozen at 9894e148e429              nothing run
+2026-08-13  tolerance now from fixtures         no results seen
+2026-08-14  ran                                 results not opened
+2026-08-15  C5 failed at k=15: 6.6% vs 5%       results seen
+```
+
+The last column is what distinguishes an amendment from a deviation, so you never have to
+decide which word to use. `nothing run`, `no results seen`, `results not opened`, `results
+seen`. An entry logged before results is an amendment; one logged after is a deviation.
+
+## Check output
+
+| Exit | Result | Meaning |
+|------|--------|---------|
+| 0 | `unchanged` | The plan says what it said |
+| 1 | `CHANGED` | The plan was edited above the line after freezing |
+| 2 | `not frozen` | No hash recorded — nothing was measured |
+
+`not frozen` is not a pass. It is the absence of a check.
+
+## The plan uses OSF's headings
+
+Verbatim, so the document maps onto an [OSF registration](https://osf.io/prereg/) without being
+rewritten. Two of the twenty-seven do the real work:
+
+- **Foreknowledge of data or evidence** — what you have already seen.
+- **Inference criteria** — the decision rule as a commitment, before the number exists.
+
+A heading that does not apply is answered `N/A` with a reason, never deleted.
+
+## What a freeze is
+
+A commit and a hash. The commit is the evidence — it is in history, dated, and not yours to
+revise quietly. The hash is the convenience that lets `prereg check` tell you in a second
+whether the plan still says what it said.
+
+Neither proves you did not run the experiment first. Nothing can: a timestamp bounds when
+something existed, never when work began.
+
+## Claude Code
+
+`plugin/` is a Claude Code plugin that tells Claude when to reach for the CLI.
+
+```bash
+/plugin marketplace add elliottower/prereg
+/plugin install prereg@prereg
+```
+
+MIT licensed.

prereg-0.1.0/README.md

@@ -0,0 +1,99 @@
+# prereg
+
+Freeze a plan before you run it, and record what changed after.
+
+## Install
+
+```bash
+pip install prereg
+```
+
+## Quick start
+
+```bash
+prereg new V16_reliability_ceilings
+# fill in the plan, commit it
+prereg freeze
+# run the experiment, then log what happened
+prereg log "tolerance now derived from fixtures" --access "no results seen"
+prereg check
+```
+
+```
+unchanged    V16_reliability_ceilings/PREREG.md
+```
+
+## Commands
+
+| Command | What it does |
+|---------|-------------|
+| `prereg new <name>` | Scaffold a plan in OSF's headings |
+| `prereg freeze` | Record the commit and hash |
+| `prereg log <note>` | Append to the log without freezing |
+| `prereg check` | Has the plan changed since the freeze? |
+
+## One file, one rule
+
+```
+V16_reliability_ceilings/
+    PREREG.md      the plan, then a line, then an append-only log
+    tests/  results/
+```
+
+**Never edit above the line. Only append below it.**
+
+`prereg check` enforces it — the freeze records a hash of the plan, and any later edit to it
+fails the check. Appending to the log does not.
+
+## The log
+
+```
+2026-08-11  frozen at 9894e148e429              nothing run
+2026-08-13  tolerance now from fixtures         no results seen
+2026-08-14  ran                                 results not opened
+2026-08-15  C5 failed at k=15: 6.6% vs 5%       results seen
+```
+
+The last column is what distinguishes an amendment from a deviation, so you never have to
+decide which word to use. `nothing run`, `no results seen`, `results not opened`, `results
+seen`. An entry logged before results is an amendment; one logged after is a deviation.
+
+## Check output
+
+| Exit | Result | Meaning |
+|------|--------|---------|
+| 0 | `unchanged` | The plan says what it said |
+| 1 | `CHANGED` | The plan was edited above the line after freezing |
+| 2 | `not frozen` | No hash recorded — nothing was measured |
+
+`not frozen` is not a pass. It is the absence of a check.
+
+## The plan uses OSF's headings
+
+Verbatim, so the document maps onto an [OSF registration](https://osf.io/prereg/) without being
+rewritten. Two of the twenty-seven do the real work:
+
+- **Foreknowledge of data or evidence** — what you have already seen.
+- **Inference criteria** — the decision rule as a commitment, before the number exists.
+
+A heading that does not apply is answered `N/A` with a reason, never deleted.
+
+## What a freeze is
+
+A commit and a hash. The commit is the evidence — it is in history, dated, and not yours to
+revise quietly. The hash is the convenience that lets `prereg check` tell you in a second
+whether the plan still says what it said.
+
+Neither proves you did not run the experiment first. Nothing can: a timestamp bounds when
+something existed, never when work began.
+
+## Claude Code
+
+`plugin/` is a Claude Code plugin that tells Claude when to reach for the CLI.
+
+```bash
+/plugin marketplace add elliottower/prereg
+/plugin install prereg@prereg
+```
+
+MIT licensed.

prereg-0.1.0/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "prereg",
+  "description": "Freeze a plan before you run it, and record what changed after",
+  "version": "0.1.0",
+  "author": { "name": "Elliot Tower", "email": "elliot@elliottower.ai" },
+  "repository": "https://github.com/elliottower/prereg",
+  "license": "MIT",
+  "keywords": ["preregistration", "reproducibility", "provenance", "experiments"]
+}

prereg-0.1.0/plugin/README.md

@@ -0,0 +1,31 @@
+# The Claude Code plugin
+
+Tells Claude the `prereg` CLI exists and when to reach for it. The CLI does the work; this adds
+nothing the CLI cannot do.
+
+## Install
+
+```bash
+/plugin marketplace add elliottower/prereg
+/plugin install prereg@prereg
+```
+
+The plugin ships instructions, not binaries. Install the tool too:
+
+```bash
+uv tool install prereg
+```
+
+For development against a checkout:
+
+```bash
+/plugin marketplace add ~/Documents/GitHub/prereg
+/plugin install prereg@prereg
+```
+
+## What it changes
+
+Claude will freeze a plan before running it rather than after, commit the PREREG.md on its own so
+the freeze is not contaminated by a code change, and log a change to a frozen plan instead of
+editing it quietly. It will also stop writing `**Status:** FROZEN` headers by hand, which produce a
+document that reads as registered and cannot be verified.

prereg-0.1.0/plugin/skills/prereg/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: prereg
+description: Freeze an experiment's plan against a commit and a content hash before running it, then log amendments and deviations. Use when writing or freezing a PREREG.md, before launching a run a plan governs, when a frozen plan needs to change, or when asked whether a plan still says what it said. Requires the `prereg` CLI (`uv tool install prereg`).
+---
+
+# prereg
+
+A plan, frozen against a commit and a hash, plus an append-only log of what changed after.
+
+## The rule that matters
+
+**Freeze before you look. Never write the header by hand.**
+
+A pre-registration is worth exactly one thing: evidence that the predictions existed before the
+data did. Every way it fails is a version of the plan moving after the numbers were seen — a
+threshold nudged, a hypothesis dropped, a subgroup added. The freeze exists so that movement leaves
+a trace, and a hand-written `**Status:** FROZEN` header leaves none. It produces a document that
+reads as registered and cannot be verified, which is worse than one that never claimed to be.
+
+`**Status:**`, `**Plan sha256:**` and `**Frozen:**` are the tool's output. Writing them yourself is
+the one thing this skill exists to prevent.
+
+## Commands
+
+```bash
+prereg new <name>      # scaffold PREREG.md in OSF's headings, plus tests/ and results/
+prereg freeze          # write the header, hash the plan, append to the log
+prereg log <note> --access <level>
+prereg check           # has anything above the log line changed since the freeze?
+```
+
+## Freezing, in order
+
+1. **Write the plan, then get it reviewed.** A plan frozen without review registers the author's
+   guesses, not an agreed design.
+2. **Commit the PREREG.md alone.** No code in that commit. A freeze whose commit also carries a
+   code change cannot distinguish the registered design from the change made while registering it.
+3. **`prereg freeze`** in the experiment directory. It refuses on a dirty tree, because the freeze
+   names a commit.
+4. **Commit the freeze header.** The freeze is only evidence once it is in history.
+5. **Then run.** Not before step 4.
+
+## Reading `prereg check`
+
+Three results, exhaustive:
+
+| exit | | |
+|---|---|---|
+| 0 | `unchanged` | the plan says what it said |
+| 1 | `CHANGED` | the plan was edited above the log line after freezing |
+| 2 | `not frozen` | no hash recorded — **nothing was measured** |
+
+**`not frozen` is not a pass.** It is the absence of a check, and it reads identically to success
+if you only look at whether the command complained.
+
+**`CHANGED` is not fixed by re-freezing.** Re-freezing overwrites the evidence that the plan moved.
+Restore the plan and `prereg log` the change with an honest `--access`.
+
+At a repository root with no governing plan, `check` checks every plan below it.
+
+## Amendments and deviations
+
+`--access` is one of `nothing run`, `no results seen`, `results not opened`, `results seen`. It
+records what was known when the change was made, so the distinction is never a judgment call: an
+entry logged before results is an amendment, one logged after is a deviation. Log the honest level
+even when it is the damaging one — that is the entire function of the field.
+
+## When to reach for this
+
+- Before launching any run whose result will be reported as confirmatory
+- When a plan is ready to freeze, after review
+- When a frozen plan has to change — log first, never edit silently
+- Before reporting a result a plan governs, to confirm the plan still says what it said
+- In CI, as `prereg check`
+
+## Non-obvious behavior
+
+- `freeze` is idempotent: the commit, digest and date sit on lines the hash skips, so re-freezing
+  an unedited plan reproduces its hash.
+- `--force` re-freezes an already-frozen plan. Use it when the plan legitimately changed and was
+  re-committed, never to clear a `CHANGED` warning.
+- Appending below the log line is the allowed edit and does not fail `check`.
+
+## What it will not do
+
+It cannot prove you did not run the experiment first. Nothing can: a timestamp bounds when
+something existed, never when the work began. It also cannot tell you the plan was any good — a
+frozen bad design is still a bad design, registered.

prereg-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "prereg"
+version = "0.1.0"
+description = "Freeze a plan before you run it, and record what changed after"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Elliot Tower", email = "elliot@elliottower.ai" }]
+keywords = ["preregistration", "reproducibility", "open science", "osf"]
+dependencies = ["PyYAML>=6.0"]
+
+[project.scripts]
+prereg = "prereg.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/prereg"]

prereg-0.1.0/src/prereg/__init__.py

@@ -0,0 +1,2 @@
+"""Freeze a plan before you run it, and record what changed after."""
+__version__ = "0.1.0"

prereg-0.1.0/src/prereg/cli.py

@@ -0,0 +1,325 @@
+"""Freeze a plan before you run it, and record what changed after.
+
+    prereg new <name>     scaffold the plan, in OSF's headings
+    prereg freeze         record the commit and hash, append to the log
+    prereg log <note>     append a line without freezing
+    prereg check          has anything above the line changed since the freeze?
+
+One file per experiment, one rule: never edit above the line, only append below it.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime
+import hashlib
+import pathlib
+import re
+import subprocess
+import sys
+
+from prereg import template
+
+PREREG = "PREREG.md"
+MARK = "\n---\n\n## Log\n"
+ACCESS = ["nothing run", "no results seen", "results not opened", "results seen"]
+
+
+def today() -> str:
+    return datetime.date.today().isoformat()
+
+
+def git(*args, cwd=None) -> str:
+    r = subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True)
+    return r.stdout.strip() if r.returncode == 0 else ""
+
+
+def find(start: pathlib.Path | None = None) -> pathlib.Path | None:
+    """The PREREG.md governing this directory: here, or the nearest one above."""
+    here = (start or pathlib.Path.cwd()).resolve()
+    for d in [here, *here.parents]:
+        if (d / PREREG).is_file():
+            return d / PREREG
+    return None
+
+
+def plan_of(text: str) -> str:
+    """What the freeze hashes: the plan, minus its own status block.
+
+    The status lines carry the commit, the hash and the freeze date, and they are written into
+    the file by `freeze` itself. Including them would mean the hash covered a value derived
+    from the hash, so the check could never pass.
+    """
+    i = text.find(MARK)
+    plan = text if i < 0 else text[:i]
+    keep = [ln for ln in plan.splitlines()
+            if not ln.startswith(("**Status:**", "**Plan sha256:**", "**Frozen:**"))]
+    return "\n".join(keep).strip() + "\n"
+
+
+def sha256_of(s: str) -> str:
+    return hashlib.sha256(s.encode()).hexdigest()
+
+
+def unhashed_content(text: str) -> list[str]:
+    """Parts of the plan the hash would not cover, which `freeze` refuses to register.
+
+    Two things are skipped when hashing, both for good reasons, and both exploitable if they
+    appear where they are not meant to. The log marker ends the hashed region, so a second one
+    in the body leaves everything after it editable without `check` noticing. Marker-prefixed
+    lines are skipped because `freeze` writes them, so one in the body is editable the same way.
+
+    Refusing is better than hashing them anyway: changing what the hash covers would invalidate
+    every plan already frozen, while refusing only affects plans not yet registered.
+    """
+    problems = []
+    if text.count(MARK) > 1:
+        problems.append(
+            "the log marker (`---` then `## Log`) appears more than once. Hashing stops at the "
+            "first, so the plan after it would not be covered.")
+    i = text.find(MARK)
+    plan = text if i < 0 else text[:i]
+    m = STATUS_BLOCK.search(plan)
+    body = (plan[:m.start()] + plan[m.end():]) if m else plan
+    stray = [ln for ln in body.splitlines()
+             if ln.startswith(("**Status:**", "**Plan sha256:**", "**Frozen:**"))]
+    if stray:
+        problems.append(
+            "these lines sit outside the status block and are skipped when hashing, so they "
+            "could be edited after freezing without `check` noticing:\n      "
+            + "\n      ".join(stray[:5]))
+    return problems
+
+
+STATUS_BLOCK = re.compile(r"^\*\*Status:\*\*.*?(?=\n[ \t]*\n|\Z)", re.S | re.M)
+
+# A status line may carry a note after its sentence — "third version; see Log".
+# The note is plan content and has to survive a freeze; the marker and its own
+# value do not.
+STATUS_VALUES = [
+    re.compile(r"^\*\*Status:\*\*[ \t]*DRAFT[ \t]*—[ \t]*not frozen\.?"),
+    re.compile(r"^\*\*Status:\*\*[ \t]*FROZEN at `[^`]*`\.?"),
+    re.compile(r"^\*\*Plan sha256:\*\*[ \t]*`[0-9a-f]*`\.?"),
+    re.compile(r"^\*\*Frozen:\*\*[ \t]*\d{4}-\d{2}-\d{2}\.?"),
+]
+
+
+def status_note(block: str) -> str:
+    """Whatever the status block says beyond the markers' own values."""
+    out = []
+    for line in block.splitlines():
+        for rx in STATUS_VALUES:
+            stripped = rx.sub("", line, count=1)
+            if stripped != line:
+                line = stripped
+                break
+        if line.strip():
+            out.append(line.strip())
+    return " ".join(out)
+
+
+def rewrite_status(text: str, commit: str, digest: str, date: str) -> str:
+    """Replace the whole status block, draft or already frozen.
+
+    Matching only the literal draft sentence did nothing on a plan that was
+    already frozen, so `--force` printed a new hash, wrote none of it, and left
+    the plan failing its own check — silently, with a zero exit code. Matching
+    the block also stops a note written after `**Status:**` from being glued onto
+    the freeze date, which is what a prefix-only replacement did to it.
+    """
+    m = STATUS_BLOCK.search(text)
+    if m is None:
+        return text
+    note = status_note(m.group(0))
+    block = (f"**Status:** FROZEN at `{commit[:12]}`\n"
+             f"**Plan sha256:** `{digest}`\n"
+             f"**Frozen:** {date}")
+    if note:
+        block += f"\n{note}"
+    return text[:m.start()] + block + text[m.end():]
+
+
+def append(path: pathlib.Path, date: str, event: str, access: str) -> None:
+    text = path.read_text()
+    if MARK not in text:
+        text += MARK.rstrip("\n") + "\n\n```\n```\n"
+    head, _, tail = text.partition(MARK)
+    # Two spaces, not just padding. `{event:<36}` emits nothing extra once the note passes 36
+    # characters, and the access level then runs into the note — losing the boundary of the one
+    # field that separates an amendment from a deviation.
+    line = f"{date}  {event:<36}  {access}"
+    if "```" in tail:
+        before, fence, after = tail.rpartition("```")
+        tail = before.rstrip("\n") + f"\n{line}\n" + fence + after
+    else:
+        tail = tail.rstrip("\n") + f"\n{line}\n"
+    path.write_text(head + MARK + tail)
+
+
+def cmd_new(a) -> int:
+    d = pathlib.Path(a.name)
+    if (d / PREREG).exists():
+        print(f"{d / PREREG} already exists")
+        return 1
+    (d / "tests").mkdir(parents=True, exist_ok=True)
+    (d / "results").mkdir(exist_ok=True)
+    title = a.title or d.name.replace("_", " ").replace("-", " ")
+    (d / PREREG).write_text(template.render(title, today()))
+    print(f"created {d}/")
+    print(f"  {PREREG}   the plan, in OSF's headings")
+    print(f"  tests/  results/")
+    print("\nfill it in, then `prereg freeze`. Never edit above the log line afterwards.")
+    return 0
+
+
+def cmd_freeze(a) -> int:
+    path = find()
+    if path is None:
+        print(f"no {PREREG} here or above. `prereg new <name>` makes one.")
+        return 2
+    text = path.read_text()
+    if STATUS_BLOCK.search(text) is None:
+        print(f"{path} has no `**Status:**` line, so there is nowhere to record the freeze.")
+        print("Add one — `**Status:** DRAFT — not frozen.` — or scaffold with `prereg new`.")
+        return 1
+    if "**Status:** DRAFT" not in text and not a.force:
+        print(f"{path} is already frozen. Use `prereg log` to append, or --force.")
+        return 1
+
+    problems = unhashed_content(text)
+    if problems:
+        print(f"{path} has content the freeze would not cover:\n")
+        for p in problems:
+            print(f"  - {p}")
+        print("\nA freeze that leaves part of the plan editable is worse than none, because it"
+              "\nreads as registered. Fix these and freeze again.")
+        return 1
+
+    repo = path.parent
+    dirty = git("status", "--porcelain", str(path), cwd=repo)
+    if dirty and not a.force:
+        print(f"{path} has uncommitted changes. Commit first — the freeze names a commit.")
+        return 1
+
+    commit = git("rev-parse", "HEAD", cwd=repo) or "(not in a git repository)"
+    # Normalize the layout first, then hash. Freezing moves any status note onto
+    # its own line, and `plan_of` skips marker lines but not that one, so hashing
+    # the pre-freeze text would store a digest of a layout the file no longer has
+    # and `check` would fail on the freeze itself. Hashing after also makes the
+    # freeze idempotent: commit and date sit on skipped lines, so re-freezing an
+    # unedited plan reproduces the same digest.
+    placeholder = "0" * 64
+    text = rewrite_status(text, commit, placeholder, today())
+    digest = sha256_of(plan_of(text))
+    text = text.replace(f"`{placeholder}`", f"`{digest}`", 1)
+    path.write_text(text)
+    append(path, today(), f"frozen at {commit[:12]}", "nothing run")
+    print(f"frozen  {path}")
+    print(f"  commit  {commit[:12]}")
+    print(f"  sha256  {digest[:16]}…  (of everything above the log)")
+    print("\nCommit this. The freeze is only evidence once it is in history.")
+    return 0
+
+
+def cmd_log(a) -> int:
+    path = find()
+    if path is None:
+        print(f"no {PREREG} here or above.")
+        return 2
+    if a.access not in ACCESS:
+        print(f"access must be one of: {', '.join(ACCESS)}")
+        return 1
+    # The log is the tamper record, so a note is not free text. One line of it is one entry, and
+    # a note carrying a newline writes a second line that reads exactly like an entry somebody
+    # made — including a `frozen at ...` one. A fence closes the block early and puts everything
+    # after it outside the log.
+    if "\n" in a.note or "\r" in a.note:
+        print("a note is one line — a newline in it would read as a second log entry.")
+        return 1
+    if "```" in a.note:
+        print("a note cannot contain ``` — it would close the log block early.")
+        return 1
+    append(path, today(), a.note, a.access)
+    print(f"logged: {a.note}  ({a.access})")
+    if a.access == "results seen":
+        print("\nRecorded as a deviation: the results were already known.")
+    return 0
+
+
+def check_one(path: pathlib.Path) -> int:
+    """0 unchanged, 1 changed, 2 not frozen."""
+    text = path.read_text()
+    m = re.search(r"\*\*Plan sha256:\*\* `([0-9a-f]{64})`", text)
+    if not m:
+        print(f"not frozen   {path}")
+        return 2
+    now = sha256_of(plan_of(text))
+    if now == m.group(1):
+        print(f"unchanged    {path}")
+        return 0
+    print(f"CHANGED      {path}")
+    print(f"  frozen  {m.group(1)[:16]}…")
+    print(f"  now     {now[:16]}…")
+    return 1
+
+
+def cmd_check(a) -> int:
+    """Check the governing plan, or every plan below when there is none.
+
+    A repository usually holds one plan per experiment, side by side, so running this at the
+    root has to mean "check them all" — otherwise the command is unusable from the one place
+    someone would naturally run it.
+    """
+    path = find()
+    if path is not None:
+        rc = check_one(path)
+        if rc == 1:
+            print("\nThe plan was edited after freezing. Restore it and record the change in the log.")
+        elif rc == 2:
+            print("\nNothing to check against yet. `prereg freeze` records the hash.")
+        return rc
+
+    found = sorted(pathlib.Path.cwd().rglob(PREREG))
+    if not found:
+        print(f"no {PREREG} here, above, or below.")
+        return 2
+
+    codes = [check_one(f) for f in found]
+    changed = codes.count(1)
+    print(f"\n{len(found)} plans: {codes.count(0)} unchanged, {changed} changed, "
+          f"{codes.count(2)} not frozen")
+    if changed:
+        print("A changed plan was edited after freezing. Restore it and record the change.")
+    return 1 if changed else 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(prog="prereg", description=__doc__.split("\n")[0])
+    sub = ap.add_subparsers(dest="cmd")
+
+    n = sub.add_parser("new", help="scaffold a plan")
+    n.add_argument("name")
+    n.add_argument("--title")
+    n.set_defaults(fn=cmd_new)
+
+    f = sub.add_parser("freeze", help="record the commit and hash")
+    f.add_argument("--force", action="store_true")
+    f.set_defaults(fn=cmd_freeze)
+
+    lg = sub.add_parser("log", help="append a line")
+    lg.add_argument("note")
+    lg.add_argument("--access", default="no results seen",
+                    help=f"one of: {', '.join(ACCESS)}")
+    lg.set_defaults(fn=cmd_log)
+
+    c = sub.add_parser("check", help="has the plan changed since the freeze?")
+    c.set_defaults(fn=cmd_check)
+
+    a = ap.parse_args()
+    if not a.cmd:
+        ap.print_help()
+        return 0
+    return a.fn(a)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

prereg-0.1.0/src/prereg/template.py

@@ -0,0 +1,82 @@
+"""The plan, under OSF's question titles.
+
+Using OSF's headings verbatim costs nothing and means the document maps onto a registration
+without being rewritten. Two of them do the real work:
+
+    Foreknowledge of data or evidence   forces you to say what you have already seen
+    Inference criteria                  forces the decision rule to be a commitment
+
+A heading that does not apply is answered N/A with a reason, never deleted. A deleted heading
+and an inapplicable one look identical in a file and very different to a reader.
+"""
+from __future__ import annotations
+
+# Verbatim from the OSF Preregistration schema, in order.
+QUESTIONS = [
+    ("Research questions or hypotheses", "What is being asked, and what would count as an answer."),
+    ("Foreknowledge of data or evidence",
+     "What have you already seen? Pilot runs, exploratory results, anything from a related "
+     "study. If nothing, say so."),
+    ("Explanation of foreknowledge and managing unintended influences",
+     "How the answer above does or does not constrain the predictions below."),
+    ("Study type", "Experimental, observational, meta-analytic."),
+    ("Intention for causal interpretation", "Or N/A if no causal claim is intended."),
+    ("Blinding of experimental treatments", ""),
+    ("Additional blinding during research or analysis", ""),
+    ("Study design", ""),
+    ("Randomization", ""),
+    ("Data collection procedures", ""),
+    ("Data collection procedures - File upload", ""),
+    ("Sample size", "And what it can and cannot detect."),
+    ("Sample size rationale", ""),
+    ("Starting and stopping rules", ""),
+    ("Manipulated variables", ""),
+    ("Measured variables", ""),
+    ("Measured variables - File upload", ""),
+    ("Indices", ""),
+    ("Indices - File upload", ""),
+    ("Statistical models", ""),
+    ("Statistical models - File upload", ""),
+    ("Transformations", ""),
+    ("Inference criteria",
+     "The decision rule, as a commitment, before the number exists. A threshold, not a hope."),
+    ("Data inclusion and exclusion", ""),
+    ("Missing data", ""),
+    ("Other planned analysis", "Anything beyond the above is exploratory and labelled so."),
+    ("Context and additional information", ""),
+]
+
+HEADER = """\
+# {title}
+
+**Status:** DRAFT — not frozen.
+
+Sections use the [OSF Preregistration](https://osf.io/prereg/) question titles verbatim, so
+this maps onto a registration without being rewritten. A question that does not apply is
+answered **N/A** with the reason, never deleted.
+"""
+
+LOG = """\
+
+---
+
+## Log
+
+Append only. Never edit above the line.
+
+The last column is what distinguishes an amendment from a deviation, so you do not have to
+decide which word to use: `nothing run`, `no results seen`, `results not opened`, `results seen`.
+
+```
+{date}  created                              nothing run
+```
+"""
+
+
+def render(title: str, date: str) -> str:
+    parts = [HEADER.format(title=title)]
+    for q, hint in QUESTIONS:
+        parts.append(f"\n## {q}\n")
+        parts.append(f"_{hint}_\n" if hint else "N/A — \n")
+    parts.append(LOG.format(date=date))
+    return "".join(parts)

prereg-0.1.0/tests/test_freeze.py

@@ -0,0 +1,247 @@
+"""A freeze is only worth anything if editing the plan afterwards is detectable."""
+from __future__ import annotations
+
+import subprocess
+import sys
+
+import pytest
+
+from prereg import cli
+
+
+def run(args, cwd):
+    return subprocess.run([sys.executable, "-m", "prereg.cli", *args],
+                          cwd=cwd, capture_output=True, text=True)
+
+
+@pytest.fixture
+def repo(tmp_path):
+    subprocess.run(["git", "init", "-q"], cwd=tmp_path)
+    run(["new", "study"], tmp_path)
+    subprocess.run(["git", "add", "-A"], cwd=tmp_path)
+    subprocess.run(["git", "-c", "user.email=t@t", "-c", "user.name=t",
+                    "commit", "-q", "-m", "init"], cwd=tmp_path)
+    return tmp_path / "study"
+
+
+def test_new_uses_the_osf_headings(tmp_path):
+    run(["new", "study"], tmp_path)
+    text = (tmp_path / "study" / "PREREG.md").read_text()
+    for q, _ in cli.template.QUESTIONS:
+        assert f"## {q}" in text
+
+
+def test_the_two_headings_that_do_the_work_are_present(tmp_path):
+    run(["new", "study"], tmp_path)
+    text = (tmp_path / "study" / "PREREG.md").read_text()
+    assert "## Foreknowledge of data or evidence" in text
+    assert "## Inference criteria" in text
+
+
+def test_check_passes_immediately_after_freeze(repo):
+    run(["freeze"], repo)
+    assert run(["check"], repo).returncode == 0
+
+
+def test_editing_the_plan_is_detected(repo):
+    run(["freeze"], repo)
+    p = repo / "PREREG.md"
+    p.write_text(p.read_text().replace("## Randomization", "## Randomisation"))
+    r = run(["check"], repo)
+    assert r.returncode == 1
+    assert "CHANGED" in r.stdout
+
+
+def test_appending_to_the_log_is_not_a_change(repo):
+    run(["freeze"], repo)
+    run(["log", "tolerance from fixtures", "--access", "no results seen"], repo)
+    assert run(["check"], repo).returncode == 0, "appending below the line is the allowed edit"
+
+
+def test_freezing_twice_is_refused(repo):
+    run(["freeze"], repo)
+    assert run(["freeze"], repo).returncode == 1
+
+
+def test_freeze_refuses_uncommitted_changes(tmp_path):
+    subprocess.run(["git", "init", "-q"], cwd=tmp_path)
+    run(["new", "study"], tmp_path)
+    r = run(["freeze"], tmp_path / "study")
+    assert r.returncode == 1
+    assert "Commit first" in r.stdout
+
+
+def test_an_unknown_access_value_is_refused(repo):
+    run(["freeze"], repo)
+    r = run(["log", "something", "--access", "probably fine"], repo)
+    assert r.returncode == 1
+
+
+def test_results_seen_is_called_a_deviation(repo):
+    run(["freeze"], repo)
+    r = run(["log", "criterion failed", "--access", "results seen"], repo)
+    assert "deviation" in r.stdout
+
+
+def test_check_on_an_unfrozen_plan_does_not_report_success(tmp_path):
+    run(["new", "study"], tmp_path)
+    assert run(["check"], tmp_path / "study").returncode != 0
+
+
+def test_commands_find_the_plan_from_a_subdirectory(repo):
+    run(["freeze"], repo)
+    (repo / "results").mkdir(exist_ok=True)
+    assert run(["check"], repo / "results").returncode == 0
+
+
+def test_force_refreeze_rewrites_the_header_it_prints(repo):
+    run(["freeze"], repo)
+    p = repo / "PREREG.md"
+    p.write_text(p.read_text().replace("## Randomization", "## Randomization\n\nBy seed."))
+    subprocess.run(["git", "add", "-A"], cwd=repo)
+    subprocess.run(["git", "-c", "user.email=t@t", "-c", "user.name=t",
+                    "commit", "-q", "-m", "edit"], cwd=repo)
+    r = run(["freeze", "--force"], repo)
+    printed = [w for w in r.stdout.split() if len(w.rstrip("…")) == 16][-1].rstrip("…")
+    assert printed in p.read_text(), "freeze printed a digest it did not write"
+    assert run(["check"], repo).returncode == 0
+
+
+def test_status_note_survives_the_freeze_intact(repo):
+    p = repo / "PREREG.md"
+    p.write_text(p.read_text().replace(
+        "**Status:** DRAFT — not frozen.",
+        "**Status:** DRAFT — not frozen. Third version; see Log."))
+    subprocess.run(["git", "add", "-A"], cwd=repo)
+    subprocess.run(["git", "-c", "user.email=t@t", "-c", "user.name=t",
+                    "commit", "-q", "-m", "note"], cwd=repo)
+    run(["freeze"], repo)
+    text = p.read_text()
+    frozen_line = next(ln for ln in text.splitlines() if ln.startswith("**Frozen:**"))
+    assert frozen_line.strip().endswith(cli.today()), \
+        f"note was glued onto the freeze date: {frozen_line!r}"
+    assert "Third version; see Log." in text
+    assert run(["check"], repo).returncode == 0
+
+
+def test_refreezing_an_unedited_plan_is_idempotent(repo):
+    run(["freeze"], repo)
+    first = (repo / "PREREG.md").read_text()
+    digest = cli.re.search(r"`([0-9a-f]{64})`", first).group(1)
+    run(["freeze", "--force"], repo)
+    second = (repo / "PREREG.md").read_text()
+    assert cli.re.search(r"`([0-9a-f]{64})`", second).group(1) == digest
+    assert run(["check"], repo).returncode == 0
+
+
+# --- what the hash does not cover ------------------------------------------------------------
+
+def test_freeze_refuses_a_plan_with_no_status_line(repo):
+    p = repo / "PREREG.md"
+    p.write_text(p.read_text().replace("**Status:** DRAFT — not frozen.", ""))
+    subprocess.run(["git", "add", "-A"], cwd=repo)
+    subprocess.run(["git", "-c", "user.email=t@t", "-c", "user.name=t",
+                    "commit", "-q", "-m", "no status"], cwd=repo)
+    r = run(["freeze"], repo)
+    assert r.returncode != 0, "reported a freeze it did not perform"
+    assert "not frozen" not in run(["check"], repo).stdout or r.returncode != 0
+
+
+def test_a_status_marker_in_the_body_cannot_hide_from_the_hash(repo):
+    """Marker-prefixed lines are skipped when hashing, so one in the body would be editable
+    after freezing without `check` noticing."""
+    p = repo / "PREREG.md"
+    p.write_text(p.read_text().replace(
+        "## Randomization",
+        "## Randomization\n\n**Frozen:** whatever the author likes\n"))
+    subprocess.run(["git", "add", "-A"], cwd=repo)
+    subprocess.run(["git", "-c", "user.email=t@t", "-c", "user.name=t",
+                    "commit", "-q", "-m", "marker in body"], cwd=repo)
+    r = run(["freeze"], repo)
+    assert r.returncode == 1, "froze a plan whose body line the hash does not cover"
+    assert "**Frozen:** whatever the author likes" in r.stdout, \
+        "the refusal must name the offending line"
+
+
+def test_a_log_marker_in_the_body_cannot_truncate_the_hash(repo):
+    """Hashing stops at the log marker. One in the body would leave the real plan after it
+    unhashed and freely editable."""
+    p = repo / "PREREG.md"
+    p.write_text(p.read_text().replace(
+        "## Randomization",
+        "## Randomization\n\nSeeds 0-4.\n\n---\n\n## Log\n\n## Sample size\n\nn=300 per arm.\n"))
+    subprocess.run(["git", "add", "-A"], cwd=repo)
+    subprocess.run(["git", "-c", "user.email=t@t", "-c", "user.name=t",
+                    "commit", "-q", "-m", "marker in body"], cwd=repo)
+    r = run(["freeze"], repo)
+    assert r.returncode == 1, "froze a plan whose tail the hash does not cover"
+    assert "more than once" in r.stdout
+
+
+def test_line_endings_do_not_change_the_hash(repo):
+    run(["freeze"], repo)
+    p = repo / "PREREG.md"
+    p.write_bytes(p.read_text().replace("\n", "\r\n").encode())
+    assert run(["check"], repo).returncode == 0, \
+        "a checkout with CRLF endings must not read as a tampered plan"
+
+
+def test_trailing_whitespace_alone_is_not_a_change(repo):
+    run(["freeze"], repo)
+    p = repo / "PREREG.md"
+    p.write_text(p.read_text() + "\n\n")
+    assert run(["check"], repo).returncode == 0
+
+
+# --- the log is the tamper record, so it is worth attacking -----------------------------------
+
+def test_a_log_note_cannot_forge_another_entry(repo):
+    run(["freeze"], repo)
+    run(["log", "harmless\n2020-01-01  frozen at 000000000000        nothing run",
+         "--access", "no results seen"], repo)
+    text = (repo / "PREREG.md").read_text()
+    assert "2020-01-01  frozen at" not in text, \
+        "a newline in a note forged a second log entry"
+
+
+def test_a_log_note_cannot_break_out_of_the_fence(repo):
+    run(["freeze"], repo)
+    run(["log", "see ``` and then some", "--access", "no results seen"], repo)
+    text = (repo / "PREREG.md").read_text()
+    _, _, tail = text.partition(cli.MARK)
+    assert tail.count("```") == 2, f"fence count is {tail.count('```')}, log structure broken"
+
+
+def test_freezing_without_a_commit_says_so(tmp_path):
+    subprocess.run(["git", "init", "-q"], cwd=tmp_path)
+    run(["new", "study"], tmp_path)
+    r = run(["freeze"], tmp_path / "study")
+    assert "(not in a git repository)" not in (tmp_path / "study" / "PREREG.md").read_text(), \
+        "wrote a placeholder where a commit should be"
+
+
+def test_check_at_a_root_fails_if_any_plan_below_it_changed(tmp_path):
+    subprocess.run(["git", "init", "-q"], cwd=tmp_path)
+    for name in ("good", "bad"):
+        run(["new", name], tmp_path)
+    subprocess.run(["git", "add", "-A"], cwd=tmp_path)
+    subprocess.run(["git", "-c", "user.email=t@t", "-c", "user.name=t",
+                    "commit", "-q", "-m", "init"], cwd=tmp_path)
+    run(["freeze"], tmp_path / "good")
+    run(["freeze"], tmp_path / "bad")
+    p = tmp_path / "bad" / "PREREG.md"
+    p.write_text(p.read_text().replace("## Randomization", "## Randomisation"))
+    assert run(["check"], tmp_path).returncode != 0, \
+        "a root check passed while a plan below it had been edited"
+
+
+def test_a_long_note_still_separates_from_its_access_level(repo):
+    """The access level is what distinguishes an amendment from a deviation, so it must never
+    run into the note."""
+    run(["freeze"], repo)
+    note = "restricting the target to {0,1} and {0,1,2} because its value set is integers"
+    run(["log", note, "--access", "no results seen"], repo)
+    line = next(ln for ln in (repo / "PREREG.md").read_text().splitlines() if note in ln)
+    assert line.endswith("no results seen")
+    assert not line.endswith(note + "no results seen"), "access level glued to the note"
+    assert "  no results seen" in line