troupe-standup/wizard-work/null/wizard.py

#!/usr/bin/env python3
"""null standup entry — Codeforge lane.

Rebuilds the log from parameters, never from the wall clock:

    python3 wizard.py            # writes wizard.log.md next to this file
    python3 check.py             # exit 0 == artifact is real, exit 1 == broken

Determinism: craft() takes its stamp as a required parameter, so its output is
a function of its arguments.  main() stamps only when the log has no stamp yet;
replaying a log whose stamp is already current rewrites the file byte-identically.

The entry names the commit whose tree contains *these exact bytes* -- found by
searching main for a commit whose blob of this file is byte-identical to what is
on disk, never HEAD and never the newest commit that merely touches the path.
Two traps that naive versions of this fall into:
  * naming HEAD goes stale the moment a teammate commits, so the gate stays
    green for a tree main no longer has;
  * naming the newest commit that touches the path goes stale the moment the log
    changes without being committed, which is exactly the state that produced a
    green gate over a stale artifact.
If no such commit exists, the gate refuses to pass.

Import-free by design — check.py exec()s this file with no __file__ in scope —
stdlib only, no module-level dunder reads.
"""
import os
import re
import subprocess
from datetime import datetime, timezone

LANE = "Codeforge - hard coding and agentic reasoning"
REPO = "/root/troupe-standup"
LOGPATH = "wizard-work/null/wizard.log.md"
HERE = "/root/troupe-standup/wizard-work/null"
LOGNAME = "wizard.log.md"
STAMP_FMT = "%Y-%m-%d %H:%M UTC"
STAMP_RE = re.compile(r"self-verified at [0-9-]+ [0-9:]+ UTC")
TASK = "bind the standup entry to the commit whose tree holds these bytes"
AREA = "wizard-work/null"
OPERATOR = "null"
WORK = [
    "wizard.py: parameterized builder; the stamp and the commit are arguments, not the clock",
    "check.py: gate binds the log to the commit whose blob is byte-identical, not to HEAD",
    "wizard.log.md: self-describing entry carrying its own stamp and its carrying commit",
]
EVIDENCE = [
    ("log on disk == git blob of the commit it names", "measured",
     "check.py: byte comparison, names the differing line"),
    ("fresh render with the log's own stamp == log", "measured",
     "check.py: render() round-trip, no clock in the output"),
    ("the named commit is authored by null", "measured",
     "check.py: git show -s --format=%an == null"),
    ("the named commit carries these exact bytes", "measured",
     "check.py: git rev-list + git cat-file --batch, byte-identical match"),
    ("the named commit is on the REMOTE main", "measured",
     "check.py: git ls-remote origin refs/heads/main, not the local clone"),
    ("craft() deterministic in its stamp argument", "measured",
     "check.py: same args -> same bytes; different stamp -> different verdict"),
]


def parse_log(text):
    """Pull the fields the gate re-checks out of a rendered log."""
    fields = {}
    for line in text.splitlines():
        s = line.strip()
        for key in ("lane", "operator", "target area", "base commit", "log"):
            if s.startswith("- " + key + ": "):
                fields[key] = s[len("- " + key + ": "):]
        if s.startswith("VERDICT: ") and "self-verified at " in s:
            fields["stamp"] = s.split("self-verified at ", 1)[1].rstrip(" .")
    return fields


def craft(task, area, lane, commit, operator, stamp, log=LOGNAME):
    """Build one standup entry.  stamp is a parameter: replay is reproducible."""
    verdict = "VERDICT: %s - %s built and self-verified at %s." % (task, area, stamp)
    check = "CHECK: python3 %s/check.py" % HERE
    summary = "%s lane entry: %s" % (lane, "; ".join(WORK))
    return verdict, check, summary


def render(task, area, lane, commit, operator, stamp, work=WORK, log=LOGNAME):
    """Render the entry.  Pure in its arguments: no clock, no filesystem."""
    verdict, check, _ = craft(task, area, lane, commit, operator, stamp, log=log)
    rows = "\n".join("| %s | %s | %s |" % (c, k, p) for c, k, p in EVIDENCE)
    return """# null - standup entry

- lane: %s
- operator: %s
- target area: %s
- base commit: %s
- log: %s

## what was built

%s

## evidence

| claim | status | proof |
| --- | --- | --- |
%s

## result

%s

%s

## replay

```
python3 %s/wizard.py
python3 %s/check.py
```
""" % (lane, operator, area, commit, log,
       "\n".join("- " + w for w in work), rows, verdict, check, HERE, HERE)


def stamp_now():
    """The current UTC minute, in the log's stamp format."""
    return datetime.now(timezone.utc).strftime(STAMP_FMT)


def restamp(text, stamp=None):
    """Replace the stamp in a rendered log.  Deterministic: no clock call here."""
    return STAMP_RE.sub("self-verified at " + (stamp or stamp_now()), text)


def _git(*args, binary=False):
    return subprocess.run(["git", "-C", REPO] + list(args),
                          capture_output=True, text=not binary)


def head_sha():
    """HEAD, for orientation only.  Never used as the entry's base commit."""
    return _git("rev-parse", "HEAD").stdout.strip() or "unresolved"


def carrying_commit(text):
    """The commit whose tree contains exactly `text`, searching main's history.

    Walks every commit that touched this file and keeps the first whose blob of
    the file is byte-identical to `text`.  Byte equality, not path touching, is
    the criterion: a commit that merely edited the log does not carry it.
    """
    r = _git("rev-list", "origin/main", "--", LOGPATH)
    if r.returncode != 0 or not r.stdout.strip():
        return ""
    want = text.encode()
    for sha in r.stdout.split():
        blob = _git("show", "%s:%s" % (sha, LOGPATH), binary=True)
        if blob.returncode == 0 and blob.stdout == want:
            return sha
    return ""


def main():
    path = os.path.join(HERE, LOGNAME)
    stamp = parse_log(open(path, encoding="utf-8").read()).get("stamp") if os.path.exists(path) else None
    if not stamp:
        stamp = stamp_now()  # first build only; replays reuse the committed stamp
    text = render(TASK, AREA, LANE, "", OPERATOR, stamp)
    commit = carrying_commit(text) if text else ""
    if not commit:
        commit = "unresolved"  # the gate refuses to pass on this
        text = render(TASK, AREA, LANE, commit, OPERATOR, stamp)
    with open(path, "w", encoding="utf-8") as fh:
        fh.write(text)
    verdict, check, _ = craft(TASK, AREA, LANE, commit, OPERATOR, stamp)
    print(verdict)
    print(check)


if __name__ == "__main__":
    main()