planning-with-files: a plan that survives /clear and an opt-in stop gate, 6 of 6 tests

OthmanAdi/planning-with-files keeps an agent's plan in markdown files on disk so it survives /clear and compaction, and it ships an opt-in completion gate. We pinned it at ff349ebe322b and on October 14, 2026 our keyless run passed 6 of 6 pytest tests, including a fresh process that recovered phase status from files and a gate that blocked a stop until all five phases were complete. The gate is off by default, it only blocks when a Stop hook reads its output, and it steps aside once the hook is already active.

The catch

Plain check-complete.sh is advisory. Right after init it prints Task in progress (0/5 phases complete). Update progress.md before stopping. and exits 0. Blocking needs init-session.sh --gated and check-complete.sh --gate. Even then the script exits 0 and writes {"decision": "block", ...} to stdout, which stops the agent only if a Stop hook hands that JSON to the agent runtime. When stdin carries {"stop_hook_active": true}, the gate prints no decision, so a session that is already continuing because of a block is allowed to stop.

This lab does not turn on hooks. The upstream skill ships lifecycle hook scripts, and the README asks you to review any .claude/settings.json change before you enable them in a real project. The /clear test is also a simulation, two subprocesses that share a directory and nothing else. It shows the state lives on disk, and it does not drive a live chat session.

The report also notes that an earlier CI run, 38522221025, failed, and it cites the later green run, 38522922934.

What we ran (keyless)

uv sync --group dev
bash scripts/fetch-upstream.sh
bash scripts/install-skill.sh
uv run pytest -q

From reports/gate.json, run on October 14, 2026:

Three of the tests exercise the gate. In test_survives_clear, process A marks phase 1 complete and exits, and process B reads Task in progress (1/5 phases complete) from the files alone. In test_gate_opt_in, a gated init writes the plan, nonce and attestation files under .planning/<date>-gated-run/. The first --gate call returns one JSON line with "decision": "block". After phases 1 through 5 are marked complete, the same call prints nothing and the agent may stop. test_check_complete_advisory pins the advisory message above. The other three tests cover legacy init, the all-complete case and the skill layout under .claude/skills/.

How it is wired

The plan lives in task_plan.md, findings.md and progress.md, with .planning/.active_plan pointing at the current plan. The agent updates phases with phase-status.sh N complete as it works. After /clear or compaction, the plan-survives-clear skill tells it to read those files before anything else. With the gate on, a Stop hook pipes the hook payload into check-complete.sh --gate, and a block sends the agent back to the open phase.

Minilab (open source)

Upstream is OthmanAdi/planning-with-files (27,455 stars, MIT, Python, as of October 14, 2026). Clone the lab and run the four commands above. Then try init-session.sh --gated "Gated Run" and echo '{}' | check-complete.sh --gate by hand to watch the block appear and clear.

uv sync --group dev && bash scripts/fetch-upstream.sh && bash scripts/install-skill.sh && uv run pytest -q