Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python

Issue reports open with the graff and Harness versions

justrach9f54ba44458e
diff --git a/AGENTS.md b/AGENTS.md
index 629f0c5d..694f03ba 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -23,6 +23,51 @@ their edit histories are visible to everyone.
not enough because edit history stays visible. Then tell the user what was
exposed and for how long.
+## Issue format: every report states its versions
+
+Every issue, whether a person or an agent files it, opens with this header.
+A report without versions can't be told apart from a bug that a newer release
+already fixed.
+
+```markdown
+**graff:** 0.0.302.25 (latest: 0.0.302.25)
+**Harness:** 0.2.109, or "not used"
+**Surface:** Harness | terminal | `graff -p` | ACP client | SDK
+**Platform:** macOS arm64 | Linux x64 | Windows x64 | ...
+
+## Symptom
+What went wrong, in generic terms, with the tool's own error text verbatim.
+
+## Repro
+The smallest sequence of steps that shows it.
+
+## Root cause
+In code terms (`file.zig::function`), naming the tag or commit the line
+numbers come from. Leave this section out if the cause isn't known.
+
+## Fix
+The expected behavior, or the proposed change.
+```
+
+- **graff:** run the binary that hit the bug. Harness runs its managed copy,
+ not the `graff` on `PATH`: `~/.harness/bin/graff --version` (macOS and
+ Linux). For the latest release, run
+ `gh release view --repo justrach/codegraff --json tagName`.
+- **Harness:** on macOS, run
+ `plutil -extract CFBundleShortVersionString raw /Applications/Harness.app/Contents/Info.plist`.
+- **If the graff that failed is older than the latest release**, check
+ whether the release notes or a closed issue already cover the bug. Reproduce
+ it on the latest release before filing, or say plainly in the header that it
+ wasn't rechecked.
+- **Cite source from a named version.** If a report cites code from a local
+ checkout that isn't the running version, it describes code that may already
+ have changed. Use `v0.0.302.25:src/x.zig:93` (or a commit hash), never a bare
+ line number.
+- **Search before filing.** Search open and closed issues by the error text.
+ Comment on an existing issue only when you have a new repro or diagnostic.
+- **What the header must not contain:** model or provider names, account
+ details, or paths. The public-tracker rules above still apply.
+
## Keychain: never dump it
Never run `security dump-keychain` (with or without `-d`), and never walk every
diff --git a/src/prompt_golden.zig b/src/prompt_golden.zig
index dab8eb66..32bacdea 100644
--- a/src/prompt_golden.zig
+++ b/src/prompt_golden.zig
@@ -77,6 +77,11 @@ pub const full_prompt =
\\'...'`). If one already tracks the failure, file nothing new: comment only
\\with a genuinely new reproduction or diagnostic. If the search fails, keep
\\the finding in your reply instead of filing.
+ \\Open the body with the versions it was seen on: the running graff's
+ \\`--version` (inside Harness that is `~/.harness/bin/graff`, not the one on
+ \\PATH) beside the latest release (`gh release view --repo justrach/codegraff
+ \\--json tagName`), the Harness version or "not used", the surface (Harness,
+ \\terminal, ACP client or SDK) and OS/arch. Cite source as `<tag>:file:line`.
\\
\\Anything you publish outside this machine — a GitHub issue, PR, comment or
\\gist, a hosted page, a paste, a request to someone else's API — carries only
diff --git a/src/prompt_text.zig b/src/prompt_text.zig
index 4ee80c20..2fda095f 100644
--- a/src/prompt_text.zig
+++ b/src/prompt_text.zig
@@ -107,6 +107,11 @@ pub const harness_issue_note =
\\'...'`). If one already tracks the failure, file nothing new: comment only
\\with a genuinely new reproduction or diagnostic. If the search fails, keep
\\the finding in your reply instead of filing.
+ \\Open the body with the versions it was seen on: the running graff's
+ \\`--version` (inside Harness that is `~/.harness/bin/graff`, not the one on
+ \\PATH) beside the latest release (`gh release view --repo justrach/codegraff
+ \\--json tagName`), the Harness version or "not used", the surface (Harness,
+ \\terminal, ACP client or SDK) and OS/arch. Cite source as `<tag>:file:line`.
;
/// Always present: MCP, delegated and hosted tools can publish without bash (#739).