Route GitHub mutations through ObjectType contracts

.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out plugin
+        uses: actions/checkout@v4
+        with:
+          path: plugin
+      - name: Check out current GodMode API
+        uses: actions/checkout@v4
+        with:
+          repository: ReBoticsAI/GodMode
+          ref: 732d993808d641645ed706d8560719cba5349d6f
+          path: GodMode
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: plugin/package-lock.json
+      - name: Build local kernel packages
+        working-directory: GodMode
+        run: |
+          npm ci
+          npm run build -w @godmode/kernel
+          npm run build -w @godmode/plugin-api
+      - name: Install plugin dependencies
+        working-directory: plugin
+        run: npm ci
+      - name: Validate migration
+        working-directory: plugin
+        run: npm run validate

README.md

@@ -1,31 +1,50 @@
 # GodMode GitHub plugin
 
-Official marketplace plugin: **GitHub** pull request and CI tools for Intelligence via the [`gh`](https://cli.github.com/) CLI.
+Official marketplace plugin: **GitHub** pull request and CI tools for Intelligence. Read tools call the [`gh`](https://cli.github.com/) CLI directly; mutations execute through versioned ObjectType kernel actions backed by `gh` adapters.
 
 ## Requirements
 
 - `gh` on the host PATH
 - Auth: `gh auth login` **or** `GITHUB_TOKEN` / `GH_TOKEN` in the environment (do not commit tokens)
 - Usually used with **godmode-plugin-git** for local commit/push
 
+## Architecture
+
+The manifest negotiates kernel client API version 1. At registration, the plugin installs two adapter-backed ObjectTypes:
+
+- `GitHubRepository`: `create_pull_request` and `create_issue`
+- `PullRequest`: `comment` and `merge`
+
+The four mutation tools call `api.kernel.runAction(...)`; they do not invoke `gh` directly. Their action contracts require confirmation and idempotency, declare timeouts and structured errors, and emit kernel events. If the kernel returns a confirmation grant, the tool wrapper replays the same action once with that grant and the same idempotency key.
+
+Repository paths are resolved inside the active coding root. In hub/client deployments, that root is tenant-scoped. Absolute or traversal escapes are rejected.
+
 ## Tools
 
-| Tool | Mode | Purpose |
-|------|------|---------|
-| `gh_pr_list` | auto | List PRs for the current repo |
-| `gh_pr_view` | auto | View one PR (JSON) |
-| `gh_pr_checks` | auto | CI check rollup for a PR |
-| `gh_pr_create` | confirm | Create a PR (title + body) |
-| `gh_pr_comment` | confirm | Comment on a PR |
-| `gh_pr_merge` | confirm | Merge when appropriate (default squash) |
-| `gh_issue_create` | confirm | Open a GitHub issue |
+| Tool | Mode | Execution and result |
+|------|------|----------------------|
+| `gh_pr_list` | auto | Direct read: lists PRs with `gh pr list`; defaults to open, limit 20 |
+| `gh_pr_view` | auto | Direct read: returns PR JSON from `gh pr view` |
+| `gh_pr_checks` | auto | Direct read: returns `ok`, exit `code`, text `checks`, and optional `stderr`; the PR number is optional |
+| `gh_pr_create` | confirm | `GitHubRepository.create_pull_request`; requires title and body |
+| `gh_pr_comment` | confirm | `PullRequest.comment`; requires PR number and body |
+| `gh_pr_merge` | confirm | `PullRequest.merge`; verifies open/non-draft/mergeable status and successful checks before merging |
+| `gh_issue_create` | confirm | `GitHubRepository.create_issue`; requires a title |
+
+All tools accept an optional `cwd` relative to the coding root. Mutation tools also accept an optional stable `idempotencyKey`; otherwise the active tool request ID is used.
+
+`gh_pr_merge` defaults to squash and branch deletion. Set `method` to `merge` or `rebase`, or set `deleteBranch: false`, to override those defaults.
 
 ## Safety
 
 - Does not store PATs in the plugin.
-- Prefer waiting for green `gh_pr_checks` before `gh_pr_merge`.
+- Use `gh_pr_checks` to inspect CI before requesting a merge. The merge action independently rejects closed or draft PRs, conflicts, unknown mergeability, and checks not reported as `SUCCESS`, `NEUTRAL`, or `SKIPPED`.
 - Never put secrets, ops passwords, or private family content in PR bodies.
 
+## Verification
+
+Run `npm run validate` to type-check source and tests, execute the ObjectType/adapter/tool contract tests, and build the bridge. The suite verifies kernel API negotiation, strict action contracts, mutation delegation, confirmation replay, coding-root isolation, safe argv handling, and merge-readiness enforcement.
+
 ## Install
 
 Marketplace → Official → **GitHub**, or Unofficial with this repo URL.

data/ai/skills/github-pr-workflow/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: github-pr-workflow
-description: Open and land GitHub PRs with gh plugin tools (create, checks, merge)
+description: Open and land GitHub PRs with kernel-backed mutations and gh read tools
 tools: ["gh_pr_list", "gh_pr_view", "gh_pr_checks", "gh_pr_create", "gh_pr_comment", "gh_pr_merge", "gh_issue_create", "git_status", "git_push"]
 ---
 
 1. Ensure the branch is pushed (`git_push` from godmode-plugin-git).
-2. `gh_pr_create` with:
+2. Call `gh_pr_create` with:
    - Title: concise why
    - Body:
      ```
@@ -15,7 +15,13 @@ tools: ["gh_pr_list", "gh_pr_view", "gh_pr_checks", "gh_pr_create", "gh_pr_comme
      ## Test plan
      - [ ] …
      ```
-3. Share the returned PR URL with the user.
-4. Poll `gh_pr_checks` until green (or report failures). Avoid tight busy-loops — wait between checks.
-5. Only when the user asks to land it: `gh_pr_merge` (squash by default).
-6. Keep secrets and private ops out of the PR.
+   - Optional `base`, `draft`, and stable `idempotencyKey`
+   - Optional `cwd` relative to the active coding root
+3. Share the returned PR URL with the user. `gh_pr_create` delegates to the `GitHubRepository.create_pull_request` kernel action.
+4. Use `gh_pr_checks` for a CI snapshot. It returns `ok`, exit `code`, text `checks`, and optional `stderr`; rerun only after waiting when checks are pending.
+5. Only when the user asks to land it, call `gh_pr_merge`. It delegates to `PullRequest.merge`, which independently requires an open, non-draft, mergeable PR whose checks are `SUCCESS`, `NEUTRAL`, or `SKIPPED`.
+   - Merge defaults: squash and delete the branch
+   - Override with `method: "merge" | "rebase"` or `deleteBranch: false`
+6. Treat `gh_pr_create`, `gh_pr_comment`, `gh_pr_merge`, and `gh_issue_create` as confirmed kernel mutations. Their wrappers preserve the idempotency key and replay once when the kernel supplies a confirmation grant.
+7. `gh_pr_list`, `gh_pr_view`, and `gh_pr_checks` are read-only direct `gh` calls; they do not run ObjectType actions.
+8. Keep secrets and private ops out of PRs, comments, and issues.

godmode.plugin.json

@@ -3,5 +3,6 @@
   "version": "0.1.0",
   "name": "GitHub",
   "engine": "^0.1.0",
+  "kernelApiVersion": 1,
   "bridge": { "entry": "dist/bridge.js" }
 }