docs: stop Stage 2 reading the sub-agent's own system prompt (#654) (#655)

Stage 2's main agent listed `.claude/agents/bess-analyst.md` (25,681 B) as
REQUIRED READING item 3. That file IS the bess-analyst sub-agent's system
prompt -- frontmatter `name: bess-analyst`, `tools: Read, Grep, Glob, Bash,
WebFetch` -- so the main agent was loading a second copy of another agent's
instructions into its own context, on every turn.

Nothing consumed it. The six PROCESS steps are: get issue context, identify
the current problem, delegate, verify the cited file:line, publish, label.
No step applies a "domain expertise checklist". The one distinctive task,
step 4, needs the cited code -- not a triage procedure the main agent never
runs.

The content was in fact loaded three times. The section that could plausibly
serve as a judging standard, "Separate Evidence from Claims", is already
restated almost verbatim in the sub-agent task the same prompt passes:
hypothesis-not-diagnosis, triage-the-bundle-first, verify-the-code-path-
matches-this-user's-setup, intentional-design-is-not-a-bug. Sub-agent system
prompt, main-agent file read, and inline paraphrase.

All four landed Stage 2 analyses (#118, #252, #624, #627) use the workflow's
four headings, never bess-analyst.md's seven-item Output Format or its
six-item type-B shape -- the main agent follows the prompt, not the file.

So item 3 is removed, with an explicit note saying why, and step 4 gains the
check that was missing: a report fails verification if it claims a CODE bug
with no file:line, if a cited location does not say what is claimed, or if
it blends P-optimality / forecast error / control noise into one verdict
when actual behavior diverged from plan. Dead weight becomes an instruction
that fires.

Three things the first draft got wrong, found in review:

- "cites no file:line" alone would have rejected CORRECT diagnoses. The same
  prompt tells the analyst that unavailable sensors, wrong inverter type or
  an HA integration mismatch are likely the real cause, and those cite no
  code. Now qualified to code-bug claims only.
- The inconclusive path never removed `ready-for-analysis`, and
  backlog-digest.sh checks that label BEFORE `needs-human-review`, so the
  backlog pass reports the issue as un-analysed and re-dispatches analyze --
  re-billing the stage. Widening that path without fixing it would have made
  a cost bug worse. It now clears the label.
- The new criterion used vocabulary defined only in the file this diff stops
  the agent reading. P-optimality had a gloss; P≠R never expanded P or R and
  control noise had no definition. All three are now glossed inline.

quality-check.sh gains a context contract gate, written RED first: no
workflow may list a `.claude/agents/*.md` file as a numbered required read,
and Stage 2 must still delegate. Both assertions were mutation-tested --
removing the delegation reddens it, and reformatting `subagent_type` with
backticks or quotes does not, which the first bare-substring version got
wrong in both directions.

Saving is up to 25,681 B off the main agent per turn; the prompt itself grew
7,098 -> 7,821 B, so net is roughly -24.9 KB. "Up to", because whether a run
obeyed the read instruction is not observable -- #646 showed it need not.

No CHANGELOG entry: agent-facing, zero user-visible effect, as #649 and #651.

Closes #654

Author: johanzander

.github/workflows/issue-analyze.yml

@@ -56,7 +56,11 @@ jobs:
             ──────────────────────────────────────────────────────────────────
             1. docs/agents/rules.md           — hard constraints
             2. docs/agents/architecture.md    — codebase layout & data flow
-            3. .claude/agents/bess-analyst.md — domain expertise checklist
+
+            Do NOT read `.claude/agents/bess-analyst.md`. It is the
+            `bess-analyst` sub-agent's own system prompt — it already has it in
+            full, and you never run the procedure it describes. Reading it costs
+            25 KB of your context on every turn and tells you nothing you act on.
 
             ──────────────────────────────────────────────────────────────────
             PROCESS
@@ -120,6 +124,32 @@ jobs:
                reading the file:line locations it cited. Do not just trust
                the summary — quote the actual code.
 
+               The report does NOT pass verification if:
+                 - it claims a CODE bug but cites no `file:line` — there is
+                   nothing to check. A diagnosis that the real problem is an
+                   unavailable sensor, the wrong inverter type, an HA
+                   integration mismatch or a stale add-on version is a
+                   legitimate root cause and needs no code citation;
+                 - a cited location does not say what the report claims it says;
+                 - actual behavior diverged from the plan (unplanned import,
+                   floor breach, spike) and the report gives ONE blended verdict
+                   instead of a separate verdict for each of:
+                     - **P-optimality** — was the allocation optimal against the
+                       inputs the DP actually had at the decision point, judged
+                       WITHOUT hindsight?
+                     - **Forecast error (P≠R)** — the Plan was optimal for its
+                       own forecast, but that forecast differed from what was
+                       Realized.
+                     - **Control/execution noise** — the plan's commanded rate
+                       was never actually achieved by the inverter.
+                   Blending these has repeatedly produced wrong conclusions in
+                   this repo.
+
+               A report that fails verification is an inconclusive result, not a
+               diagnosis. Publish what you found and what is still missing via
+               the IF YOU CAN'T REACH A CONCLUSION path below — do not dress it
+               up as a root cause.
+
             5. **Publish the analysis by RUNNING these two commands.** Writing
                the diagnosis as your reply does NOT publish it — you are running
                headless, nothing is watching your output, and a final message
@@ -169,7 +199,7 @@ jobs:
                  ANALYSIS_EOF
 
                  gh issue comment ${{ github.event.issue.number }} --body-file /tmp/analysis.md
-                 gh issue edit ${{ github.event.issue.number }} --add-label needs-human-review
+                 gh issue edit ${{ github.event.issue.number }} --add-label needs-human-review --remove-label ready-for-analysis
 
             Be honest — "I couldn't find the bug in the current code" is a
             valid outcome. Do not invent a root cause to fill the template.

scripts/quality-check.sh

@@ -515,6 +515,68 @@ then
     ERRORS=$((ERRORS + 1))
 fi
 
+echo ""
+echo "📋 Checking bot workflow context contract..."
+echo "-------------------------------------------"
+
+# A workflow prompt must not tell its MAIN agent to read a `.claude/agents/*.md`
+# file. Those files are sub-agent system prompts: the sub-agent already has one
+# in full, so naming it as the main agent's REQUIRED READING loads a second copy
+# into a different context window, on every turn, for an agent that never runs
+# the procedure it describes.
+#
+# Stage 2 did exactly that with bess-analyst.md (25,681 B) and nothing consumed
+# it (#654). Its six steps are: get context, identify the current problem,
+# delegate, verify the cited file:line, publish, label -- no step applies a
+# "domain expertise checklist". Worse, the section of that file which could
+# plausibly serve as a judging standard (Separate Evidence from Claims) was
+# already restated inline in the sub-agent task the same prompt passes, so the
+# content was loaded three times over.
+#
+# The paired assertion matters as much as the removal: Stage 2 must still
+# DELEGATE. Dropping the read is the saving; dropping the delegation would gut
+# the stage, and the same "trim the prompt" instinct reaches for both.
+if ! python3 - <<'PY_CTX'
+import re, sys, pathlib
+
+WF = pathlib.Path(".github/workflows")
+bad = []
+
+for f in sorted(set(WF.glob("*.yml")) | set(WF.glob("*.yaml"))):
+    text = f.read_text()
+    for i, line in enumerate(text.splitlines(), 1):
+        # Match the shape the regression actually takes: a NUMBERED entry in a
+        # reading list, e.g. "3. .claude/agents/bess-analyst.md — checklist".
+        # Deliberately narrow. A prose line that merely names the path is not
+        # flagged, because the prompt now carries an explicit "Do NOT read
+        # .claude/agents/bess-analyst.md" note and a gate that fought its own
+        # documentation would be worse than one with a known edge. An
+        # unnumbered "read <path>" instruction would slip through; that is an
+        # accepted narrowness, not a claim of completeness.
+        if re.match(r"^\s*\d+\.\s+\.claude/agents/", line):
+            bad.append(f"{f}:{i}: main agent told to read a sub-agent definition: {line.strip()}")
+
+analyze = (WF / "issue-analyze.yml").read_text()
+_, _, prompt_block = analyze.partition("prompt: |")
+if not re.search(r"subagent_type[\s:`'\"]*bess-analyst", prompt_block):
+    bad.append("issue-analyze.yml: Stage 2 no longer delegates to the bess-analyst "
+               "sub-agent -- that delegation IS the stage")
+
+if bad:
+    for b in bad:
+        print(f"   {b}")
+    sys.exit(1)
+
+print("✅ Bot workflow context contract intact (no sub-agent definition read by a "
+      "main agent, Stage 2 still delegates)")
+PY_CTX
+then
+    echo "❌ Bot workflow context contract violated"
+    echo "   A sub-agent's definition is its own system prompt. Do not also list"
+    echo "   it as the main agent's REQUIRED READING (#654)."
+    ERRORS=$((ERRORS + 1))
+fi
+
 echo ""
 echo "📋 Checking agent context budget..."
 echo "-------------------------------------------"