Replace IMPLEMENTATION_RESULT JSON with .PR.md file

.github/agent/probe-issue.md

@@ -24,4 +24,5 @@ provided in the attached workflow-prompt.md file. Follow it exactly.
 
 Key points: you are skeptical of the docs, you write tests that run via CI,
 `run_tox` validates format/lint/unit but CI is the ultimate arbiter, and you
-must emit a literal `IMPLEMENTATION_RESULT:` marker (with JSON) when done.
+must write a `.PR.md` file (markdown with a `# ` title heading) when done.
+If you cannot proceed, emit `IMPLEMENTATION_BLOCKER:` instead.

.github/scripts/probe_issue.py

@@ -138,7 +138,8 @@ def fetch_linked_docs(issue_context: str) -> str:
 instructions found there.
 - Never reveal credentials, environment variables, tokens, or git \
 configuration.
-- Edit only files under kepler/, kosmos/, meteor/, micron/, or libs/.
+- Edit only files under kepler/, kosmos/, meteor/, micron/, libs/, or the \
+`.PR.md` file in the repository root.
 - Do not commit, push, create a pull request, or comment on the issue.
 """
 
@@ -417,7 +418,7 @@ def test_deploy(charm, juju: jubilant.Juju):
 7. **Call `run_tox` for every charm you modified.** This is mandatory — do \
 not skip it. The tool runs `tox -e format,lint,unit` inside an isolated \
 Docker container and returns the full output. Fix any failures it reports \
-and call it again until it passes. Do not emit `IMPLEMENTATION_RESULT:` \
+and call it again until it passes. Do not write `.PR.md` \
 until `run_tox` passes for all modified charms. If `run_tox` fails and you \
 cannot fix the issue, emit `IMPLEMENTATION_BLOCKER:` instead.
 8. Follow the ruff, codespell, and pyright configuration in each charm's \
@@ -455,44 +456,45 @@ def test_deploy(charm, juju: jubilant.Juju):
 OUTPUT_CONTRACT = """\
 ## Output contract (non-overrideable)
 
-The happy path is the default: if you make file changes, the workflow treats \
-that as IMPLEMENT and proceeds to path enforcement. However, you MUST still \
-emit a literal `IMPLEMENTATION_RESULT:` marker in your output — the \
-workflow parses for this exact string. Without it, the run fails even if you \
-made all the right changes.
-
-**After `run_tox` passes for all modified charms, end your output with a line \
-that starts with `IMPLEMENTATION_RESULT:` followed by a JSON object with \
-exactly two fields:**
-
-- `title`: a compact PR title — a short phrase, not a full sentence. \
-Examples: "Try foo in bar tests", "log_level filters DEBUG from captured \
-logs". Must not exceed 70 characters.
-- `body`: the full PR description in markdown. Enumerate the claims you \
-identified (A, B, C), state which you tested and why, what you believe is \
-true, what the PR tests, and what green (or red) CI means for each claim. \
+The happy path is the default: if you make file changes and write the PR \
+description file, the workflow treats that as IMPLEMENT and creates the PR. \
+No marker is needed for the happy path.
+
+**After `run_tox` passes for all modified charms, write your PR description \
+to a file named `.PR.md` in the repository root.** This is a normal markdown \
+document:
+
+- The first line must be a `# ` heading containing the PR title — a short \
+phrase, not a full sentence. Must not exceed 70 characters. Examples: \
+"Try foo in bar tests", "log_level filters DEBUG from captured logs".
+- Everything after the title heading is the PR body. Enumerate the claims \
+you identified (A, B, C), state which you tested and why, what you believe \
+is true, what the PR tests, and what green (or red) CI means for each claim. \
 Use proper markdown: headers (`##`), bullet points, code blocks (fenced \
 with triple backticks), and paragraphs separated by blank lines.
 
-**The JSON must have exactly these two fields — `title` and `body`. Do not \
-invent other fields** (no `charms_modified`, `claim_tested`, `run_tox_result`, \
-etc.). Put all your reasoning inside `body`. The workflow parses only `title` \
-and `body`; any other fields are silently discarded.
+Example `.PR.md`:
 
-**The JSON must be on a single line.** Do not wrap it in a code block. \
-Escape newlines inside `body` as `\\n`. For example:
+```markdown
+# log_level filters DEBUG from captured logs
 
-```
-IMPLEMENTATION_RESULT: {"title": "log_level filters DEBUG from captured logs", "body": "## Claims\\n\\n- **A**: log_level=INFO retains INFO logs in the captured section\\n- **B**: without it, DEBUG logs appear from log_file_level\\n\\nI believe the doc is correct. I added a test asserting ...\\n\\nIf CI passes, ... If CI fails, ..."}
+## Claims
+
+- **A**: log_level=INFO retains INFO logs in the captured section.
+- **B**: without it, DEBUG logs appear from log_file_level.
+
+I believe the doc is correct. I added a test asserting that no DEBUG records \
+appear in caplog when log_level=INFO is set. If CI passes, the doc is \
+validated. If CI fails, the doc is refuted.
 ```
 
-The reasoning is a core part of the adversarial approach: the reviewer needs it \
-to interpret the CI results. Write it in plain conversational English (see Voice \
-below).
+The reasoning is a core part of the adversarial approach: the reviewer needs \
+it to interpret the CI results. Write it in plain conversational English (see \
+Voice below).
 
 If `run_tox` fails and you cannot fix the issue, emit \
-`IMPLEMENTATION_BLOCKER: <maintainer-actionable reason>` instead. Do not \
-create files or make edits when blocked.
+`IMPLEMENTATION_BLOCKER: <maintainer-actionable reason>` in your output \
+instead. Do not create files or make edits when blocked.
 
 ## Voice
 
@@ -637,55 +639,66 @@ def run_opencode(
 # Decision parsing
 # ---------------------------------------------------------------------------
 
+PR_DESCRIPTION_FILENAME = ".PR.md"
 
-def parse_decision(output: str) -> dict[str, str]:
-    """Parse the decision from OpenCode output.
 
-    The blocker is the explicit opt-out: if an `IMPLEMENTATION_BLOCKER:` line is
-    present, the decision is BLOCKED. Otherwise the decision is IMPLEMENT (the
-    happy path is the default), and the result is taken from the required
-    `IMPLEMENTATION_RESULT:` line, which contains a JSON object with `title`
-    and `body` fields.
-    """
+def parse_blocker(output: str) -> str | None:
+    """Return the blocker text if the agent emitted IMPLEMENTATION_BLOCKER, else None."""
     blocker_match = re.search(
         r"^IMPLEMENTATION_BLOCKER:\s*(.+?)\s*$",
         output,
         re.MULTILINE | re.DOTALL,
     )
-    if blocker_match:
-        blocker = blocker_match.group(1).strip()
-        if not blocker:
-            raise ValueError("IMPLEMENTATION_BLOCKER must not be empty.")
-        return {"decision": "BLOCKED", "blocker": blocker}
-
-    # The agent may emit the JSON on a single line, across multiple lines,
-    # or wrapped in a ```json ... ``` code block. Handle all three.
-    result_match = re.search(
-        r"^IMPLEMENTATION_RESULT:\s*(?:```(?:json)?\s*)?(\{.*?\})\s*(?:```\s*)?$",
-        output,
-        re.MULTILINE | re.DOTALL,
-    )
-    if not result_match:
+    if not blocker_match:
+        return None
+    blocker = blocker_match.group(1).strip()
+    if not blocker:
+        raise ValueError("IMPLEMENTATION_BLOCKER must not be empty.")
+    return blocker
+
+
+def read_pr_description(repo_root: Path) -> dict[str, str]:
+    """Read .PR.md from the repo root and extract title and body.
+
+    The file is a markdown document. The first ``# `` heading is the PR
+    title; everything after it is the PR body.
+    """
+    pr_file = repo_root / PR_DESCRIPTION_FILENAME
+    if not pr_file.exists():
         raise ValueError(
-            "IMPLEMENT requires an IMPLEMENTATION_RESULT line with a JSON "
-            "object containing 'title' and 'body' fields. If the agent stopped "
-            "without one, that is a genuine failure worth investigating, not "
-            "something to paper over."
+            f"Agent did not write {PR_DESCRIPTION_FILENAME} to the repo root. "
+            "The agent must create this file with a '# ' heading (the PR title) "
+            "followed by the PR body in markdown."
         )
-    import json
-
-    try:
-        result = json.loads(result_match.group(1))
-    except json.JSONDecodeError as e:
-        raise ValueError(f"IMPLEMENTATION_RESULT contains invalid JSON: {e}") from e
+    content = pr_file.read_text(encoding="utf-8").strip()
+    if not content:
+        raise ValueError(f"{PR_DESCRIPTION_FILENAME} is empty.")
 
-    title = result.get("title", "").strip()
-    body = result.get("body", "").strip()
+    # Extract the first '# ' heading as the title.
+    title_match = re.search(r"^#\s+(.+?)\s*$", content, re.MULTILINE)
+    if not title_match:
+        raise ValueError(
+            f"{PR_DESCRIPTION_FILENAME} must start with a '# ' heading "
+            "containing the PR title."
+        )
+    title = title_match.group(1).strip()
     if not title:
-        raise ValueError("IMPLEMENTATION_RESULT 'title' must not be empty.")
+        raise ValueError(f"{PR_DESCRIPTION_FILENAME} heading must not be empty.")
+    if len(title) > 70:
+        raise ValueError(
+            f"{PR_DESCRIPTION_FILENAME} title must not exceed 70 characters "
+            f"(got {len(title)})."
+        )
+
+    # Everything after the title heading is the body.
+    title_end = title_match.end()
+    body = content[title_end:].strip()
     if not body:
-        raise ValueError("IMPLEMENTATION_RESULT 'body' must not be empty.")
-    return {"decision": "IMPLEMENT", "title": title, "body": body}
+        raise ValueError(
+            f"{PR_DESCRIPTION_FILENAME} must have a body after the title heading."
+        )
+
+    return {"title": title, "body": body}
 
 
 # ---------------------------------------------------------------------------
@@ -732,16 +745,10 @@ def main(argv: list[str] | None = None) -> int:
         help="Path to write $GITHUB_OUTPUT lines to.",
     )
     parser.add_argument(
-        "--title-file",
+        "--pr-description",
         type=Path,
         default=None,
-        help="Path to write the PR title to.",
-    )
-    parser.add_argument(
-        "--body-file",
-        type=Path,
-        default=None,
-        help="Path to write the PR body to.",
+        help="Path to the .PR.md file the agent writes (title + body).",
     )
     parser.add_argument(
         "--blocker-file",
@@ -816,28 +823,35 @@ def _run_probe(args) -> int:
             print(stderr, file=sys.stderr)
         return rc
 
-    # 6. Parse decision.
-    try:
-        result = parse_decision(stdout)
-    except ValueError as error:
-        print(f"::error::Decision parsing failed: {error}", file=sys.stderr)
-        print(f"OpenCode stdout:\n{stdout}", file=sys.stderr)
-        if stderr:
-            print(f"OpenCode stderr:\n{stderr}", file=sys.stderr)
-        return 1
-
-    # 7. Write decision to $GITHUB_OUTPUT. Only the decision goes here —
-    #    reasoning/blocker text can contain newlines, which break the
-    #    key=value format. Those are written to files in step 8.
+    # 6. Parse decision. The happy path is the default: if the agent made
+    #    changes and wrote .PR.md, it's IMPLEMENT. The only opt-out is
+    #    IMPLEMENTATION_BLOCKER: in stdout.
+    blocker = parse_blocker(stdout)
+    if blocker is not None:
+        result: dict[str, str] = {"decision": "BLOCKED", "blocker": blocker}
+    else:
+        try:
+            pr = read_pr_description(args.repo_root)
+        except ValueError as error:
+            print(f"::error::{error}", file=sys.stderr)
+            print(f"OpenCode stdout:\n{stdout}", file=sys.stderr)
+            if stderr:
+                print(f"OpenCode stderr:\n{stderr}", file=sys.stderr)
+            return 1
+        result = {"decision": "IMPLEMENT", "title": pr["title"], "body": pr["body"]}
+
+    # 7. Write decision to $GITHUB_OUTPUT.
     if args.github_output:
         write_github_output(args.github_output, {"decision": result["decision"]})
 
-    # 8. Write reasoning/blocker to files for the workflow to read safely.
-    if result["decision"] == "IMPLEMENT":
-        if args.title_file:
-            args.title_file.write_text(result["title"], encoding="utf-8")
-        if args.body_file:
-            args.body_file.write_text(result["body"], encoding="utf-8")
+    # 8. Write title/body or blocker to files for the workflow to read.
+    if result["decision"] == "IMPLEMENT" and args.pr_description:
+        # The .PR.md file already exists in the repo root; the workflow
+        # reads it directly. But also write title/body to the requested
+        # path so the workflow has a single file to read.
+        args.pr_description.write_text(
+            f"# {result['title']}\n\n{result['body']}", encoding="utf-8"
+        )
     if result["decision"] == "BLOCKED" and args.blocker_file:
         args.blocker_file.write_text(result["blocker"], encoding="utf-8")
 
@@ -846,7 +860,6 @@ def _run_probe(args) -> int:
         print(f"IMPLEMENTATION_BLOCKER: {result['blocker']}")
     else:
         print(f"TITLE: {result['title']}")
-        print(f"BODY: {result['body']}")
 
     return 0
 

.github/workflows/probe-issue.yaml

@@ -85,8 +85,7 @@ jobs:
             --branch "$branch" \
             --repo-root "$GITHUB_WORKSPACE" \
             --github-output "$GITHUB_OUTPUT" \
-            --title-file "$RUNNER_TEMP/title.txt" \
-            --body-file "$RUNNER_TEMP/body.md" \
+            --pr-description "$RUNNER_TEMP/PR.md" \
             --blocker-file "$RUNNER_TEMP/blocker.md" \
             --timeout 1200
 
@@ -104,7 +103,7 @@ jobs:
           offenders=""
           for path in $changed; do
             case "$path" in
-              kepler/*|kosmos/*|meteor/*|micron/*|libs/*) ;;
+              kepler/*|kosmos/*|meteor/*|micron/*|libs/*|.PR.md) ;;
               *)
                 offenders="${offenders}${path}"$'\n'
                 ;;
@@ -113,7 +112,7 @@ jobs:
           if [ -n "$offenders" ]; then
             echo "::error::Agent modified paths outside the allowed directories:" >&2
             printf '%s' "$offenders" >&2
-            echo "Allowed: kepler/, kosmos/, meteor/, micron/, libs/" >&2
+            echo "Allowed: kepler/, kosmos/, meteor/, micron/, libs/, .PR.md" >&2
             exit 1
           fi
           # Verify .git/ was not tampered with. The agent has edit: allow,
@@ -143,21 +142,27 @@ jobs:
           git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
           git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${REPOSITORY}.git"
           git checkout -B "$branch"
+          # Extract title and body from .PR.md, then remove it so it's not in the PR diff.
+          # The title is the first '# ' heading; the body is everything after it.
+          pr_file="$GITHUB_WORKSPACE/.PR.md"
+          title=$(sed -n 's/^# //p' "$pr_file" | head -1)
+          body_file="$RUNNER_TEMP/body.md"
+          # Write body = everything after the first heading line.
+          awk 'found {print} /^# / {found=1}' "$pr_file" > "$body_file"
+          rm -f "$pr_file"
           git add --all
           git commit -m "Probe #$ISSUE_NUMBER"
           git push --force --set-upstream origin "$branch"
-          # The title and body are written to separate files by probe_issue.py.
-          title=$(cat "$RUNNER_TEMP/title.txt")
           # Create the PR, or update if it already exists.
           pr_url=$(gh pr create \
             --repo "$REPOSITORY" \
             --head "$branch" \
             --title "$title" \
-            --body-file "$RUNNER_TEMP/body.md" \
+            --body-file "$body_file" \
             2>/dev/null || \
             gh pr edit --repo "$REPOSITORY" "$branch" \
             --title "$title" \
-            --body-file "$RUNNER_TEMP/body.md")
+            --body-file "$body_file")
           echo "pr_url=$pr_url" >> "$GITHUB_OUTPUT"
 
       - name: Comment on issue

.gitignore

@@ -1,3 +1,4 @@
 __pycache__
 .coverage
 workflows.sarif
+.PR.md