Add pre-HN readiness toolkit

Author: LeoStehlik

.agent/tasks/pre-hn-readiness/evidence.md

@@ -0,0 +1,63 @@
+# Evidence - pre-hn-readiness
+
+## Build Summary
+
+Implemented the five pre-HN readiness items:
+
+- added `Makefile` with `make test`
+- added stdlib unittest coverage under `tests/`
+- added executable wrappers `bin/proof-loop-init` and `bin/proof-loop-check`
+- added realistic demo fixture under `examples/demo-repo/`
+- added GitHub Actions workflow `.github/workflows/test.yml`
+- updated README with test badge, `20-second demo`, and `What This Is Not`
+
+## Checks Run
+
+```bash
+make test
+```
+
+Result:
+
+```text
+Ran 7 tests in 0.398s
+OK
+NAV_LABEL_CHECK_PASS
+PROOF_LOOP_PASS examples/example-task/.agent/tasks/ui-language-fix
+PROOF_LOOP_PASS examples/demo-repo/.agent/tasks/nav-labels-proof
+```
+
+```bash
+cd /tmp/proof-loop-wrapper-smoke/other-repo
+/home/less/repo-garden-audit/repos/proof-loop/bin/proof-loop-init external-hn --title "External HN smoke" --root .
+/home/less/repo-garden-audit/repos/proof-loop/bin/proof-loop-check .agent/tasks/external-hn
+```
+
+Result: wrapper init created `.agent/tasks/external-hn/`; wrapper check failed as expected because the task was unverified.
+
+```bash
+python3 examples/demo-repo/check_nav_labels.py examples/demo-repo/nav_labels.json
+python3 scripts/check_task.py examples/demo-repo/.agent/tasks/nav-labels-proof
+```
+
+Result: demo check passed and the demo proof task passed.
+
+## AC1 - PASS
+
+`make test` passes and covers initialization, invalid IDs, unverified failure, completed example pass, invalid JSON, non-empty `problems.md`, and wrappers from another repo.
+
+## AC2 - PASS
+
+`bin/proof-loop-init` and `bin/proof-loop-check` work from a temporary directory outside this repository.
+
+## AC3 - PASS
+
+`examples/demo-repo/` contains a real JSON fixture, a real checker script, and matching proof artifacts. The checker and task gate both pass.
+
+## AC4 - PASS
+
+`.github/workflows/test.yml` runs `make test`; README includes the workflow badge.
+
+## AC5 - PASS
+
+README includes `20-second demo` and `What This Is Not`; commands shown are backed by committed wrappers, Makefile, and examples.

.agent/tasks/pre-hn-readiness/problems.md

@@ -0,0 +1,40 @@
+# Task: pre-hn-readiness
+
+## Task Statement
+
+Make Proof Loop ready for a Show HN audience by turning it from a useful protocol repo into a small, tryable, verified tool with tests, CI, executable wrappers, a realistic demo fixture, and a sharper README entry path.
+
+## Acceptance Criteria
+
+**AC1:** The repository has a real test suite and a single `make test` command that exercises the helper scripts.
+- Verify: run `make test`; it must pass and cover task initialization, invalid task IDs, unverified FAIL, completed PASS, invalid JSON, and non-empty `problems.md`.
+
+**AC2:** Proof Loop can be invoked from another repository through executable wrapper commands, not only by running `python3 scripts/...` inside the cloned repo.
+- Verify: from a temporary directory outside this repo, run `bin/proof-loop-init` and `bin/proof-loop-check` using absolute paths; initialization must create `.agent/tasks/<TASK_ID>/` in that external directory and the check must fail until the task is verified.
+
+**AC3:** The repo includes a realistic demo fixture whose proof artifacts correspond to an actual file and check command.
+- Verify: run the demo check command documented in the demo evidence; it must pass against files in `examples/demo-repo/`, and the demo task must pass `scripts/check_task.py`.
+
+**AC4:** GitHub Actions CI is present and the README exposes the test badge.
+- Verify: `.github/workflows/test.yml` exists, runs `make test`, and README contains the workflow badge.
+
+**AC5:** The README has an HN-ready top section: a 20-second demo and a clear `What This Is Not` section.
+- Verify: README contains `20-second demo` and `What This Is Not`, and the commands shown in the demo are backed by actual files/scripts.
+
+## Constraints
+
+- Keep runtime dependencies to Python standard library.
+- Do not introduce packaging complexity unless needed.
+- Do not remove existing examples, role briefs, or references.
+- Keep claims harness-agnostic and honest; do not imply native integrations.
+
+## Non-Goals
+
+- Publishing to PyPI.
+- Building a full web demo.
+- Creating an umbrella repo or platform brand.
+- Adding Loopsmith eval packs in this task.
+
+## Verification Approach
+
+Run `make test`, run the wrappers from outside the repo, run the realistic demo check, run `scripts/check_task.py` against the demo proof task, and finally update `verdict.json` so every AC is PASS only after those checks succeed.

.agent/tasks/pre-hn-readiness/spec.md

@@ -0,0 +1,34 @@
+{
+  "task_id": "pre-hn-readiness",
+  "phase": "verify",
+  "agent": "francis-fresh-verifier",
+  "timestamp": "2026-05-20T15:55:00Z",
+  "overall": "PASS",
+  "criteria": [
+    {
+      "id": "AC1",
+      "status": "PASS",
+      "note": "make test passes and covers init, invalid IDs, unverified FAIL, completed PASS, invalid JSON, non-empty problems.md, and wrapper usage."
+    },
+    {
+      "id": "AC2",
+      "status": "PASS",
+      "note": "Absolute bin/proof-loop-init and bin/proof-loop-check were run from /tmp/proof-loop-wrapper-smoke/other-repo; init created artifacts and check failed until verification as expected."
+    },
+    {
+      "id": "AC3",
+      "status": "PASS",
+      "note": "examples/demo-repo has a real JSON fixture and checker; checker passes and the demo proof task passes check_task.py."
+    },
+    {
+      "id": "AC4",
+      "status": "PASS",
+      "note": ".github/workflows/test.yml runs make test and README contains the test badge."
+    },
+    {
+      "id": "AC5",
+      "status": "PASS",
+      "note": "README contains 20-second demo and What This Is Not; demo commands reference committed wrappers, Makefile, and examples."
+    }
+  ]
+}

.agent/tasks/pre-hn-readiness/verdict.json

@@ -0,0 +1,15 @@
+name: test
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - run: make test

.github/workflows/test.yml

@@ -0,0 +1,8 @@
+.PHONY: test
+
+test:
+	python3 -m py_compile scripts/init_task.py scripts/check_task.py examples/demo-repo/check_nav_labels.py
+	python3 -m unittest discover -s tests
+	python3 examples/demo-repo/check_nav_labels.py examples/demo-repo/nav_labels.json
+	python3 scripts/check_task.py examples/example-task/.agent/tasks/ui-language-fix
+	python3 scripts/check_task.py examples/demo-repo/.agent/tasks/nav-labels-proof

Makefile

@@ -1,11 +1,34 @@
 # Proof Loop
 
+![Tests](https://github.com/LeoStehlik/proof-loop/actions/workflows/test.yml/badge.svg)
+
 **Finish AI coding work with evidence, not vibes.**
 
 Proof Loop is a lightweight protocol and toolkit for non-trivial coding tasks handled by AI agents. It freezes acceptance criteria before the build, separates builder and verifier roles, records durable proof artifacts in the repo, and refuses to call work done until every acceptance criterion has a fresh PASS verdict.
 
 Use it when an agent, team, or multi-agent sprint needs a hard boundary against false completion claims. Because the protocol is just files plus role discipline, it works with OpenClaw, Hermes, Codex, OpenCode, Claude Code, or any other harness that can read and write a repository.
 
+
+## 20-second demo
+
+```bash
+git clone https://github.com/LeoStehlik/proof-loop.git
+cd proof-loop
+make test
+
+tmp=$(mktemp -d)
+bin/proof-loop-init hn-demo --title "Prove this task before done" --root "$tmp"
+bin/proof-loop-check "$tmp/.agent/tasks/hn-demo"
+```
+
+The last command fails on purpose because the generated task has not been verified yet. Proof Loop only returns success after a fresh verifier records `PASS` for every acceptance criterion and `problems.md` is empty.
+
+A completed passing example is included:
+
+```bash
+bin/proof-loop-check examples/example-task/.agent/tasks/ui-language-fix
+```
+
 ## Why It Exists
 
 AI coding agents often fail in predictable ways:
@@ -31,10 +54,10 @@ Proof Loop makes completion auditable. A task is done only when a fresh verifier
 
 Clone the repo or copy it into the project where you want to run the protocol.
 
-Create a task proof folder:
+Create a task proof folder from this repo or from another repository:
 
 ```bash
-python3 scripts/init_task.py ui-language-fix --title "Fix German navigation labels"
+bin/proof-loop-init ui-language-fix --title "Fix German navigation labels" --root .
 ```
 
 This creates:
@@ -52,7 +75,7 @@ Fill `spec.md` with explicit acceptance criteria before implementation starts.
 After the build and verifier pass, check whether the task is allowed to be called done:
 
 ```bash
-python3 scripts/check_task.py .agent/tasks/ui-language-fix
+bin/proof-loop-check .agent/tasks/ui-language-fix
 ```
 
 The check exits non-zero unless:
@@ -61,6 +84,16 @@ The check exits non-zero unless:
 - every AC has `status: PASS`
 - `problems.md` is empty or absent
 
+
+## What This Is Not
+
+- not an agent framework
+- not a benchmark suite
+- not a replacement for tests
+- not tied to one model, vendor, or harness
+
+Proof Loop is deliberately small: a protocol, a few files, and a mechanical done gate.
+
 ## The Protocol
 
 ```text
@@ -186,9 +219,14 @@ Copy the `proof-loop` folder into your agent skills directory, or reference `SKI
 ```text
 proof-loop/
   SKILL.md                         skill trigger and core operating rules
+  bin/
+    proof-loop-init                wrapper usable from another repository
+    proof-loop-check               wrapper usable from another repository
   scripts/
     init_task.py                   create .agent/tasks/<TASK_ID>/ skeletons
     check_task.py                  mechanical done gate
+  tests/                           stdlib unittest coverage for CLI behavior
+  .github/workflows/test.yml       CI running make test
   references/
     workflow.md                    full phase-by-phase protocol
     brief-template.md              reusable sprint and role prompts

README.md

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+set -eu
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec python3 "$SCRIPT_DIR/../scripts/check_task.py" "$@"

bin/proof-loop-check

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+set -eu
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+exec python3 "$SCRIPT_DIR/../scripts/init_task.py" "$@"

bin/proof-loop-init

@@ -0,0 +1,29 @@
+# Evidence - nav-labels-proof
+
+## Build Summary
+
+The demo fixture contains `examples/demo-repo/nav_labels.json` and a real check command at `examples/demo-repo/check_nav_labels.py`.
+
+## Checks Run
+
+```bash
+python3 examples/demo-repo/check_nav_labels.py examples/demo-repo/nav_labels.json
+```
+
+Result:
+
+```text
+NAV_LABEL_CHECK_PASS
+```
+
+## AC1 - PASS
+
+The JSON file contains the expected English labels: Home, Settings, Billing.
+
+## AC2 - PASS
+
+The JSON file contains the expected German labels: Startseite, Einstellungen, Abrechnung.
+
+## AC3 - PASS
+
+The check script compares the file against an expected dictionary and exits with status `1` when values differ.