From bcf1a5d5a0fda428d0da5b91f17f7d61b314dc56 Mon Sep 17 00:00:00 2001
From: timmy <timmy@stackchain.ai>
Date: Tue, 4 Aug 2026 15:02:15 +0000
Subject: [PATCH] docs: audit release worker instructions (#19)

---
 README.md            | 18 +++++++++++++-----
 tests/test_readme.py | 12 ++++++++++++
 2 files changed, 25 insertions(+), 5 deletions(-)
 create mode 100644 tests/test_readme.py

diff --git a/README.md b/README.md
index 55491e9..ced268c 100644
--- a/README.md
+++ b/README.md
@@ -20,16 +20,24 @@ python3 -m src.release_engine \
   --dry-run
 ```
 
-Execute one ticket:
+Execute one ticket after implementing and committing its change directly on
+the deterministic branch printed by `--dry-run`:
 
 ```bash
-export RELEASE_AGENT_COMMAND='codex exec "Implement Gitea issue #{issue_number}: {issue_title}. Follow the issue body and run tests."'
+export GITEA_TOKEN='<scoped-token>'
+export RELEASE_AGENT_COMMAND=true
 python3 -m src.release_engine \
   --repo stackchain/stackchain-dashboard \
   --agent timmy \
+  --issue 19 \
   --test-command 'python3 -m pytest tests/ -q'
 ```
 
-Required secret: `GITEA_TOKEN`. Durable state defaults to
-`.release-engine/state.json`. Full behavior and safety gates are documented in
-[`docs/release-engine-spec.md`](docs/release-engine-spec.md).
\ No newline at end of file
+`GITEA_TOKEN` needs issue and repository write scopes. The engine verifies the
+claim, reruns the test command, pushes the branch, and opens a PR containing
+`Closes #19` plus test evidence. Replace `19` with the selected issue number;
+do not run without `--issue` when processing a preselected ticket.
+
+Durable state defaults to `.release-engine/state.json`. Full behavior and
+safety gates are documented in
+[`docs/release-engine-spec.md`](docs/release-engine-spec.md).
diff --git a/tests/test_readme.py b/tests/test_readme.py
new file mode 100644
index 0000000..c9cf911
--- /dev/null
+++ b/tests/test_readme.py
@@ -0,0 +1,12 @@
+from pathlib import Path
+
+
+README = Path(__file__).parents[1] / "README.md"
+
+
+def test_release_worker_instructions_use_direct_agent_execution():
+    text = README.read_text()
+
+    assert "codex" not in text.lower()
+    assert "RELEASE_AGENT_COMMAND=true" in text
+    assert "--issue 19" in text