feat(pr-pipeline): run fix-docs on run-claude-cli with an apply-patch push job

.changes/pr-pipeline/feat-pr-pipeline-fix-docs-run-claude-cli-3c9f0b51.md

@@ -0,0 +1,11 @@
+---
+bump: minor
+---
+
+### Added
+
+- A skill activity's `permission-mode` (`dontAsk`, the default, or `auto`) sets the read
+  runner's launcher mode, through `resolve-config`'s new `permission-mode` output. A step after
+  each launcher leg fails the run unless the CLI's init message reports that mode. fix-docs sets
+  `auto`
+  ([ADR 0049](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/adr/0049-run-ci-lanes-on-github-hosted-runners-under-trigger-and-token-hardening.md)).

.changes/pr-pipeline/feat-pr-pipeline-fix-docs-run-claude-cli-7d1e4a20.md

@@ -0,0 +1,37 @@
+---
+bump: minor
+---
+
+### Changed
+
+- fix-docs moves into the `pr-unblock` lane, so its check is `pr-unblock / fix-docs`.
+  `pr-unblock-dispatch.yml` dispatches it on each push to main, once per open, ready pull request
+  a person opened that changes a Markdown file, carries no `do-not-merge` or `needs-human` label
+  and never had a fix-docs run, at most `limits.fix-docs-per-run` (default 2) per run
+  ([README, fix-docs](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/pr-pipeline/README.md)).
+- fix-docs runs on the read runner with no write token, on ci-workflows' run-claude-cli and the
+  automations role's API key first. pr-unblock.yml calls the read runner twice, each call with one
+  Claude secret: `fix-docs` passes only `AUTOMATIONS_CLAUDE_API_KEY`, and `fix-docs-subscription`
+  passes only `AUTOMATIONS_CLAUDE_CODE_OAUTH_TOKEN` and runs only after a credit stop or with the
+  key empty. Every fix-docs job trusts the default branch tip
+  ([pr-run-activity.md, Two calls on one credential each](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/pr-pipeline/pr-run-activity.md#two-calls-on-one-credential-each)).
+- fix-docs's change leaves as a patch that the `apply-docs-patch` job pushes as one commit, only
+  when a patch was written. A refused patch posts the `pr-unblock / apply-patch` check neutral and
+  labels nothing
+  ([pr-run-activity.md, prepare: apply-patch](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/pr-pipeline/pr-run-activity.md#prepare-apply-patch)).
+- The `default` row of
+  [`patch-rules.json`](https://github.com/melodic-software/claude-code-plugins/blob/main/.github/actions/resolve-config/patch-rules.json)
+  refuses every agent instruction path, caps a patch at 300 files and takes a moved head with
+  `--3way` (`skip-moved-head: false`).
+- The read runner's launcher takes a skill with no prepare mode that hands on a patch: Bash,
+  Edit, Write and Agent as tools, no Bash allow rule, and `Read(./.git/**)` denied. It fails red
+  on `checks`, `self-checks` and `verify-scripts`.
+- fix-docs routes to the new `docs-fix` profile, a mechanical worker from the multi-agent role
+  map, which resolves to sonnet.
+- The launcher accepts `web-access` (`domains: any` only), staging the research skills and their
+  plugins under `.lane/`. fix-docs leaves it off.
+
+### Removed
+
+- The `pr-refine` lane and `pr-refine.yml`, whose `pull_request` trigger ran the read runner's
+  scan job off main, where the `pr-pipeline-scan-carrier` environment refuses it.

.github/actions/collect-base-activity/action.yml

@@ -80,7 +80,9 @@ inputs:
       the CI context, a scratch directory and the prompt file are staged in
       $RUNNER_TEMP/lane-stage for the runner to copy to .lane/ after the head
       checkout, and the tool rules name them there. It takes a read skill
-      only (ci-context included), never a gate or an issue lane.
+      only (ci-context included, and one with no prepare mode that hands on
+      a patch), never a gate, an issue lane or an activity with checks,
+      self-checks or verify-scripts.
     required: false
     default: claude-code-action
 
@@ -217,8 +219,11 @@ runs:
         # preamble would not expand.
         if [ "$LAUNCHER" = run-claude-cli ]; then
           [ -z "${ISSUE_NUMBER:-}" ] || fail "run-claude-cli: an issue lane runs on claude-code-action"
-          [ "$edits" = read ] || fail "run-claude-cli: only a read skill, ci-context included, runs on the launcher"
+          [ "$edits" = read ] || { [ "$edits" = patch ] && [ -z "$PREPARE" ]; } ||
+            fail "run-claude-cli: only a read skill runs on the launcher, ci-context included, or one with no prepare mode that hands on a patch"
           [ "$GATING" = advisory ] || fail "run-claude-cli: a gate skill's verdict is not read from the launcher"
+          jq -e '[.selected.checks, .selected["self-checks"], .selected["verify-scripts"]] | all(. == null or . == [])' "$RESOLVED" >/dev/null ||
+            fail "run-claude-cli: checks, self-checks and verify-scripts have no wrapper on the launcher"
           [[ $WORKSPACE =~ ^/[A-Za-z0-9_./-]+$ && $STAGE =~ ^/[A-Za-z0-9_./-]+$ ]] ||
             fail "the workspace or the stage directory has a name a rule cannot carry"
           plugin=${SKILL%%:*}
@@ -252,6 +257,42 @@ runs:
             denied+=("Edit(./.lane/ci/**)" "Write(./.lane/ci/**)")
             preamble="$preamble Run every step the skill instructions name. Your scratchpad directory is $lane/scratch: put every temporary or state file there. The context file is $lane/ci/context.json. Leave every fix uncommitted in the working tree: the runner turns it into a patch that a later job pushes."
           fi
+          # A skill that hands on a patch with no prepare mode (fix-docs) gets
+          # Bash for the scripts its own frontmatter grants, which alone run
+          # under dontAsk: no Bash rule here. The base deny rules keep the git
+          # directory unread.
+          plugin_dirs=(".lane/plugins/$plugin")
+          if [ "$edits" = patch ]; then
+            tools+=(Bash Edit Write Agent)
+            allowed+=(Edit Write Agent)
+            preamble="$preamble Run every step the skill instructions name. Your scratchpad directory is $lane/scratch: put every temporary or state file there. Leave every change uncommitted in the working tree: the runner turns it into a patch that a later job pushes."
+            # web-access `any` only: the research plugins load from .lane/
+            # too, read-only like the skill's own. The docs scripts are not
+            # staged, so the run reads pages with WebFetch.
+            if [ "$(jq -r '.selected["web-access"].enabled // false' "$RESOLVED")" = true ]; then
+              jq -e '.selected["web-access"].domains == "any"' "$RESOLVED" >/dev/null ||
+                fail "run-claude-cli: web-access takes domains: any"
+              for research in discovery knowledge; do
+                [ -d "$BASE_PATH/plugins/$research" ] || fail "web-access: the $research plugin is not in the base"
+                [ -d "$STAGE/plugins/$research" ] || cp -R "$BASE_PATH/plugins/$research" "$STAGE/plugins/"
+                # Each plugin dir is an --add-dir too, so it gets the empty
+                # server list the skill's own copy gets.
+                mcp=$STAGE/plugins/$research/.mcp.json
+                [ -e "$mcp" ] || [ -L "$mcp" ] || printf '{"mcpServers":{}}\n' >"$mcp"
+                [ "$research" = "$plugin" ] || plugin_dirs+=(".lane/plugins/$research")
+              done
+              [ -z "$(find "$STAGE/plugins" -type l -print -quit)" ] || fail "a research plugin holds a symbolic link"
+              tools+=(WebFetch WebSearch)
+              allowed+=("WebFetch(domain:*)" WebSearch "Skill(discovery:read-docs)" "Skill(discovery:research)" "Skill(knowledge:docpage-digest)" "Skill(knowledge:map-corpus)")
+              # A deny rule beats an allow rule.
+              kept=()
+              for rule in "${denied[@]}"; do
+                [[ $rule == WebFetch || $rule == WebSearch ]] || kept+=("$rule")
+              done
+              denied=("${kept[@]}")
+              preamble="$preamble This run may search the web and read any page with WebFetch; the docs scripts the research skills use are not available, so read each page with WebFetch, and cite each page you read."
+            fi
+          fi
           skill_args=$(jq -r '.selected.args // ""' "$RESOLVED")
           for target in "${targets[@]}"; do
             skill_args="${skill_args:+$skill_args }$target"
@@ -269,7 +310,8 @@ runs:
             printf '%s\n' "${allowed[@]}" "$delimiter"
             echo "disallowed-tools<<$delimiter"
             printf '%s\n' "${denied[@]}" "$delimiter"
-            echo "plugin-dirs=.lane/plugins/$plugin"
+            echo "plugin-dirs<<$delimiter"
+            printf '%s\n' "${plugin_dirs[@]}" "$delimiter"
             echo "preamble=$preamble"
           } >>"$GITHUB_OUTPUT"
           exit 0

.github/actions/collect-base-activity/collect-base-activity.test.mjs

@@ -1268,7 +1268,7 @@ function launch(overrides = {}) {
     tools: outputOf(text, "tools"),
     allowedTools: outputOf(text, "allowed-tools"),
     deniedTools: outputOf(text, "disallowed-tools"),
-    pluginDirs: /^plugin-dirs=(.*)$/m.exec(text)?.[1] ?? "",
+    pluginDirs: outputOf(text, "plugin-dirs").join("\n"),
     preamble: /^preamble=(.*)$/m.exec(text)?.[1] ?? "",
     promptFile: (() => {
       try {
@@ -1316,14 +1316,26 @@ test("run-claude-cli: a read skill without ci-context gets no Bash, Edit or Writ
   assert.doesNotMatch(run.preamble, /context file/);
 });
 
-test("run-claude-cli refuses an issue lane, a writing skill, a patch-producing read skill and a gate before any output", () => {
-  const appliedBy = path.join(mkdtempSync(path.join(root, "launch-ab-")), "resolved.json");
-  writeFileSync(appliedBy, JSON.stringify({ selected: { args: "--ci", "applied-by": { patch: "apply-patch" } } }));
+// A resolved file for the launcher tests: the activity's args plus `extra`.
+function launchResolved(extra) {
+  const file = path.join(mkdtempSync(path.join(root, "launch-ab-")), "resolved.json");
+  writeFileSync(file, JSON.stringify({ selected: { args: "fix", ...extra } }));
+  return file;
+}
+const PATCH = { "applied-by": { patch: "apply-patch" } };
+
+test("run-claude-cli refuses an issue lane, a writing skill, a patch-producing skill with a prepare mode, a gate and any check before any output", () => {
+  const appliedBy = launchResolved(PATCH);
   for (const [overrides, message] of [
     [{ ISSUE_NUMBER: "7" }, /an issue lane runs on claude-code-action/],
     [{ EFFECT: "mutate-branch", CAN_COMMIT: "true" }, /only a read skill/],
-    [{ RESOLVED: appliedBy }, /only a read skill/],
+    [{ RESOLVED: appliedBy, PREPARE: "review-threads" }, /only a read skill/],
+    [{ RESOLVED: appliedBy, PREPARE: "dependency-review" }, /only a read skill/],
+    [{ RESOLVED: appliedBy, PREPARE: "merge-base" }, /only a read skill/],
     [{ GATING: "gate" }, /a gate skill's verdict is not read from the launcher/],
+    [{ RESOLVED: launchResolved({ ...PATCH, checks: ["scripts/check-x.sh --check"] }) }, /checks, self-checks and verify-scripts have no wrapper/],
+    [{ RESOLVED: launchResolved({ ...PATCH, "self-checks": ["scripts/check-x.sh"] }) }, /checks, self-checks and verify-scripts have no wrapper/],
+    [{ RESOLVED: launchResolved({ ...PATCH, "verify-scripts": [VERIFY] }) }, /checks, self-checks and verify-scripts have no wrapper/],
   ]) {
     const run = launch(overrides);
     assert.notEqual(run.status, 0, JSON.stringify(overrides));
@@ -1359,3 +1371,93 @@ test("run-claude-cli: a skill plugin holding a symbolic link fails red", () => {
   assert.match(run.stdout, /the skill's plugin holds a symbolic link/);
   assert.deepEqual(run.tools, []);
 });
+
+// fix-docs: a read skill with no prepare mode that hands on a patch gets Bash
+// for its own frontmatter grants (no Bash rule), Edit, Write and Agent, the
+// git directory denied, and the instruction to leave its change uncommitted.
+test("run-claude-cli: a patch-producing skill with no prepare mode gets Bash, Edit, Write and Agent, no Bash rule, and .git denied", () => {
+  const run = launch({ RESOLVED: launchResolved(PATCH), SKILL: "source-control:pull-request" });
+  assert.equal(run.status, 0, run.stdout);
+  assert.deepEqual(run.tools.toSorted(), ["Agent", "Bash", "Edit", "Glob", "Grep", "Read", "Skill", "Write"]);
+  assert.deepEqual(run.allowedTools.toSorted(), ["Agent", "Edit", "Glob", "Grep", "Skill(source-control:pull-request)", "Write"]);
+  for (const rule of ["WebFetch", "WebSearch", "Read(./.git/**)", "Read(//proc/**)", "Edit(./.lane/plugins/**)", "Write(./.lane/plugins/**)", "Edit(./.lane/trusted-context.json)", "Write(./.lane/trusted-context.json)"]) {
+    assert.ok(run.deniedTools.includes(rule), `${rule} in ${run.deniedTools.join(" | ")}`);
+  }
+  assert.equal(run.pluginDirs, ".lane/plugins/source-control");
+  assert.ok(statSync(path.join(run.stageDir, "plugins", "source-control")).isDirectory());
+  assert.ok(statSync(path.join(run.stageDir, "scratch")).isDirectory());
+  assert.ok(run.preamble.includes(`Your scratchpad directory is ${WORKSPACE}/.lane/scratch:`), run.preamble);
+  assert.ok(run.preamble.includes(UNCOMMITTED_SENTENCE), run.preamble);
+  assert.doesNotMatch(run.preamble, /context file/);
+  assert.equal(run.promptFile, "Call the Skill tool with skill source-control:pull-request and args fix, then follow the skill instructions to the end.\n");
+  assert.equal(run.args, "", "no claude_args for the launcher");
+  assert.deepEqual(run.plugins, []);
+});
+
+test("run-claude-cli: a ci-context skill that hands on a patch keeps the ci-context tool set and preamble", () => {
+  const ciDir = mkdtempSync(path.join(root, "ci-launch-ab-"));
+  writeFileSync(path.join(ciDir, "context.json"), "{}");
+  const run = launch({ RESOLVED: launchResolved(PATCH), PREPARE: "ci-context", CI_DIR: ciDir, SKILL: "source-control:pull-request" });
+  assert.equal(run.status, 0, run.stdout);
+  assert.ok(run.allowedTools.includes("Bash"), "ci-context keeps its own tool set");
+  assert.ok(!run.preamble.includes(UNCOMMITTED_SENTENCE), run.preamble);
+});
+
+// web-access on the launcher: `any` only, with the research plugins staged
+// under .lane/ beside the skill's own and the web tools neither stripped by
+// --restricted nor denied.
+function webBase() {
+  const dir = mkdtempSync(path.join(root, "base-web-"));
+  for (const plugin of ["source-control", "discovery", "knowledge"]) mkdirSync(path.join(dir, "plugins", plugin), { recursive: true });
+  mkdirSync(path.join(dir, ".claude-plugin"));
+  writeFileSync(path.join(dir, ".claude-plugin", "marketplace.json"), JSON.stringify({ name: "melodic-software" }));
+  return dir;
+}
+const RESEARCH = ["Skill(discovery:read-docs)", "Skill(discovery:research)", "Skill(knowledge:docpage-digest)", "Skill(knowledge:map-corpus)"];
+
+test("run-claude-cli: web-access any gives a patch skill WebFetch and WebSearch, the research skills and their plugins under .lane/", () => {
+  const run = launch({
+    BASE_PATH: webBase(),
+    RESOLVED: launchResolved({ ...PATCH, "web-access": { enabled: true, domains: "any" } }),
+    SKILL: "source-control:pull-request",
+  });
+  assert.equal(run.status, 0, run.stdout);
+  assert.ok(run.tools.includes("WebFetch") && run.tools.includes("WebSearch"), run.tools.join(" | "));
+  for (const rule of ["WebFetch(domain:*)", "WebSearch", ...RESEARCH]) {
+    assert.ok(run.allowedTools.includes(rule), `${rule} in ${run.allowedTools.join(" | ")}`);
+  }
+  assert.ok(!run.deniedTools.includes("WebFetch") && !run.deniedTools.includes("WebSearch"), run.deniedTools.join(" | "));
+  for (const rule of ["Read(./.git/**)", "Read(//proc/**)", "Edit(./.lane/plugins/**)", "Write(./.lane/plugins/**)"]) {
+    assert.ok(run.deniedTools.includes(rule), `${rule} in ${run.deniedTools.join(" | ")}`);
+  }
+  assert.equal(run.pluginDirs, ".lane/plugins/source-control\n.lane/plugins/discovery\n.lane/plugins/knowledge");
+  for (const plugin of ["discovery", "knowledge"]) {
+    assert.ok(statSync(path.join(run.stageDir, "plugins", plugin)).isDirectory(), plugin);
+    assert.equal(readFileSync(path.join(run.stageDir, "plugins", plugin, ".mcp.json"), "utf8"), '{"mcpServers":{}}\n', plugin);
+  }
+  assert.match(run.preamble, /cite each page you read/);
+  assert.ok(!run.allowedTools.some((rule) => rule.startsWith("Bash")), "no docs-script rule");
+});
+
+test("run-claude-cli: a patch skill without web-access gets no web tools and only its own plugin", () => {
+  const run = launch({ BASE_PATH: webBase(), RESOLVED: launchResolved(PATCH), SKILL: "source-control:pull-request" });
+  assert.equal(run.status, 0, run.stdout);
+  assert.ok(!run.tools.includes("WebFetch") && !run.tools.includes("WebSearch"), run.tools.join(" | "));
+  assert.ok(run.deniedTools.includes("WebFetch") && run.deniedTools.includes("WebSearch"), run.deniedTools.join(" | "));
+  assert.equal(run.pluginDirs, ".lane/plugins/source-control");
+  assert.doesNotMatch(run.preamble, /WebFetch/);
+});
+
+test("run-claude-cli: web-access with a domain list, or a research plugin missing from the base, fails red before any output", () => {
+  const noKnowledge = webBase();
+  rmSync(path.join(noKnowledge, "plugins", "knowledge"), { recursive: true });
+  for (const [overrides, message] of [
+    [{ BASE_PATH: webBase(), RESOLVED: launchResolved({ ...PATCH, "web-access": { enabled: true, domains: ["code.claude.com"] } }) }, /web-access takes domains: any/],
+    [{ BASE_PATH: noKnowledge, RESOLVED: launchResolved({ ...PATCH, "web-access": { enabled: true, domains: "any" } }) }, /the knowledge plugin is not in the base/],
+  ]) {
+    const run = launch({ SKILL: "source-control:pull-request", ...overrides });
+    assert.notEqual(run.status, 0, JSON.stringify(overrides));
+    assert.match(run.stdout, message);
+    assert.deepEqual(run.tools, []);
+  }
+});

.github/actions/resolve-config/action.yml

@@ -142,6 +142,12 @@ outputs:
   applied-by-patch:
     description: The activity that applies the selected activity's patch (its applied-by.patch); empty when it hands on none.
     value: ${{ steps.resolve.outputs.applied-by-patch }}
+  permission-mode:
+    description: >
+      A skill activity's launcher permission mode, `dontAsk` (the default)
+      or `auto`, for run-claude-cli's `permission-mode` input; empty for a
+      script.
+    value: ${{ steps.resolve.outputs.permission-mode }}
   issue-dimensions:
     description: >
       `<size>/<complexity>/<uncertainty>` as models.issue-dimensions reads

.github/actions/resolve-config/activity-rules.json

@@ -22,6 +22,10 @@
     "forbidden-effects": ["publish-artifact", "mutate-tracker", "merge"],
     "never": "Posts to the pull request, merges, closes, or pushes under .github/"
   },
+  "fix-docs": {
+    "forbidden-effects": ["publish-artifact", "mutate-tracker", "mutate-branch", "merge"],
+    "never": "Holds a write token: it runs a script on head files, and its change leaves only as a patch"
+  },
   "fix-ci": {
     "forbidden-effects": ["publish-artifact", "mutate-tracker", "mutate-branch", "merge"],
     "never": "Holds a write token: it runs head code, and its change leaves only as a patch"