gentle-shellBLOCK

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: gentle-ai-branch-pr
description: "Create Gentle AI pull requests with issue-first checks. Trigger: creating, opening, or preparing PRs for review."
license: Apache-2.0
metadata:
  author: gentleman-programming
  version: "2.0"
---

## When to Use

Use this skill when:
- Creating a pull request for any change
- Preparing a branch for submission
- Helping a contributor open a PR

---

## Critical Rules

1. **Every PR MUST link an approved issue** — no exceptions
2. **Every PR MUST have exactly one `type:*` label**
3. **REQUIRED CI must pass according to target policy** before merge; CodeRabbit is optional unless required by that policy
4. **Blank PRs without issue linkage will be blocked** by GitHub Actions

---

## Target and Authorization

- Inspect `origin` locally (`git remote get-url origin`) and establish one unambiguous target host and `owner/repo`. Do not infer the target from the cwd or assume `main`. Stop if ambiguous.
- Obtain explicit remote destination, operation and credential/session authorization before any target-host reads, including `gh auth status` or repository metadata. Do not inspect or reuse an ambient SSH agent. Permission for a read does not authorize a write; confirm each remote operation is within the grant.
- Once authorized, reuse fresh target-bound issue, default branch, type labels and checks evidence from this session instead of repeating discovery. Refresh stale or mismatched evidence; do not substitute another host's data. Resolve the base from the authorized target's default branch or a human-selected base.
- Do not automatically commit, push, open a PR or merge. Prepare and report a candidate; perform each action only with its own authorization. Local preparation is not permission for remote delivery.

## Workflow

1. Identify the authorized target and verify that the linked issue is approved; choose with the human whether the reference closes it or is nonclosing.
2. Select the base from target metadata and prepare a `type/description` branch only when requested.
3. Implement in work units with conventional commits when authorized; follow the merged ODD applicable test-first policy, run applicable tests, shellcheck on modified scripts, and test changed skills in at least one agent when relevant. The per-task advisory 400 authored-line heuristic is not an automatic split or a reason to omit tests or docs.
4. Prepare the PR body from the target template and evidence. On separate authorization, open the PR and add exactly one `type:*` label.
5. Check target-policy required CI and report pending/failing checks rather than declaring merge-ready.

---

## Branch Naming

Branch names MUST match this regex:

```
^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$
```

**Format:** `type/description` — lowercase, no spaces, only `a-z0-9._-` in description.

| Type | Branch pattern | Example |
|------|---------------|---------|
| Feature | `feat/<description>` | `feat/user-login` |
| Bug fix | `fix/<description>` | `fix/zsh-glob-error` |
| Chore | `chore/<description>` | `chore/update-ci-actions` |
| Docs | `docs/<description>` | `docs/installation-guide` |
| Style | `style/<description>` | `style/format-scripts` |
| Refactor | `refactor/<description>` | `refactor/extract-shared-logic` |
| Performance | `perf/<description>` | `perf/reduce-startup-time` |
| Test | `test/<description>` | `test/add-setup-coverage` |
| Build | `build/<description>` | `build/update-shellcheck` |
| CI | `ci/<description>` | `ci/add-branch-validation` |
| Revert | `revert/<description>` | `revert/broken-setup-change` |

---

## PR Body Format

Use the authorized target's `.github/PULL_REQUEST_TEMPLATE.md`. Fill it from observed evidence, retaining its required sections.

### 1. Linked Issue (REQUIRED)

Use the human-selected closing (`Closes #N`, `Fixes #N`, or `Resolves #N`) or nonclosing `Refs #N` reference. Do not turn `Refs` into an automatic close. The linked issue MUST have the `status:approved` label; reuse fresh target-bound verification.

### 2. PR Type (REQUIRED)

Check exactly ONE in the template and add the matching label:

| Checkbox | Label to add |
|----------|-------------|
| Bug fix | `type:bug` |
| New feature | `type:feature` |
| Documentation only | `type:docs` |
| Code refactoring | `type:refactor` |
| Maintenance/tooling | `type:chore` |
| Breaking change | `type:breaking-change` |

### 3. Summary

1-3 bullet points of what the PR does.

### 4. Changes Table

```markdown
| File | Change |
|------|--------|
| `path/to/file` | What changed |
```

### 5. Test Plan

Record actual commands and outcomes, including shellcheck on modified scripts, manual testing of affected functionality, and whether changed skills load in at least one agent. Mark inapplicable checks as such; do not invent successful runs.

### 6. Contributor Checklist

Do not mark an unverified `[x]` checkbox. Check each item only after evidence supports it; leave pending items unchecked, including approved issue, exactly one `type:*` label, applicable shellcheck, skills tested in at least one agent, docs updated if behavior changed, conventional commit format, and no `Co-Authored-By` trailers. If a template demands every box checked, resolve outstanding items before submission rather than falsely attesting.

---

## Labels and Automated Checks

- Apply exactly one `type:*` label from the authorized target's available labels. A commit-type mapping below is a suggestion, not proof of label availability or permission.
- Protected labels require an exact direct instruction naming the label and an actor with MAINTAIN/ADMIN permission. Do not infer authorization from a general request to prepare or open a PR.
- For a PR above the advisory 400 authored-line review budget, record the human-selected `size:exception` rationale if that route was selected; no separate instructor proof is required. Apply the protected label only under the same direct-instruction and actor rule. Do 

BLOCKgrade D · trust 67/100 Do not install this without reading the findings. The audit found something that could harm you or your machine.

What the source does

Filesystem

declared (5 observation(s))

Network

declared (1 observation(s))

Shell

declared (6 observation(s))

Dependencies

not all pinned

Secrets in source

found

Findings (25)

const result = await exec({ file: resolve(), arguments: ["telemetry", "policy", "--json"],

const secret = "private-fixture-path-and-user";

if (lists === 2) writeFileSync(marker, JSON.stringify({ ...owner, token: "00000000-0000-4000-8000-000000000000" }));

writeFileSync(marker, JSON.stringify({ ...JSON.parse(bytes), token: "00000000-0000-4000-8000-000000000000" }));

return exec(file, args, options);

contentHash = createHash("sha1").update(await readFile(file)).digest("hex");

return createHash("sha1").update(lines.join("\n")).digest("hex");

const sensitiveEdit = await toolHook({ toolName: "edit", input: { edits: [], path: join(toolCwd, "id_rsa.pem") } }, createCtx(toolCwd));

import { gentlePiConfigHome } from "../../lib/agent-home.ts";

} from "../../lib/history-capture-policy.ts";

import { REVIEW_HOST_RELAY_FAILURE, ReviewHostRelayError, classifyReviewHostRelayRefusal, resolveReviewHostRelaySubmission, runReviewHostRelaySlot } from "../../lib/review-host-relay.ts";

import { GENTLE_PI_REVIEW_RELAY_CONTRACT, GENTLE_PI_REVIEW_RELAY_CONTRACT_ENV } from "../../lib/review-relay-contract.ts";

import { decodeReviewLastEventClosureV1 } from "../../runtime/review-integration-v2.mjs";

for (const key of ["é", " ", "👩💻"]) editor.handleInput(key);

assert.equal(editor.getText(), "é 👩💻one two three");

editor.handleInput("c"); editor.handleInput("w"); editor.handleInput("👩💻"); editor.handleInput("é"); editor.handleInput("\x1b");

assert.equal(editor.getText(), "👩💻étwo three");

assert.equal(editor.getText(), "👩💻étwo 👩💻é");

@types/node, typescript

because the module's *own* contract (never invent an `apiKey`, never read `process.env`) is worth

resolvers already read `process.env` through the auth context and `getApiKeyAndHeaders` runs before

Before any remote read or PR creation, require explicit human authorization for the destination (exact host/repository), operation (PR read or creation), and credential/session. Do not probe credentia

- For NaN Cloud, usage comes from the quota endpoint the official dashboard reads, with the same API key pi already holds. Each metered model reports one allowance for the billing period, and that win

- `orchestrator_session_id`, `orchestrator_list`, and `orchestrator_send_message` provide local-profile session notifications. List results advertise IDs only and reachability remains unknown. Sending

assets/gentle-logo-only.png

Gates applied: no_behavioural_pass.