@perrylink/dsh-github 0.6.0 → 0.6.2

package/README.md

@@ -1,131 +1,90 @@
-<h1 align="center">dsh-github</h1>
-
-<p align="center">
-  <b>Bring GitHub into DeepSeek Harness.</b><br/>
-  Create pull requests · review PRs with inline or summary comments · manage issues · search — every write gated by human approval, token never logged.
-</p>
-
-<p align="center">
-  <a href="README.zh-CN.md">中文</a> ·
-  <a href="README.es.md">Español</a> ·
-  <a href="README.pt.md">Português</a> ·
-  <a href="README.hi.md">हिन्दी</a>
-</p>
-
-<p align="center">
-  <img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License: Apache 2.0">
-  <img src="https://img.shields.io/badge/dsh-0.1.0--rc.6-4D6BFE" alt="dsh: 0.1.0-rc.6">
-  <img src="https://img.shields.io/badge/dsh-dsh--plugin-4D6BFE" alt="dsh-plugin">
-  <img src="https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen" alt="Node: ^22.19 || >=24">
-  <img src="https://github.com/PerryLink/dsh-github/actions/workflows/ci.yml/badge.svg" alt="CI">
-  <img src="https://img.shields.io/badge/documents-EN%2FZH%2FES%2FPT%2FHI-8257D0" alt="Documents: EN/ZH/ES/PT/HI">
-</p>
+<div align="center">
 
----
+# dsh-github
+
+**GitHub PRs, reviews, issues, and CI for DeepSeek Harness — every write gated by human approval, token never logged.**
+
+*Create, review, merge, and search GitHub from the agent, with a CI composite action, polling review bot, and status-check gate.*
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![DSH plugin](https://img.shields.io/badge/dsh-plugin-✅-green)](https://github.com/topics/dsh-plugin)
+[![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen.svg)](#)
+[![CI](https://img.shields.io/github/actions/workflow/status/PerryLink/dsh-github/ci.yml?branch=main&label=CI)](https://github.com/PerryLink/dsh-github/actions)
+[![Version](https://img.shields.io/github/v/tag/PerryLink/dsh-github?label=version)](https://github.com/PerryLink/dsh-github/releases)
+[![npm version](https://img.shields.io/npm/v/%40perrylink%2Fdsh-github)](https://www.npmjs.com/package/@perrylink/dsh-github)
+[![npm downloads](https://img.shields.io/npm/dm/%40perrylink%2Fdsh-github)](https://www.npmjs.com/package/@perrylink/dsh-github)
 
-**dsh-github** is a bundle plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) — the "everything is a plugin" agent harness. It fills the GitHub gap between dsh and tools like [Claude Code](https://github.com/anthropics/claude-code) (`gh claude` / [claude-code-action](https://github.com/anthropics/claude-code-action)) and [Codex](https://github.com/openai/codex) (`@codex review` / Autofix CI): your agent can **read a PR, review a PR, open a PR, merge and update PRs, read repo metadata and files, comment on and close issues, and search** — while a human approves every write and the token stays secret.
+[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
 
-- 🛠 **12 tools** — `pr_create` · `pr_merge` · `pr_update` · `gh_review` · `review_post` · `gh_issue` · `issue_open` · `issue_comment` · `issue_close` · `gh_search` · `gh_repo` · `gh_file`, all canonical-JSON via `defineTool`
-- ⌨️ **3 command families** — `/pr create` · `/review` (start/stop/post) · `/issue open`
-- 🔀 **Full PR lifecycle** — create → review → update (title/body/state/base) → merge (merge/squash/rebase, optional head-branch delete)
-- 📝 **Inline reviews** — `review_post` posts either one summary comment or line-anchored review comments against the PR head commit
-- 🔒 **Approval-gated writes** — every GitHub write goes through `ctx.approval` (default `ask`, fail-closed); approval reasons preview titles, body sizes, and comment overrides
-- 🗝 **Token secrecy** — credentials seam → environment → `gh` CLI, resolved per operation, never in logs, events, renders, or errors
-- 🖥 **Background review jobs** — `/review` runs on `ctx.jobs` with the host's own `job_list` / `job_output` / `job_kill` surface, and reports CI status and comment counts alongside the findings
-- 🤖 **Model review option** — `reviewMode: "model"` delegates the capped diff to a one-shot subagent through the host's `subagents` seam; the default `static` mode stays deterministic and token-free
-- 🚦 **429 backoff + quota surfacing** — the model sees the remaining rate limit on every result, including failures; per-section fetch errors are surfaced instead of swallowed
-- 🌐 **5-language docs** — English · 中文 · Español · Português · हिन्दी
+</div>
 
 ---
 
 ## 📚 Table of contents
 
-- [Quick start](#🚀-quick-start)
-- [Features](#✨-features)
-- [Installation](#📦-installation)
-- [Configuration](#⚙️-configuration)
-- [Tools](#🛠-tools)
-- [Commands](#⌨️-commands)
-- [Architecture](#🏗-architecture)
-- [Security boundaries](#🔒-security-boundaries)
-- [Known limitations](#⚠️-known-limitations)
-- [Development](#🧪-development)
-- [Repository layout](#🗂-repository-layout)
-- [Topics](#🏷-topics)
-- [License](#license)
+- [Compatibility](#compatibility)
+- [What you get](#what-you-get)
+- [Quick start](#quick-start)
+- [Install & uninstall](#install-&-uninstall)
+- [Configuration](#configuration)
+- [Tools & surfaces](#tools-&-surfaces)
+- [Architecture](#architecture)
+- [Permissions & data](#permissions-&-data)
+- [Security boundaries](#security-boundaries)
+- [Known limitations](#known-limitations)
+- [Development](#development)
+- [Repository layout](#repository-layout)
+- [Topics](#topics)
+- [Contributors](#contributors)
 - [PerryLink DSH Plugin Family](#perrylink-dsh-plugin-family)
+- [License](#license)
 
-## 🚀 Quick start
+## Compatibility
 
-```sh
-# 1. install (npm registry — simplest; or use the tarball channel below)
-dsh plugin --profile <name> add @perrylink/dsh-github
-#    tarball channel (no registry needed):
-#    pnpm pack → dsh-github-<version>.tgz
-#    dsh plugin --profile <name> add ./dsh-github-<version>.tgz
-
-# 2. configure a GitHub token (recommended: the credentials seam)
-#    $DSH_HOME/.credentials.yaml
-#    GITHUB_TOKEN: <your token>
-
-# 3. use it — in the dsh web UI or headless
-#    /pr create "add dark mode"      → agent drafts & opens the PR (approval required)
-#    /review 42                      → background review job, read it with job_output
-#    /review post github-review-1    → publish the review comment (approval required)
-#    /issue open "crash on startup"  → agent opens the issue (approval required)
-```
+| Surface | Status |
+|---|---|
+| Harness | DeepSeek Harness `0.1.0-rc.6` (compat declared for `0.1.0-rc.5`–`0.1.0-rc.6`) |
+| Node | `^22.19.0 \|\| >=24.0.0` |
+| Platforms | All (host plugin; outbound network to GitHub) |
+| Model | Any (static review is deterministic; `reviewMode: "model"` is optional) |
 
-Verify: `dsh --profile <name> --dump-config` must show the `# == dsh-github` section with **no FAILED lines**.
+## What you get
 
-## ✨ Features
+`dsh-github` fills the GitHub gap between `dsh` and tools like Claude Code and Codex: your agent can read, review, open, update, and merge pull requests, read repository metadata and files, comment on and close issues, and search — while a human approves every write and the token stays secret.
 
-| Area | What you get |
-|---|---|
-| **Create PRs** | `/pr create [title]` reads git state (branch, changed files, commits ahead) and hands the agent a draft; `pr_create` opens the PR and returns its URL |
-| **Update PRs** | `pr_update` edits title, body, state, or target branch — approval-gated like every other write |
-| **Merge PRs** | `pr_merge` merges with `merge`/`squash`/`rebase`, optional commit title/message and head-branch deletion after the merge |
-| **Review PRs** | `gh_review` summarizes metadata, capped diff (full text in the canonical value, bounded excerpt in the render), comments, CI status, and static findings — per-section fetch failures are reported as `diff.error` / `comments.error` / `ci.error` |
-| **Post reviews** | `review_post` publishes one aggregated issue-level comment (`mode: "summary"`, default) or line-anchored review comments on the PR head commit (`mode: "inline"`); a `body` override lets the model polish the comment first — after human approval |
-| **Background reviews** | `/review <pr>` fetches metadata, the capped diff, CI checks, and existing comments in a `ctx.jobs` job; the completion output carries the findings summary, CI status, and comment count. `reviewMode: "model"` delegates the diff to a one-shot subagent instead of the static analyzer |
-| **Read repos** | `gh_repo` reads repository metadata: description, default branch, visibility, stars, forks, open issues, language, license, topics |
-| **Read files** | `gh_file` reads one file at a branch/tag/commit with base64 decoding and a configurable cap; directories report a structured error |
-| **Read issues** | `gh_issue` lists / gets / comments; pull requests in listings are marked `kind: "pr"` |
-| **Manage issues** | `issue_open` creates, `issue_comment` comments (also works on PRs), `issue_close` closes with an optional state reason — all approval-gated |
-| **Search** | `gh_search` queries issues and pull requests with GitHub search syntax, surfacing the separate search quota |
-| **Approval** | `tools/pre-execute` asks `ctx.approval` for every write; `allowedActions` whitelist denies before prompting |
-| **Secret safety** | Token is read per operation and sent only in the Authorization header; a dedicated test asserts it never appears in any visible output |
-| **Resilience** | 429 retry with `Retry-After`/`x-ratelimit-reset` backoff; read tools are concurrency-safe; all calls honor cancellation |
-| **Observability** | Model-visible ⇔ logged: everything the model sees flows through the host's own session events (`tool/result`, `user/message`, `command/run`, `approval/asked`…) |
-
-## 📦 Installation
-
-Four documented channels — pick one.
-
-| Channel | Command | Notes |
-|---|---|---|
-| **npm registry** | `dsh plugin --profile <name> add @perrylink/dsh-github` | Published package — the simplest channel |
-| **npm tarball** | `dsh plugin --profile <name> add ./dsh-github-<version>.tgz` | Ships with `lib/` built — no build permission |
-| **git source** | `dsh plugin --profile <name> add "github:PerryLink/dsh-github#<sha>"` | Needs `prepare` + `allowBuilds` (see below); pin the commit |
-| **local link** | `pnpm link --dir .` then `dsh plugin add @perrylink/dsh-github` | Development |
+- **12 tools** — `pr_create`, `pr_merge`, `pr_update`, `gh_review`, `review_post`, `gh_issue`, `issue_open`, `issue_comment`, `issue_close`, `gh_search`, `gh_repo`, `gh_file`, all canonical JSON via `defineTool`.
+- **3 command families** — `/pr create`, `/review` (start/stop/post), `/issue open`.
+- **Full PR lifecycle** — create → review → update (title/body/state/base) → merge (merge/squash/rebase, optional head-branch delete).
+- **Inline reviews** — `review_post` posts one summary comment or line-anchored review comments against the PR head commit.
+- **Approval-gated writes** — every GitHub write goes through `ctx.approval` (default `ask`, fail-closed); approval reasons preview titles, body sizes, and comment overrides.
+- **Token secrecy** — credentials seam → environment → `gh` CLI, resolved per operation, never in logs, events, renders, or errors.
+- **Background review jobs** — `/review` runs on `ctx.jobs` with the host's own `job_list` / `job_output` / `job_kill` surface.
+- **Resilience** — 429 retry with `Retry-After`/`x-ratelimit-reset` backoff; read tools are concurrency-safe; all calls honor cancellation.
+- **CI surface** — the one-shot `ci_run` tool, a polling review bot, and a status-check gate (composite action `action.yml`).
 
-> The npm package is published under the `@perrylink` scope because the
-> unscoped `dsh-github` name is owned by an unrelated project on the registry.
-> The plugin's module name stays `dsh-github`.
+## Quick start
 
-Git installs: pnpm ≥10 refuses a git dependency's `prepare` until allowlisted — `dsh` prints the exact key; copy it into the profile's `pnpm-workspace.yaml`:
+```sh
+# 1. install the bundle into your profile
+dsh plugin --profile web add "github:PerryLink/dsh-github#main"
+
+# or from npm (published releases)
+dsh plugin --profile web add @perrylink/dsh-github
 
-```yaml
-allowBuilds:
-  '@perrylink/dsh-github': true
+# 2. restart and verify the row
+dsh --profile web --dump-config | grep -A3 'id: dsh-github'
 ```
 
-The `prepare` script (`scripts/prepare.mjs`) is self-contained: it builds with TypeScript when a compiler is resolvable, otherwise falls back to the **committed `lib/` artifacts**, and fails loud with neither.
+## Install & uninstall
 
-**Uninstall:** `dsh plugin --profile <name> remove @perrylink/dsh-github`.
+- **git channel** (latest `main`): `dsh plugin --profile web add "github:PerryLink/dsh-github#main"` — the `prepare` script builds with production dependencies only.
+- **npm channel** (published releases): `dsh plugin --profile web add @perrylink/dsh-github`.
+- **tarball channel**: `pnpm pack` in this repo, then `dsh plugin --profile web add ./dsh-github-<version>.tgz`.
+- **uninstall**: `dsh plugin --profile web remove dsh-github` (or remove the row from the profile patch).
 
-## ⚙️ Configuration
+## Configuration
 
-Schemastery-validated at load time (fail loud). Override any key in the profile's `cordis.patch.yml` (the whole row config is replaced, never deep-merged).
+All tunables are Schemastery `Config` fields (changeable from cordis.yml). An id-targeted override replaces the whole row — restate every key you need. `cordis.patch.yml` documents each key inline.
 
 | Key | Default | Meaning |
 |---|---|---|
@@ -152,97 +111,71 @@ Schemastery-validated at load time (fail loud). Override any key in the profile'
 | `workspaceDir` | process cwd | Working directory for read-only git inspection |
 | `ci` | `{ enabled: false, … }` | CI integration section: polling review bot, status-check gate, and the one-shot `ci_run` tool (all `ci.*` keys live inside it) |
 
-## 🛠 Tools
-
-| Tool | Kind | Parameters | Returns |
-|---|---|---|---|
-| `pr_create` | write | `title*`, `body?`, `base?`, `head?`, `draft?`, `ownerRepo?` | `{status:'created', url, number, title, state, draft, base, head, rateLimit}` or structured error |
-| `pr_merge` | write | `pr*` (number / `#n` / `o/r#n` / URL), `mergeMethod?`, `commitTitle?`, `commitMessage?`, `deleteBranch?` | `{status:'merged', merged, sha?, message, url, branchDeleted, branchDeleteNote?, rateLimit}` or structured error |
-| `pr_update` | write | `pr*` (number / `#n` / `o/r#n` / URL), `title?`, `body?`, `state?` (`open`/`closed`), `base?` | `{status:'updated', url, number, title, state, base, rateLimit}` or structured error |
-| `gh_review` | read | `pr*` (number / `#n` / `o/r#n` / URL), `fields?`, `maxDiffChars?` | metadata, capped diff (full `diff.text` + bounded `diff.excerpt` + per-file stats), comments, CI, static findings, per-section `error` fields, rate limit |
-| `gh_repo` | read | `ownerRepo?` | `{repo, description, defaultBranch, visibility, stars, forks, openIssues, language, license, topics, url, updatedAt, rateLimit}` or structured error |
-| `gh_file` | read | `ownerRepo?`, `path*`, `ref?`, `maxChars?` | `{repo, path, ref, size, truncated, content, sha, url, rateLimit}` or structured error |
-| `gh_issue` | read | `action*` (`list`/`get`/`comments`), `ownerRepo?`, `issueNumber?`, `state?`, `limit?` | normalized items (each marked `kind: issue/pr/comment`) + rate limit |
-| `review_post` | write | `jobId*`, `mode?` (`summary`/`inline`), `body?` | `{status:'posted', mode, url, commentId?, reviewId?, findings, rateLimit}` or structured error |
-| `issue_open` | write | `title*`, `body?`, `labels?`, `ownerRepo?` | `{status:'created', url, number, title, rateLimit}` or structured error |
-| `issue_comment` | write | `issueNumber*`, `body*`, `ownerRepo?` | `{status:'commented', url, commentId, issueNumber, rateLimit}` or structured error |
-| `issue_close` | write | `issueNumber*`, `ownerRepo?`, `stateReason?` (`completed`/`not_planned`) | `{status:'closed', url, number, title, rateLimit}` or structured error |
-| `gh_search` | read | `q*`, `sort?`, `order?`, `perPage?` | `{query, total, items[{number,title,state,kind,author,url,repo,comments,createdAt}], rateLimit}` or structured error |
+## Tools & surfaces
 
-`execute` returns only the canonical JSON declared by `output.schema`. Missing-token and GitHub-API failures are structured error variants carrying rate-limit facts; infrastructure failures throw (→ `isError`). `exec.signal` is honored everywhere.
-
-## ⌨️ Commands
-
-| Command | Effect |
-|---|---|
-| `/pr create [title]` | Reads git state and queues a `pr_create` instruction for the model (draft body, defaults, no commit/push unless `autoCommit`). Creating the PR asks for approval. |
-| `/review <pr>` | Starts a background review job; prints the job id. Completion is announced by the host; read it with `job_output`. |
-| `/review <pr> --max-diff <n> --no-ci --no-comments` | Per-job overrides: diff cap and which supplementary sections the job fetches. |
-| `/review stop <jobId>` | Cancels the job (local control, no GitHub write). |
-| `/review post <jobId>` | Queues a `review_post` instruction for the model (summary or inline); posting asks for approval. |
-| `/issue open <title>` | Queues an `issue_open` instruction for the model; creating asks for approval. |
+| Surface | Kind | Notes |
+|---|---|---|
+| `pr_create` | tool | Create a pull request (write; approval-gated) |
+| `pr_merge` | tool | Merge a PR (merge/squash/rebase, optional head-branch delete) |
+| `pr_update` | tool | Update a PR (title/body/state/base) |
+| `gh_review` | tool | Read a PR: metadata, capped diff, comments, CI, static findings |
+| `review_post` | tool | Publish a review comment (summary or line-anchored inline) |
+| `gh_issue` | tool | List / get / comment on issues (PRs marked `kind: "pr"`) |
+| `issue_open` | tool | Create an issue |
+| `issue_comment` | tool | Comment on an issue or PR |
+| `issue_close` | tool | Close an issue (optional state reason) |
+| `gh_search` | tool | Search issues and PRs (separate search quota) |
+| `gh_repo` | tool | Read repository metadata |
+| `gh_file` | tool | Read one file at a branch/tag/commit |
+| `/pr create` | command | Read git state and queue a `pr_create` instruction |
+| `/review` | command | Start / stop / post a background review job |
+| `/issue open` | command | Queue an `issue_open` instruction |
+| `ci_run` | tool | One-shot CI review run by the composite action / CI driver |
+| review bot | surface | Polling review bot with idempotent inline comments (`ci.*`) |
+| status-check gate | surface | Publishes the `success` / `needs-changes` verdict per PR head commit (`action.yml`) |
+
+## Architecture
 
-## 🏗 Architecture
+- **Credential seam.** `tokenSource: auto` resolves per operation in the order credentials seam (`GITHUB_TOKEN` reference) → environment variable → `gh` CLI token. The value is a local variable handed to the REST client; it never enters canonical values, renders, cards, command outputs, injected notices, job output, approval reasons, or error messages.
+- **Approval gate.** All writes flow through model tools. A `tools/pre-execute` waterfall listener returns `ask` for the write tools, so the registry asks the human through `ctx.approval` (the host logs the `approval/asked` + `approval/decided` audit pair) and fails closed without an answerer. Commands never write directly: a write command gathers read-only context, then wakes the agent so the model runs the gated tool inside a turn.
+- **Background review job.** `/review <pr>` starts a `github-review` job on `ctx.jobs`; the job fetches metadata (capturing the head-commit SHA for inline posting), the capped diff, CI checks, and existing comments, then runs the deterministic multi-file analyzer (`src/review.ts`). With `reviewMode: "model"`, the job hands the capped diff to a one-shot subagent through the host's `subagents` seam. Completion reaches the session through the host's `dsh-tool-jobs` consumer; the model reads it with `job_output` and publishes it with `review_post`.
+- **CI composite action / review bot / status-check gate.** The repo ships a composite action (`action.yml`) that reviews PRs, fixes CI, and writes the report; a polling review bot posts idempotent inline comments; and a status-check gate publishes the verdict per PR head commit. The one-shot `ci_run` tool drives the headless run. Every write stays approval-gated.
 
-```
-                    ┌───────────────────────────────────────────────┐
-                    │                   dsh-github                  │
-                    │                                               │
- humans ─── /pr ────┼──► git reader (read-only) ──► agent.followup  │
-         /review ───┼──► ctx.jobs.start("github-review") ──► job    │
-         /issue ────┼──► agent.followup                              │
-                    │                                               │
- model ─── pr_create / pr_merge / pr_update / gh_review /           │
-           review_post / gh_issue / issue_open / issue_comment /    │
-           issue_close / gh_search / gh_repo / gh_file              │
-           (defineTool, canonical JSON only)                        │
-                    │                                               │
-                    └───────┬───────────────┬───────────────┬───────┘
-                            │               │               │
-                  tools/pre-execute     credential        GitHub REST
-                  approval gate        resolution        client (fetch,
-                  (ask | deny)      (seam → env →       429 retry,
-                                    gh CLI, per-op)     rate-limit)
-```
+## Permissions & data
 
-- **Credential seam.** `tokenSource: auto` resolves per operation in the order credentials seam (`GITHUB_TOKEN` reference) → environment variable → `gh` CLI token. The value is a local variable handed to the REST client; it never enters canonical values, renders, cards, command outputs, injected notices, job output, approval reasons, or error messages.
-- **Approval.** All writes flow through model tools. A `tools/pre-execute` waterfall listener returns `ask` for the seven write tools, so the registry asks the human through `ctx.approval` (the host logs the `approval/asked` + `approval/decided` audit pair) and fails closed without an answerer. Approval reasons preview what would be published (titles, body sizes, merge methods, and the first line of an overridden review body). Commands never write directly: command handlers run with no open turn, so the approval seam is structurally closed to them — a write command gathers read-only context, then wakes the agent (`followup` when idle, `inject` when busy) so the model runs the gated tool inside a turn.
-- **Background review.** `/review <pr>` starts a `github-review` job on `ctx.jobs` (label, owner, timeout, cancelable). The job resolves the token per operation, fetches the PR metadata (capturing the head-commit SHA for inline posting), the capped diff, and — unless disabled — CI check runs and existing review comments, then runs a deterministic multi-file analyzer (`src/review.ts`: hardcoded secrets, Google API keys, credential assignments, debug artifacts, eval, TODO markers, long lines, oversized changes) — zero tokens spent, fully testable. With `reviewMode: "model"`, the job instead hands the capped diff to a one-shot subagent through the host's `subagents` seam (the owning agent is the parent) and stores the child's Markdown output as the postable report; a missing seam or provider fails loud. Supplementary fetch failures are noted in the output without failing the job. Completion notices reach the initiating session through the host's `dsh-tool-jobs` consumer; the model reads the report via the existing `job_output` tool and publishes it with `review_post` — approval required.
-- **Model-visible ⇔ logged.** The plugin appends **no custom session event types**. Out-of-repo event types are not in the host's `KNOWN_SESSION_EVENT_TYPES`, so an unknown required event would make the session log unreadable after plugin removal (the host deliberately defers a registration surface for external plugins). All model-visible content therefore flows through host-logged surfaces: `tool/result` canonical values, `user/message` notices via `agent.inject`/`agent.followup`, the `command/run` + `command/done` lifecycle pair, and the `approval/asked` + `approval/decided` audit pair.
-- **Pure presenters.** `presentCall`/`presentResult` are pure functions of `args` (+ the persisted `result.meta`), identical on live streaming and log replay. PR creation shows a generic card with the PR URL.
+- **Permissions**: writes ride the official approval seam; nothing is re-implemented or bypassed. The plugin declares `network:outbound` and `filesystem:write` in its workshop manifest.
+- **Data**: the review report lives in process memory keyed by job id; nothing durable is written to disk.
+- **Session log**: the plugin adds no custom session event types; all model-visible content flows through host-logged surfaces (`tool/result`, `user/message`, `command/run`, `approval/asked`…).
 
-## 🔒 Security boundaries
+## Security boundaries
 
-- The token is read per operation from the configured source (credentials seam, environment, or `gh` CLI) and sent only in the REST client's Authorization header. It is never logged, never rendered, never injected, never appended to the session log, and never appears in error messages.
-- Every GitHub write requires `allowed-once` from `ctx.approval` (default policy `ask`); `rejected`, `cancelled`, and `unavailable` all fail closed.
-- `/pr create` never commits or pushes by itself; with `autoCommit: true` the model performs those writes through the bash tool's own approval gate. dsh-github does **not** manage git identity (dsh-git-identity's job) or worktrees (dsh-worktree's job).
-- The review job performs no writes: it reads a diff and stores a report in process memory; only `review_post` publishes, after approval.
-- Posted comments interpolate diff-derived file names, which are untrusted repository content: `formatPostBody` backtick-escapes and HTML-escapes file names so a hostile PR cannot inject Markdown into the review comment.
-- File contents read by `gh_file` and issue/PR bodies, comments, and search results read from GitHub are external untrusted content that enters model context — the same inherent tradeoff as web fetching; the plugin marks them as external content in its renders.
-- Rate limits: 429s are retried with backoff and the remaining quota is surfaced to the model on every result, including failures.
+- **Approval, not enforcement.** Writes only produce `ask`/deny decisions on the official seam; the sandbox and approval systems remain the enforcement authorities.
+- **Fail closed.** Missing approval answerer degrades to the strictest decision — never to silent pass-through.
+- **The token never leaves the process.** It is read per operation and sent only in the Authorization header; never logged, rendered, injected, or surfaced in errors.
+- **No writes outside approval.** `/pr create` never commits or pushes by itself; with `autoCommit: true`, the model performs those writes through the bash tool's own approval gate. The review job performs no writes; only `review_post` publishes, after approval.
+- **Untrusted content is escaped and marked.** `formatPostBody` backtick- and HTML-escapes diff-derived file names, and external GitHub content (files, bodies, comments, search results) is marked as external in renders.
+- **Bounded work and rate limits.** 429s are retried with backoff; the remaining quota is surfaced on every result, including failures.
 
-## ⚠️ Known limitations
+## Known limitations
 
 - **No custom session events** — deliberate (see Architecture); audit trails rely on the host's own event vocabulary.
-- **Static analyzer by default** — deterministic rules (`src/review.ts`), zero tokens, reproducible. `reviewMode: "model"` delegates the capped diff to a one-shot subagent through the host's `subagents` seam for an LLM review (costs tokens; requires the seam and a registered provider).
-- **Jobs and records are process-local** — the review report lives in plugin memory keyed by job id, matching the host job registry's lifetime; the record map is capped by `maxReviewRecords` (oldest settled records evict first).
-- **npm `latest` dist-tags are stale** — the plugin declares `^0.1.0-rc.5` peer ranges so it resolves against the profile closure that `dsh-base` provides, and pins `0.1.0-rc.6` for development. Never install by bare `npm i @deepseek-ai/dsh-tools`.
-- **CI / GitHub Action** — ships in this repository (v0.6.0): a composite action (`action.yml`) that reviews PRs, fixes CI, and writes the report; a polling review bot with idempotent inline comments; and a status-check gate. Every write stays approval-gated.
+- **Static analyzer by default** — deterministic rules (`src/review.ts`), zero tokens, reproducible. `reviewMode: "model"` costs tokens and requires the `subagents` seam and a registered provider.
+- **Jobs and records are process-local** — the review report lives in plugin memory keyed by job id; the record map is capped by `maxReviewRecords` (oldest settled records evict first).
+- **npm `latest` dist-tags are stale** — install through the profile closure `dsh-base` provides; never bare `npm i @deepseek-ai/dsh-tools`.
 
-## 🧪 Development
+## Development
 
 ```sh
-pnpm install
-pnpm test          # vitest: config, credentials, 429/retry, tools, commands, jobs, approval gate, token non-leakage
-pnpm typecheck
-pnpm build         # tsc → lib/ (noEmitOnError)
-pnpm pack          # installable tarball
+pnpm install             # node ^22.19 || >=24
+pnpm run build           # tsc --noEmitOnError → lib/
+pnpm run prepare         # self-contained git-install build (scripts/prepare.mjs)
+pnpm run prepublishOnly  # build + test before publishing
+pnpm test                # vitest run
+pnpm run typecheck       # tsc --noEmit
 pnpm run check:readmes   # cross-checks TOC anchors, tools, and config keys in all 5 READMEs
 ```
 
-Tests mock the GitHub API, the `gh` CLI, and git through injected runners — no network, no real credentials. `test/security.test.ts` asserts the token string never appears in any model- or human-visible output. `test/e2e.test.ts` contains opt-in real-API smoke tests that self-skip unless `DSH_GITHUB_E2E_TOKEN` is set (read-only endpoints only; the dedicated variable keeps the unit suite hermetic).
-
-## 🗂 Repository layout
+## Repository layout
 
 ```
 src/index.ts          plugin entry (name/inject/apply, applyWithDeps for tests)
@@ -262,15 +195,13 @@ cordis.patch.yml      bundle patch (one insert row)
 scripts/prepare.mjs   self-contained git-install build
 ```
 
-## 🏷 Topics
-
-Recommended GitHub repository topics (set them in the repo settings — they power the [`dsh-plugin` topic page](https://github.com/topics/dsh-plugin) and the DSH plugin marketplaces):
+## Topics
 
 `dsh` · `dsh-plugin` · `deepseek-harness` · `github` · `pull-request` · `code-review` · `issue-tracker`
 
-## License
+## Contributors
 
-[Apache License 2.0](LICENSE)
+- [@PerryLink](https://github.com/PerryLink) — creator and maintainer: the GitHub tool surface, approval gate, background review jobs, CI composite action, review bot, status-check gate, and the five-language docs.
 
 ## PerryLink DSH Plugin Family
 
@@ -293,3 +224,7 @@ This project is one of the [15 DeepSeek Harness plugins](https://github.com/Perr
 | **[dsh-github](https://github.com/PerryLink/dsh-github)** | GitHub PR/issues integration for DSH, every write gated by approval |
 | [dsh-plugin-guide](https://github.com/PerryLink/dsh-plugin-guide) | Plugin-development knowledge base as an on-demand agent skill |
 | [dsh-claude-move](https://github.com/PerryLink/dsh-claude-move) | Migrate Claude Code sessions, memory, skills and CLAUDE.md into DSH |
+
+## License
+
+[Apache License 2.0](LICENSE) © 2026 dsh-github contributors