claude-dev-env 2.7.1 → 2.9.0

package/skills/_shared/end-of-run-gotcha-recommendations.md

@@ -0,0 +1,156 @@
+# End-of-run gotcha recommendations
+
+**Shared close-out** for every skill.
+
+After the deliverable, recommend pasteable gotchas from issues **this run** hit.
+
+## When
+
+- **With issues:** end of work, after the deliverable.
+- **Clean run:** end with the deliverable only.
+
+## What counts
+
+Keep only items that **bit this run**:
+
+- Wrong **path, file, or config**
+- **Command / CLI** failed or needed different flags
+- **Auth, permission, or environment** blocked a step
+- **Data shape** mismatch (empty set, wrong schema, bad field)
+- **Tool, UI, or selector** missed the target
+- **Timing** needed a retry or longer wait
+- **Dependency or install** gap or wrong version
+- **Output format** wrong for the next step
+- A **workaround** required to finish
+
+## What to produce
+
+**Order (hard):**
+
+1. Show findings in chat; categorize as P0-P3.
+2. Then `AskUserQuestion`.
+3. On confirm only, file via `issue-tracker`.
+
+### Cold-reader frame
+
+Assume zero context.
+
+**Exactly two setup sentences**, each on its **own rendered line**:
+
+1. What we were doing.
+2. Why these notes matter.
+
+### 1. Chat findings (always first)
+
+#### Sentence law (HARD)
+
+| Rule | Required |
+|---|---|
+| **One sentence per rendered line** | Exactly one terminal `.` `?` or `!` on that line |
+| **No collapsed pairs** | A single markdown newline is **not** a line break — it joins sentences |
+| **Force the break** | Blank line between every prose sentence, **or** one list item per sentence |
+| **No clause glue** | No em-dash or semicolon joining two clauses |
+| **One idea** | If you can split it, split it |
+| **Heavy detail** | Prefer an **ASCII infographic** over a stack of sentences |
+
+**Self-check before send:** paste the chat into a viewer that collapses soft breaks.
+
+If two periods appear on one visual line, **split or diagram**.
+
+#### Per gotcha (HARD shape)
+
+| Part | Form |
+|---|---|
+| **Title** | Heading fragment only |
+| **Broke** | One sentence alone on its rendered line |
+| **Fix** | One sentence alone on its rendered line |
+| **ASCII** | Required for path, flag, or before/after |
+
+**Cap: two prose sentences per gotcha.**
+
+```markdown
+## Session close-out
+
+We built phone-theme prompts from a project style catalog.
+
+Keep these traps for the next run.
+
+## Gotcha recommendations
+
+### Wrong catalog folder
+
+The style picker failed outside the project.
+
+Run from the project root with data/midjourney_sref_catalog.json.
+
+```text
+wrong folder --> fail
+project root --> data/midjourney_sref_catalog.json
+```
+```
+
+**Wrong (soft break joins sentences into one line):**
+
+```markdown
+The style picker failed outside the project.
+Run from the project root with data/midjourney_sref_catalog.json.
+```
+
+Renders as one line with **two** sentences.
+
+**Right (blank line forces two lines):**
+
+```markdown
+The style picker failed outside the project.
+
+Run from the project root with data/midjourney_sref_catalog.json.
+```
+
+**Right (list items):**
+
+```markdown
+- The style picker failed outside the project.
+- Run from the project root with data/midjourney_sref_catalog.json.
+```
+
+### 2. Issue offer (`AskUserQuestion`)
+
+Only after the chat block.
+
+| Field | Limit |
+|---|---|
+| **Question** | One short sentence |
+| **Header** | `File issues` |
+| **label** | Plain name |
+| **description** | One short sentence |
+
+Detail and ASCII stay in chat.
+
+**On confirm:** file via `issue-tracker`.
+
+Cold-reader issue body.
+
+Clean run: skip.
+
+## Built-in skill gotcha
+
+**Two sentences on one rendered line.**
+
+Markdown soft-breaks join prose.
+
+Review the close-out before send.
+
+Split with a blank line or a list item.
+
+Or move the detail into an ASCII infographic.
+
+## Rules
+
+- Cold-reader first.
+- Chat first, then ask.
+- One sentence per **rendered** line.
+- Blank line or list item between prose sentences.
+- Two prose sentences per gotcha max.
+- ASCII for path, flag, or before/after.
+- File only on confirm.
+- Lived issues only.

package/skills/_shared/pr-loop/CLAUDE.md

@@ -12,7 +12,24 @@ those skills invoke during each loop tick.
 | `prompts/` | XML agent prompt templates. |
 | `scripts/` | Python scripts for loop state management, prompt building, outcome recording, path resolution, pacer selection, and preflight checks. |
 
-## Key files
+## Canonical-path stubs (`~/.claude/_shared/pr-loop/`)
+
+Open a stub, then load the `@` target:
+
+| Stub here | Load |
+|---|---|
+| `audit-contract.md` | `@~/.claude/_shared/pr-loop/audit-contract.md` |
+| `audit-reply-template.md` | `@~/.claude/_shared/pr-loop/audit-reply-template.md` |
+| `code-rules-gate.md` | `@~/.claude/_shared/pr-loop/code-rules-gate.md` |
+| `fix-protocol.md` | `@~/.claude/_shared/pr-loop/fix-protocol.md` |
+| `gh-payloads.md` | `@~/.claude/_shared/pr-loop/gh-payloads.md` |
+| `post-audit-thread-contract.md` | `@~/.claude/_shared/pr-loop/post-audit-thread-contract.md` |
+| `precatch-rubric.md` | `@~/.claude/_shared/pr-loop/precatch-rubric.md` |
+| `state-schema.md` | `@~/.claude/_shared/pr-loop/state-schema.md` |
+| `worker-spawn.md` | `@~/.claude/_shared/pr-loop/worker-spawn.md` |
+| `scripts/RUNTIME_SCRIPTS.md` | `@~/.claude/_shared/pr-loop/scripts/` |
+
+## Key files (live in this tree)
 
 | File | Role |
 |---|---|

package/skills/_shared/pr-loop/audit-contract.md

@@ -0,0 +1,5 @@
+# Audit contract
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/audit-contract.md

package/skills/_shared/pr-loop/audit-reply-template.md

@@ -0,0 +1,5 @@
+# Audit reply template
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/audit-reply-template.md

package/skills/_shared/pr-loop/code-rules-gate.md

@@ -0,0 +1,5 @@
+# Code rules gate
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/code-rules-gate.md

package/skills/_shared/pr-loop/fix-protocol.md

@@ -0,0 +1,5 @@
+# Fix protocol
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/fix-protocol.md

package/skills/_shared/pr-loop/gh-payloads.md

@@ -0,0 +1,5 @@
+# Gh payloads
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/gh-payloads.md

package/skills/_shared/pr-loop/post-audit-thread-contract.md

@@ -0,0 +1,5 @@
+# Post-audit thread contract
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/post-audit-thread-contract.md

package/skills/_shared/pr-loop/precatch-rubric.md

@@ -0,0 +1,5 @@
+# Precatch rubric
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/precatch-rubric.md

package/skills/_shared/pr-loop/scripts/CLAUDE.md

@@ -2,7 +2,14 @@
 
 Python scripts that run the PR audit-fix loop at runtime. Both `bugteam` and `pr-converge` invoke these scripts during each loop tick.
 
-## Key files
+## Two script homes
+
+| Home | Path |
+|---|---|
+| **Skill-local** (this folder) | Converge helpers: `build_*_prompt.py`, `init_loop_state.py`, `portable_converge_driver.py`, … |
+| **Runtime** (top-level shared) | Gate / preflight / review helpers — see `RUNTIME_SCRIPTS.md` → `@~/.claude/_shared/pr-loop/scripts/` |
+
+## Key files (skill-local)
 
 | File | Role |
 |---|---|

package/skills/_shared/pr-loop/scripts/RUNTIME_SCRIPTS.md

@@ -0,0 +1,29 @@
+# PR-loop runtime scripts
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/scripts/code_rules_gate.py
+
+@~/.claude/_shared/pr-loop/scripts/preflight.py
+
+@~/.claude/_shared/pr-loop/scripts/post_audit_thread.py
+
+@~/.claude/_shared/pr-loop/scripts/post_audit_review.py
+
+@~/.claude/_shared/pr-loop/scripts/gh_util.py
+
+@~/.claude/_shared/pr-loop/scripts/reviews_disabled.py
+
+@~/.claude/_shared/pr-loop/scripts/reviewer_availability.py
+
+@~/.claude/_shared/pr-loop/scripts/copilot_quota.py
+
+@~/.claude/_shared/pr-loop/scripts/grant_project_claude_permissions.py
+
+@~/.claude/_shared/pr-loop/scripts/revoke_project_claude_permissions.py
+
+@~/.claude/_shared/pr-loop/scripts/verify_review.py
+
+@~/.claude/_shared/pr-loop/scripts/README.md
+
+Skill-local converge helpers (`build_*_prompt.py`, `init_loop_state.py`, and siblings) live in this `scripts/` folder. Runtime gate, preflight, and review helpers live under `~/.claude/_shared/pr-loop/scripts/`.

package/skills/_shared/pr-loop/scripts/test_build_audit_prompt.py

@@ -378,3 +378,49 @@ def test_main_headless_flavor_emits_outcome_path_on_stdout(
     assert "post_audit_thread.py" in captured.out
     assert "Do not post reviews" in captured.out
     assert "add_comment_to_pending_review" not in captured.out
+
+
+_PACKAGE_ROOT = _SCRIPTS_DIR.parents[3]
+_CODE_QUALITY_AGENT_PATH = _PACKAGE_ROOT / "agents" / "code-quality-agent.md"
+_AUDIT_CONTRACT_PATH = _PACKAGE_ROOT / "_shared" / "pr-loop" / "audit-contract.md"
+_PRECATCH_RUBRIC_PATH = _PACKAGE_ROOT / "_shared" / "pr-loop" / "precatch-rubric.md"
+_CATEGORY_Q_LABEL = (
+    "Cross-surface claim consistency "
+    "(terminology, PR-description claims, message-vs-guard)"
+)
+_CATEGORY_Q_RUBRIC_REFERENCE = (
+    "../audit-rubrics/category_rubrics/category-q-cross-surface-claims.md"
+)
+_A_THROUGH_Q_PATTERN = re.compile(r"A[\u2013-]Q")
+_SEVENTEEN_CATEGORIES_PATTERN = re.compile(r"seventeen categor", re.IGNORECASE)
+_STALE_SIXTEEN_PATTERN = re.compile(r"sixteen categor", re.IGNORECASE)
+_STALE_A_THROUGH_P_PATTERN = re.compile(r"A[\u2013-]P")
+
+
+def test_code_quality_agent_default_scope_is_a_through_q() -> None:
+    agent_text = _CODE_QUALITY_AGENT_PATH.read_text(encoding="utf-8")
+    assert _A_THROUGH_Q_PATTERN.search(agent_text) is not None
+    assert _SEVENTEEN_CATEGORIES_PATTERN.search(agent_text) is not None
+    assert _STALE_SIXTEEN_PATTERN.search(agent_text) is None
+    assert "A through Q" in agent_text
+    assert "A through P" not in agent_text
+    assert _STALE_A_THROUGH_P_PATTERN.search(agent_text) is None
+    assert "## Bug Categories A–Q" in agent_text
+    assert _CATEGORY_Q_LABEL in agent_text
+    assert _CATEGORY_Q_RUBRIC_REFERENCE in agent_text
+    assert "| Q |" in agent_text
+
+
+def test_audit_contract_category_schema_includes_q() -> None:
+    contract_text = _AUDIT_CONTRACT_PATH.read_text(encoding="utf-8")
+    assert '"category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q"' in (
+        contract_text
+    )
+    assert _A_THROUGH_Q_PATTERN.search(contract_text) is not None
+    assert _STALE_A_THROUGH_P_PATTERN.search(contract_text) is None
+
+
+def test_precatch_rubric_adversarial_lane_uses_a_through_q() -> None:
+    rubric_text = _PRECATCH_RUBRIC_PATH.read_text(encoding="utf-8")
+    assert _A_THROUGH_Q_PATTERN.search(rubric_text) is not None
+    assert _STALE_A_THROUGH_P_PATTERN.search(rubric_text) is None

package/skills/_shared/pr-loop/state-schema.md

@@ -0,0 +1,5 @@
+# State schema
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/state-schema.md

package/skills/_shared/pr-loop/worker-spawn.md

@@ -0,0 +1,5 @@
+# Worker spawn
+
+**Canonical home:**
+
+@~/.claude/_shared/pr-loop/worker-spawn.md

package/skills/autoconverge/workflow/converge.contract.test.mjs

@@ -411,8 +411,13 @@ test('the shared verdict-fence builder names the binding-hash command and the ve
     /verification_verdict_store\.py/,
     'expected the verdict-store script that computes the binding hash to be named',
   );
-  assert.match(fenceBuilder, /```verdict/, 'expected the verdict fence to be specified');
-  assert.match(fenceBuilder, /manifest_sha256/, 'expected the verdict fence to carry manifest_sha256');
+  assert.match(fenceBuilder, /buildVerdictFenceTail\(/, 'expected the fence builder to close with the shared fence tail');
+  const renderedFenceTail = loadVerdictFenceTailBuilder()('');
+  assert.match(renderedFenceTail, /```verdict/, 'expected the verdict fence to be specified');
+  assert.ok(
+    renderedFenceTail.includes(VERDICT_FENCE_JSON_LINE),
+    'expected the verdict fence to carry manifest_sha256',
+  );
   assert.match(
     fenceBuilder,
     /gh pr view/,
@@ -425,6 +430,100 @@ test('the shared verdict-fence builder names the binding-hash command and the ve
   );
 });
 
+test('the incomplete-verdict contract sentence is written once and used by both verify paths', () => {
+  const sentenceOccurrences = convergeSource.split(
+    'name that check in prose directly above the fence rather than in findings',
+  ).length - 1;
+  assert.equal(
+    sentenceOccurrences,
+    1,
+    'expected the incomplete-verdict contract sentence to be written exactly once so the two verify paths cannot drift',
+  );
+  assert.match(
+    lensPromptBody('buildVerdictFenceTail'),
+    /VERDICT_FENCE_CONTRACT_SENTENCE/,
+    'expected the shared fence tail to use the one contract sentence',
+  );
+  assert.match(
+    lensPromptBody('buildVerdictFenceSteps'),
+    /buildVerdictFenceTail\(/,
+    'expected the gh-lookup fence builder to reach the contract sentence through the shared fence tail',
+  );
+  assert.match(
+    lensPromptBody('runVerifierTask'),
+    /buildVerdictFenceTail\(/,
+    'expected the hardening-verify prompt to reach the contract sentence through the shared fence tail',
+  );
+});
+
+const VERDICT_FENCE_JSON_LINE = '{"all_pass": true, "findings": [], "manifest_sha256": "<that hash>"}';
+const VERDICT_FENCE_LEAD_IN = 'END your message with a fenced verdict block exactly in this shape';
+
+function countOccurrences(haystack, needle) {
+  return haystack.split(needle).length - 1;
+}
+
+function loadVerdictFenceTailBuilder() {
+  const sentenceMatch = /const VERDICT_FENCE_CONTRACT_SENTENCE =\s*\n?\s*'[^']*'/.exec(convergeSource);
+  assert.notEqual(sentenceMatch, null, 'expected VERDICT_FENCE_CONTRACT_SENTENCE to be declared as one string literal');
+  const builderSource = lensPromptBody('buildVerdictFenceTail');
+  return new Function(
+    `${sentenceMatch[0]}\n${builderSource}\nreturn buildVerdictFenceTail;`,
+  )();
+}
+
+test('the verdict fence recipe is written once — no verify path re-inlines its own copy', () => {
+  assert.equal(
+    countOccurrences(convergeSource, VERDICT_FENCE_JSON_LINE),
+    1,
+    'expected the verdict fence JSON skeleton to be written exactly once so no verify path can drift from the shared recipe',
+  );
+  assert.equal(
+    countOccurrences(convergeSource, VERDICT_FENCE_LEAD_IN),
+    1,
+    'expected the fence lead-in sentence to be written exactly once so no verify path can drift from the shared recipe',
+  );
+  assert.match(
+    lensPromptBody('buildVerdictFenceSteps'),
+    /buildVerdictFenceTail\(/,
+    'expected the gh-lookup binding path to render its fence through the shared tail builder',
+  );
+  assert.match(
+    lensPromptBody('runVerifierTask'),
+    /buildVerdictFenceTail\(/,
+    'expected the hardening-verify path to render its fence through the shared tail builder',
+  );
+});
+
+test('the shared fence tail renders the same fence JSON and contract sentence at every indent', () => {
+  const buildVerdictFenceTail = loadVerdictFenceTailBuilder();
+  const topLevelTail = buildVerdictFenceTail('');
+  const nestedTail = buildVerdictFenceTail('   ');
+  for (const [siteName, renderedTail] of [['top-level', topLevelTail], ['nested', nestedTail]]) {
+    assert.ok(
+      renderedTail.includes(VERDICT_FENCE_JSON_LINE),
+      `expected the ${siteName} fence tail to carry the verdict JSON skeleton`,
+    );
+    assert.ok(
+      renderedTail.includes(VERDICT_FENCE_LEAD_IN),
+      `expected the ${siteName} fence tail to carry the fence lead-in sentence`,
+    );
+    assert.ok(
+      renderedTail.includes('```verdict'),
+      `expected the ${siteName} fence tail to open a verdict fence`,
+    );
+    assert.ok(
+      renderedTail.includes('name that check in prose directly above the fence rather than in findings'),
+      `expected the ${siteName} fence tail to carry the one incomplete-verdict contract sentence`,
+    );
+  }
+  assert.equal(
+    nestedTail,
+    topLevelTail.split('\n').map((eachLine) => `   ${eachLine}`).join('\n'),
+    'expected indent to be the only difference between the two rendered fence tails',
+  );
+});
+
 test('the verdict-fence binding does not self-resolve a cwd via git rev-parse for the manifest hash', () => {
   const fenceBuilder = lensPromptBody('buildVerdictFenceSteps');
   assert.doesNotMatch(
@@ -1006,6 +1105,7 @@ test('the whole priming spawn-agent family is removed — every dispatcher spawn
 
 test('parseLastVerdictFence returns non-null for a verdict fence with valid JSON', () => {
   const parseModule = new Function(
+    `${functionSource('findLastVerdictFence')}\n` +
     `${functionSource('parseLastVerdictFence')}\n` +
     'return { parseLastVerdictFence };',
   )();
@@ -1016,6 +1116,7 @@ test('parseLastVerdictFence returns non-null for a verdict fence with valid JSON
 
 test('parseLastVerdictFence returns null for non-string input', () => {
   const parseModule = new Function(
+    `${functionSource('findLastVerdictFence')}\n` +
     `${functionSource('parseLastVerdictFence')}\n` +
     'return { parseLastVerdictFence };',
   )();
@@ -1025,6 +1126,7 @@ test('parseLastVerdictFence returns null for non-string input', () => {
 
 test('parseLastVerdictFence returns null when no verdict fence is present', () => {
   const parseModule = new Function(
+    `${functionSource('findLastVerdictFence')}\n` +
     `${functionSource('parseLastVerdictFence')}\n` +
     'return { parseLastVerdictFence };',
   )();
@@ -1033,6 +1135,7 @@ test('parseLastVerdictFence returns null when no verdict fence is present', () =
 
 test('parseLastVerdictFence returns null for malformed JSON in the fence', () => {
   const parseModule = new Function(
+    `${functionSource('findLastVerdictFence')}\n` +
     `${functionSource('parseLastVerdictFence')}\n` +
     'return { parseLastVerdictFence };',
   )();

package/skills/autoconverge/workflow/converge.fix-recovery.test.mjs

@@ -255,7 +255,8 @@ test('the round-loop fix-stalled blockers survive the recovery wiring', () => {
 });
 
 const verifyObjectionModule = new Function(
-  `${functionSource('parseLastVerdictFence')}\n` +
+  `${functionSource('findLastVerdictFence')}\n` +
+    `${functionSource('parseLastVerdictFence')}\n` +
     `${constantLine('VERIFY_OBJECTION_FALLBACK')}\n` +
     `${functionSource('renderVerifyObjectionLine')}\n` +
     `${functionSource('extractPreFenceProse')}\n` +
@@ -350,6 +351,38 @@ test('the prose reader anchors on the last CLOSED fence, not a stray unterminate
   assert.doesNotMatch(objection, /all_pass/, 'expected the verdict body never to be read back as prose');
 });
 
+test('both fence readers locate the fence through the one shared locator', () => {
+  assert.match(
+    functionSource('parseLastVerdictFence'),
+    /findLastVerdictFence\(/,
+    'expected the verdict parser to locate its fence through findLastVerdictFence',
+  );
+  assert.match(
+    functionSource('extractPreFenceProse'),
+    /findLastVerdictFence\(/,
+    'expected the prose reader to locate its fence through findLastVerdictFence, not a second search',
+  );
+  assert.doesNotMatch(
+    functionSource('extractPreFenceProse'),
+    /lastIndexOf\(/,
+    'expected no second fence-search procedure in the prose reader to drift from the parser',
+  );
+});
+
+test('the prose reader and the verdict parser land on the same fence when a later marker carries no newline', () => {
+  const transcript =
+    'check X never showed red\n\n' +
+    '```verdict\n{"all_pass": false, "findings": []}\n```\n\n' +
+    '```verdict {"all_pass": true, "findings": []}```';
+  const objection = extractVerifyObjection(transcript);
+  assert.doesNotMatch(
+    objection,
+    /all_pass/,
+    'expected the prose reader to anchor on the fence the parser read, never to slice a verdict body in as prose',
+  );
+  assert.equal(objection, 'check X never showed red');
+});
+
 test('the prose reader skips a scaffolding-only paragraph above the fence', () => {
   const transcript =
     'check X never showed red\n\n' + '## Verdict\n\n' + '```verdict\n{"all_pass": false, "findings": []}\n```';