Reframe sweep M7-27 + capstone (AI drives git, lesson=theory, de-slop) (#93)

Co-authored-by: claude <claude@jpaul.io>
Co-committed-by: claude <claude@jpaul.io>

modules/24-assistive-agents/lab/reviewer.py

@@ -4,8 +4,8 @@ This stands in for a forge-native reviewer (an app/bot triggered when a PR opens
 runner from Module 19) without needing any hosted account. It does the two deterministic halves of
 the job and leaves the one judgment call — what actually happens to the PR — to you.
 
-    python reviewer.py prompt              # assemble the prompt: rubric + diff. Paste to your AI.
-    python reviewer.py apply ai-review.sample.json   # ingest the AI's JSON, render it, gate it
+    python reviewer.py prompt              # assemble the prompt: rubric + diff, for the agent to review
+    python reviewer.py apply ai-review.sample.json   # ingest the agent's JSON, render it, gate it
 
 The point of this module: the agent produces comments and a recommendation. It never approves,
 never requests-changes-as-a-gate, never merges. The `apply` step ends at a HUMAN DECISION, every
@@ -23,9 +23,9 @@ HERE = Path(__file__).parent
 def load_json_response(path: Path):
     """Parse the JSON the AI returned.
 
-    Chat assistants very often wrap their output in a ```json ... ``` code fence (or add a line of
-    prose) even when told to "return only the JSON" — so a strict json.loads on the raw paste fails
-    on the most likely real output. Try a strict parse first; if that fails, fall back to the
+    Chat assistants very often wrap their output in a ```json ... ``` code fence (or add a stray
+    line of text) even when told to "return only the JSON", so a strict json.loads on the raw paste
+    fails on the most likely real output. Try a strict parse first; if that fails, fall back to the
     outermost { ... } block, which survives a code fence or surrounding text. Stdlib only."""
     raw = path.read_text()
     try:
@@ -39,7 +39,7 @@ def load_json_response(path: Path):
 
 PROMPT_HEADER = """\
 You are an assistive code reviewer. Follow the rubric below exactly, then review the diff that
-follows it. Return ONLY the JSON object the rubric specifies — no prose before or after.
+follows it. Return ONLY the JSON object the rubric specifies, with no extra text before or after.
 
 ================ REVIEW RUBRIC ================
 {rubric}
@@ -99,7 +99,7 @@ def main(argv: list[str]) -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     sub = parser.add_subparsers(dest="cmd", required=True)
 
-    p = sub.add_parser("prompt", help="assemble the review prompt to paste to your AI")
+    p = sub.add_parser("prompt", help="assemble the review prompt for the agent to act on")
     p.add_argument("--rubric", default=str(HERE / "review-rubric.md"))
     p.add_argument("--patch", default=str(HERE / "feature.patch"))
     p.set_defaults(func=cmd_prompt)

modules/24-assistive-agents/lab/triage.py

@@ -4,7 +4,7 @@ Stands in for a forge-native triage agent (triggered when an issue opens) withou
 It assembles the prompt, then validates and renders the AI's suggestion — and stops at a human
 confirm. The agent proposes labels and a route; it does not apply them.
 
-    python triage.py prompt                          # taxonomy + issue -> prompt. Paste to your AI.
+    python triage.py prompt                          # taxonomy + issue -> prompt for the agent
     python triage.py apply ai-triage.sample.json     # validate + render + confirm gate
 
 The validation step matters: the agent may only use labels that exist in label-taxonomy.md. A
@@ -42,9 +42,9 @@ def allowed_labels(taxonomy_text: str) -> set[str]:
 def load_json_response(path: Path):
     """Parse the JSON the AI returned.
 
-    Chat assistants very often wrap their output in a ```json ... ``` code fence (or add a line of
-    prose) even when told to "return only the JSON" — so a strict json.loads on the raw paste fails
-    on the most likely real output. Try a strict parse first; if that fails, fall back to the
+    Chat assistants very often wrap their output in a ```json ... ``` code fence (or add a stray
+    line of text) even when told to "return only the JSON", so a strict json.loads on the raw paste
+    fails on the most likely real output. Try a strict parse first; if that fails, fall back to the
     outermost { ... } block, which survives a code fence or surrounding text. Stdlib only."""
     raw = path.read_text()
     try:
@@ -109,7 +109,7 @@ def main(argv: list[str]) -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     sub = parser.add_subparsers(dest="cmd", required=True)
 
-    p = sub.add_parser("prompt", help="assemble the triage prompt to paste to your AI")
+    p = sub.add_parser("prompt", help="assemble the triage prompt for the agent to act on")
     p.add_argument("--taxonomy", default=str(HERE / "label-taxonomy.md"))
     p.add_argument("--issue", default=str(HERE / "sample-issue.md"))
     p.set_defaults(func=cmd_prompt)