prereg 0.1.0__py3-none-any.whl

prereg/__init__.py

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

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+prereg/__init__.py,sha256=mBQq0zoaUgKXOxFCAbKnf6fDc6-54-hg-WIwOBnD2Ps,92
+prereg/cli.py,sha256=lKnSqeVDUlRQAQHbZYpW1kkHKsc0jZIA10Yhtqls9Gc,12489
+prereg/template.py,sha256=FRBeVubycDUJ5agMEvIpQtWbb3xDh_ICC1OfP8F4824,3128
+prereg-0.1.0.dist-info/METADATA,sha256=jF0MgV_Kw2p9IVUhg73hNK9wfo7ajPyuUdNhvNS1Jm4,3280
+prereg-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+prereg-0.1.0.dist-info/entry_points.txt,sha256=ipPK_DL-7qDJZD2MYJBm_rIziZ20BtIMHdfbXAT1dCw,43
+prereg-0.1.0.dist-info/licenses/LICENSE,sha256=5Cxc8x04RnJhPINqLjdKNIGXE1Fp6Dle0jaj9x1xQW8,1069
+prereg-0.1.0.dist-info/RECORD,,

prereg-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

prereg-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+prereg = prereg.cli:main

prereg-0.1.0.dist-info/licenses/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.