From 1f634a6aa08acbd7d56accb56ba1b65c8c4eb26c Mon Sep 17 00:00:00 2001
From: reachableceo <charles@turnsys.com>
Date: Tue, 11 Aug 2026 19:49:46 -0500
Subject: [PATCH] =?UTF-8?q?docs(agents):=20clarify=20questions-v(N).md=20v?=
 =?UTF-8?q?ersioning=20=E2=80=94=20increment=20on=20each=20answer=20round?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

💘 Generated with Crush

Assisted-by: Crush:glm-5.2
---
 AGENTS.md | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 54ae185..7d6cc5d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -102,7 +102,7 @@ traceable to an approved ticket. There is no "I thought it would help."
 
 1. **Set up the environment:** `bash scripts/setup-hooks.sh` (installs git hooks — idempotent).
 2. **Read this file** (`AGENTS.md`) — project policy and domain knowledge.
-3. **Read [questions-v1.md](questions-v1.md)** — open questions awaiting human input.
+3. **Read the latest questions file** (`questions-v*.md`) — open questions awaiting human input. The version number increments each round (v1, v2, v3...).
 4. **Check for understanding — GATE.** In your own words, summarize ALL the rules
    back to the user before doing any work: Agent Authority (ticket-governed,
    propose-never-implement), Access-Channel SSH-only policy, Remote access
@@ -164,10 +164,13 @@ for a full audit or `--fast` for pre-commit speed. Bypass with `--no-verify`
 **NEVER use a harness "question"/"ask user" tool** (structured prompts,
 modal forms, tabbed questions). Banned across every project, every harness.
 They are not portable, not version-controlled, and bypass the git record.
-**All questions go in [questions-v1.md](questions-v1.md)** — write the
-question; the human edits the answer inline in the same file. Version up
-per round. Synthesize resolved Q&A into Discourse (decisions) and Redmine
-(work items). See `BASELINE-PROMPT.md` §10.
+**All questions go in the current `questions-v(N).md` file** — write the
+question; the human edits the answer inline in the same file. **Version up
+the filename each time answers land** (v1 → v2 → v3...): create
+`questions-v2.md` with resolved Q&A marked, new questions appended. This
+preserves the history of each Q&A round. Synthesize resolved Q&A into
+Discourse (decisions) and Redmine (work items). See `BASELINE-PROMPT.md`
+§10.
 
 ## Documentation policy (IMPORTANT)