From 67daed312f290f7ba0fda78ed3243901f5b32813 Mon Sep 17 00:00:00 2001
From: wassname <1103714+wassname@users.noreply.github.com>
Date: Fri, 3 Jul 2026 11:12:42 +0800
Subject: [PATCH] docs: evidence should cite committed artifacts; .pi/ is
 gitignored so it's judge-time proof only

Co-Authored-By: Claudypoo <288921227+claudypoo@users.noreply.github.com>
---
 README.md      | 4 +++-
 src/prompts.ts | 2 ++
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 25ce5b5..9a2b898 100644
--- a/README.md
+++ b/README.md
@@ -77,7 +77,9 @@ Latency target came from the SLO review; keep the existing client API.
   cancelled). That one line pattern is the only thing the extension itself reads, for the widget.
 - The `discriminator` is the success test, written while planning: the positive observation that the
   goal succeeded and that none of the `subtle failure mode`s could fake. `evidence` is the proof,
-  filled at sign-off: each item pairs a durable artifact with a short read of it.
+  filled at sign-off: each item pairs a durable artifact with a short read of it. Prefer committed
+  artifacts (files, tests, diffs); `.pi/` is usually gitignored, so evidence there is judge-time
+  proof only and won't survive in history.
 - Small format deviations are fine; the file is read by the human and the judge, not a parser.
 - The agent prunes finished goals itself when the file gets long (evidence survives in git history
   and `## Log`).
diff --git a/src/prompts.ts b/src/prompts.ts
index 22d0cde..bf93a1c 100644
--- a/src/prompts.ts
+++ b/src/prompts.ts
@@ -66,6 +66,8 @@ Conventions:
 - Make the discriminator a concrete, checkable observation about a real artifact (a file, a test
   result, a committed diff, a metric), never about the plan file's own checkbox.
 - evidence stays empty at planning; you fill it at sign-off and a fresh read-only judge checks it.
+  Cite durable artifacts a future reader can open: committed files, test names, git diffs. .pi/ is
+  usually gitignored, so files there prove things only at judge time, not in history.
 
 When the goals are drafted, present them and stop for review. Do not begin execution.`;