@ikon85/agent-workflow-kit 0.11.0 → 0.13.0

package/.agents/skills/kit-update/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: kit-update
+description: "Preview and transactionally apply a parity-verified agent-workflow-kit release without overwriting local modifications or auto-resolving conflicts."
+---
+
+# Kit Update
+
+Update an installed consumer only from the public scoped package
+`@ikon85/agent-workflow-kit`. The unscoped `agent-workflow-kit` package belongs
+to another publisher and is never a valid update source. Existing installs from
+`npx github:iKon85/agent-workflow-kit` remain valid, but updates must use the
+scoped npm release so the shared release-parity checker can prove that npm and
+the matching GitHub release contain the same artifact.
+
+## Workflow
+
+1. Preview the delta without writing:
+
+   ```sh
+   npx @ikon85/agent-workflow-kit@latest diff
+   ```
+
+   Review the named added, updated, locally modified, removed, and conflicting
+   paths. Do not reinterpret a local modification as permission to overwrite it.
+
+2. Apply the update:
+
+   ```sh
+   npx @ikon85/agent-workflow-kit@latest update
+   ```
+
+   The command checks npm/GitHub release parity before staging. It prepares a
+   complete candidate outside the consumer, runs the consumer's existing
+   `npm test` command there, and activates only a verified candidate. A staging
+   or verification failure leaves the installed tree byte-identical.
+
+3. Read the terminal report. `aktuell` proves a second run found no upstream
+   delta. A conflict report names and counts every category and leaves every
+   consumer file untouched. Follow its recommendation and resolve each named
+   conflict manually; never auto-merge, delete a local edit, or silently choose
+   the incoming copy.
+
+4. If a candidate is interrupted, discard its reported stage directory or
+   resume the transaction through the update API's `resumeFrom` option. Do not
+   copy staged files into the consumer by hand.
+
+## State contract
+
+The update API reports `checking -> preview/awaiting_decision -> staging ->
+verifying -> applied | conflicted | failed | aborted`. `conflicted`, `failed`,
+and `aborted` never authorize partial activation. The existing manifest,
+three-way diff, and atomic-write seams remain the source of truth.

package/.agents/skills/setup-workflow/SKILL.md

@@ -24,6 +24,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `docs/agents/code-review.md` | Standards-source pointers + adjacent-review-tooling notes the `code-review` skill's Standards axis reads (Section I) |
 | `## Workflow` in CLAUDE.md **and** AGENTS.md | generic entry-point map seeded from [workflow-overview.md](./workflow-overview.md) (Section F + Write) |
 | `## Agent skills` + `## Prod` in CLAUDE.md **and** AGENTS.md | one-line pointers + deploy target (Sections C/G + Write) |
+| `.github/workflows/agent-workflow-kit-update.yml` | optional tested Kit update pull request for GitHub consumers (Section A2) |
 
 ## Idempotency contract — read before writing anything
 
@@ -68,6 +69,40 @@ Default posture: these skills were designed for GitHub. If a `git remote` points
 
 Seed `docs/agents/issue-tracker.md` from the matching template in this folder: [issue-tracker-github.md](./issue-tracker-github.md), [issue-tracker-gitlab.md](./issue-tracker-gitlab.md), [issue-tracker-local.md](./issue-tracker-local.md). For "other", write it from the user's description.
 
+### 2a. Automatic Kit update pull requests (GitHub tracker only)
+
+> A short scheduled check can keep the installed Kit current by opening one normal pull request after the candidate passes the consumer's own tests. It never merges the pull request for you.
+
+Only after the user has confirmed a **GitHub tracker**, ask in plain language: *"Should GitHub check weekly for a tested Agent Workflow Kit update and keep one update pull request ready?"* Offer these explicit choices:
+
+Before offering **Enable**, confirm the consumer has a committed `package-lock.json` and a usable `package.json` `npm test` command. The shipped workflow installs the locked dependencies with `npm ci --ignore-scripts`; without that lockfile/test contract it cannot prove the candidate in a clean checkout, so explain the prerequisite and do not create the workflow yet.
+
+Also read the repository Actions policy before enabling:
+
+```bash
+gh api repos/<owner>/<repo>/actions/permissions/workflow
+```
+
+The response must report `"can_approve_pull_request_reviews": true`; this is GitHub's **Allow GitHub Actions to create and approve pull requests** gate used by the stable PR upsert. If it is false, or the policy cannot be read, do not seed the workflow yet. Guide the user to **Settings → Actions → General → Workflow permissions**, enable that checkbox, and rerun `setup-workflow`.
+
+If the user prefers `gh`, first show the exact mutation and obtain **explicit confirmation**; never change repository settings merely because setup was invoked. After confirmation, preserve the currently reported `default_workflow_permissions` value (`read` or `write`) and set the gate with:
+
+```bash
+gh api --method PUT repos/<owner>/<repo>/actions/permissions/workflow \
+  -f default_workflow_permissions=<current-read-or-write> \
+  -F can_approve_pull_request_reviews=true
+```
+
+Read the policy back and offer **Enable** only after the field is actually true.
+
+- **Enable** — seed `.github/workflows/agent-workflow-kit-update.yml` from [assets/agent-workflow-kit-update.yml](./assets/agent-workflow-kit-update.yml).
+- **Opt out** — do not create a GitHub workflow, branch, or pull request.
+- **Ask later** — do not create a GitHub workflow, branch, or pull request; explain that re-running `setup-workflow` can offer it again.
+
+This workflow opt-in has its own file-level idempotency rule: if the destination is already present, leave it byte-for-byte unchanged and report `skipped (already present)`. On repeated setup runs, do not prompt again when it exists. The workflow consumes the scoped `@ikon85/agent-workflow-kit` release and its existing parity-checked transactional update command; do not reproduce either mechanism in setup prose or shell steps.
+
+For GitLab, local, other, or an unknown provider, give only a provider-neutral explanation that automatic updates require provider-specific CI and pull-request support; **do not create a GitHub workflow**. Setup itself never creates the update branch or pull request — only an opted-in workflow run may do that later.
+
 **Conditional board-write note (only when the GitHub tracker uses a managed board):** if Section D ends with `board-sync.md` at `mode: github-projects-v2`, add one line to `issue-tracker.md`: *"Board writes (item-add, status/wave/cluster field edits, sub-issue links) go through the board-sync helper, not bare `gh issue create`/`gh project item-*`."* Do **not** add this for GitLab, local, other, or `mode: none`.
 
 ### 3. Section B — Triage labels

package/.agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml

@@ -0,0 +1,31 @@
+name: Agent Workflow Kit update
+
+on:
+  schedule:
+    - cron: '17 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: agent-workflow-kit-update
+  cancel-in-progress: false
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.14
+      - name: Install locked consumer dependencies
+        run: npm ci --ignore-scripts
+      - name: Verify, test, and upsert the Kit update pull request
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: npx --yes --package=@ikon85/agent-workflow-kit@latest agent-workflow-kit-update-pr

package/.agents/skills/setup-workflow/workflow-overview.md

@@ -19,6 +19,7 @@ Use this section as the entry-point map for agent-assisted work. The individual
 - **Implementation slice:** use `tdd` for one behavior at a time: RED, GREEN, then refactor.
 - **Finished slice:** use `wrapup` to prepare the branch, PR, and cleanup steps your repo expects.
 - **Kit release:** use `kit-release` to derive the shipped delta, confirm Semver, regenerate the manifest, run all gates, and then hand landing to `wrapup`.
+- **Kit update:** use `kit-update` to preview and transactionally apply a parity-verified scoped release without overwriting local modifications.
 - **A huge, foggy effort, too big for one session:** use `wayfinder` — it charts it as a shared map of investigation tickets, resolving one per session.
 
 ## Routing Rule

package/.claude/skills/kit-update/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: kit-update
+description: "Preview and transactionally apply a parity-verified agent-workflow-kit release without overwriting local modifications or auto-resolving conflicts."
+---
+
+# Kit Update
+
+Update an installed consumer only from the public scoped package
+`@ikon85/agent-workflow-kit`. The unscoped `agent-workflow-kit` package belongs
+to another publisher and is never a valid update source. Existing installs from
+`npx github:iKon85/agent-workflow-kit` remain valid, but updates must use the
+scoped npm release so the shared release-parity checker can prove that npm and
+the matching GitHub release contain the same artifact.
+
+## Workflow
+
+1. Preview the delta without writing:
+
+   ```sh
+   npx @ikon85/agent-workflow-kit@latest diff
+   ```
+
+   Review the named added, updated, locally modified, removed, and conflicting
+   paths. Do not reinterpret a local modification as permission to overwrite it.
+
+2. Apply the update:
+
+   ```sh
+   npx @ikon85/agent-workflow-kit@latest update
+   ```
+
+   The command checks npm/GitHub release parity before staging. It prepares a
+   complete candidate outside the consumer, runs the consumer's existing
+   `npm test` command there, and activates only a verified candidate. A staging
+   or verification failure leaves the installed tree byte-identical.
+
+3. Read the terminal report. `aktuell` proves a second run found no upstream
+   delta. A conflict report names and counts every category and leaves every
+   consumer file untouched. Follow its recommendation and resolve each named
+   conflict manually; never auto-merge, delete a local edit, or silently choose
+   the incoming copy.
+
+4. If a candidate is interrupted, discard its reported stage directory or
+   resume the transaction through the update API's `resumeFrom` option. Do not
+   copy staged files into the consumer by hand.
+
+## State contract
+
+The update API reports `checking -> preview/awaiting_decision -> staging ->
+verifying -> applied | conflicted | failed | aborted`. `conflicted`, `failed`,
+and `aborted` never authorize partial activation. The existing manifest,
+three-way diff, and atomic-write seams remain the source of truth.

package/.claude/skills/setup-workflow/SKILL.md

@@ -24,6 +24,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `docs/agents/code-review.md` | Standards-source pointers + adjacent-review-tooling notes the `code-review` skill's Standards axis reads (Section I) |
 | `## Workflow` in CLAUDE.md **and** AGENTS.md | generic entry-point map seeded from [workflow-overview.md](./workflow-overview.md) (Section F + Write) |
 | `## Agent skills` + `## Prod` in CLAUDE.md **and** AGENTS.md | one-line pointers + deploy target (Sections C/G + Write) |
+| `.github/workflows/agent-workflow-kit-update.yml` | optional tested Kit update pull request for GitHub consumers (Section A2) |
 
 ## Idempotency contract — read before writing anything
 
@@ -68,6 +69,40 @@ Default posture: these skills were designed for GitHub. If a `git remote` points
 
 Seed `docs/agents/issue-tracker.md` from the matching template in this folder: [issue-tracker-github.md](./issue-tracker-github.md), [issue-tracker-gitlab.md](./issue-tracker-gitlab.md), [issue-tracker-local.md](./issue-tracker-local.md). For "other", write it from the user's description.
 
+### 2a. Automatic Kit update pull requests (GitHub tracker only)
+
+> A short scheduled check can keep the installed Kit current by opening one normal pull request after the candidate passes the consumer's own tests. It never merges the pull request for you.
+
+Only after the user has confirmed a **GitHub tracker**, ask in plain language: *"Should GitHub check weekly for a tested Agent Workflow Kit update and keep one update pull request ready?"* Offer these explicit choices:
+
+Before offering **Enable**, confirm the consumer has a committed `package-lock.json` and a usable `package.json` `npm test` command. The shipped workflow installs the locked dependencies with `npm ci --ignore-scripts`; without that lockfile/test contract it cannot prove the candidate in a clean checkout, so explain the prerequisite and do not create the workflow yet.
+
+Also read the repository Actions policy before enabling:
+
+```bash
+gh api repos/<owner>/<repo>/actions/permissions/workflow
+```
+
+The response must report `"can_approve_pull_request_reviews": true`; this is GitHub's **Allow GitHub Actions to create and approve pull requests** gate used by the stable PR upsert. If it is false, or the policy cannot be read, do not seed the workflow yet. Guide the user to **Settings → Actions → General → Workflow permissions**, enable that checkbox, and rerun `setup-workflow`.
+
+If the user prefers `gh`, first show the exact mutation and obtain **explicit confirmation**; never change repository settings merely because setup was invoked. After confirmation, preserve the currently reported `default_workflow_permissions` value (`read` or `write`) and set the gate with:
+
+```bash
+gh api --method PUT repos/<owner>/<repo>/actions/permissions/workflow \
+  -f default_workflow_permissions=<current-read-or-write> \
+  -F can_approve_pull_request_reviews=true
+```
+
+Read the policy back and offer **Enable** only after the field is actually true.
+
+- **Enable** — seed `.github/workflows/agent-workflow-kit-update.yml` from [assets/agent-workflow-kit-update.yml](./assets/agent-workflow-kit-update.yml).
+- **Opt out** — do not create a GitHub workflow, branch, or pull request.
+- **Ask later** — do not create a GitHub workflow, branch, or pull request; explain that re-running `setup-workflow` can offer it again.
+
+This workflow opt-in has its own file-level idempotency rule: if the destination is already present, leave it byte-for-byte unchanged and report `skipped (already present)`. On repeated setup runs, do not prompt again when it exists. The workflow consumes the scoped `@ikon85/agent-workflow-kit` release and its existing parity-checked transactional update command; do not reproduce either mechanism in setup prose or shell steps.
+
+For GitLab, local, other, or an unknown provider, give only a provider-neutral explanation that automatic updates require provider-specific CI and pull-request support; **do not create a GitHub workflow**. Setup itself never creates the update branch or pull request — only an opted-in workflow run may do that later.
+
 **Conditional board-write note (only when the GitHub tracker uses a managed board):** if Section D ends with `board-sync.md` at `mode: github-projects-v2`, add one line to `issue-tracker.md`: *"Board writes (item-add, status/wave/cluster field edits, sub-issue links) go through the board-sync helper, not bare `gh issue create`/`gh project item-*`."* Do **not** add this for GitLab, local, other, or `mode: none`.
 
 ### 3. Section B — Triage labels

package/.claude/skills/setup-workflow/assets/agent-workflow-kit-update.yml

@@ -0,0 +1,31 @@
+name: Agent Workflow Kit update
+
+on:
+  schedule:
+    - cron: '17 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: agent-workflow-kit-update
+  cancel-in-progress: false
+
+jobs:
+  update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.14
+      - name: Install locked consumer dependencies
+        run: npm ci --ignore-scripts
+      - name: Verify, test, and upsert the Kit update pull request
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: npx --yes --package=@ikon85/agent-workflow-kit@latest agent-workflow-kit-update-pr

package/.claude/skills/setup-workflow/workflow-overview.md

@@ -19,6 +19,7 @@ Use this section as the entry-point map for agent-assisted work. The individual
 - **Implementation slice:** use `tdd` for one behavior at a time: RED, GREEN, then refactor.
 - **Finished slice:** use `wrapup` to prepare the branch, PR, and cleanup steps your repo expects.
 - **Kit release:** use `kit-release` to derive the shipped delta, confirm Semver, regenerate the manifest, run all gates, and then hand landing to `wrapup`.
+- **Kit update:** use `kit-update` to preview and transactionally apply a parity-verified scoped release without overwriting local modifications.
 - **A huge, foggy effort, too big for one session:** use `wayfinder` — it charts it as a shared map of investigation tickets, resolving one per session.
 
 ## Routing Rule

package/.claude/skills/skill-manifest.json

@@ -384,6 +384,16 @@
         "codex"
       ],
       "provenance": "own"
+    },
+    "kit-update": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
     }
   }
 }

package/README.md

@@ -332,6 +332,21 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.13.0
+
+- added: `.agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml`
+- added: `.claude/skills/setup-workflow/assets/agent-workflow-kit-update.yml`
+- added: `scripts/kit-update-pr.mjs`
+- changed: `.agents/skills/setup-workflow/SKILL.md`
+- changed: `.claude/skills/setup-workflow/SKILL.md`
+
+### 0.12.0
+
+- added: `.agents/skills/kit-update/SKILL.md`
+- added: `.claude/skills/kit-update/SKILL.md`
+- changed: `.agents/skills/setup-workflow/workflow-overview.md`
+- changed: `.claude/skills/setup-workflow/workflow-overview.md`
+
 ### 0.11.0
 
 - added: `scripts/release-parity.mjs`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.11.0",
+  "kitVersion": "0.13.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -325,6 +325,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".agents/skills/kit-update/SKILL.md",
+      "kind": "skill",
+      "ownerSkill": "kit-update",
+      "surface": "codex",
+      "sha256": "26737ea49ac104260e56fd1604f60249ca1d59f1a2c1f22db55649833d01ebc3",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".agents/skills/local-ci/SKILL.md",
       "kind": "skill",
@@ -451,6 +460,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml",
+      "kind": "skill",
+      "ownerSkill": "setup-workflow",
+      "surface": "codex",
+      "sha256": "d8abf995d67184b4459b9565c9062319fc42e8a685042b288b3066a07a6fda59",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".agents/skills/setup-workflow/board-sync.md",
       "kind": "skill",
@@ -519,7 +537,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "ea0b75ccd1579820a09e7c8d4c151126aa0be7a0be6b76b23599fadebb44b554",
+      "sha256": "efc7818d98158a85a79f3a652787d2e557552fa5175b32b24916c894388b9b74",
       "mode": 420,
       "origin": "kit"
     },
@@ -564,7 +582,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "87e5ab578f1c17905b39b9cb39b515e4661f3437d96de919f1b23a5775760c4f",
+      "sha256": "6ce3954e4f94d112801cba0d145e4d3b6f101aca5e50e6b1f9794aa0288881a9",
       "mode": 420,
       "origin": "kit"
     },
@@ -1271,6 +1289,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/skills/kit-update/SKILL.md",
+      "kind": "skill",
+      "ownerSkill": "kit-update",
+      "surface": "claude",
+      "sha256": "26737ea49ac104260e56fd1604f60249ca1d59f1a2c1f22db55649833d01ebc3",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/local-ci/SKILL.md",
       "kind": "skill",
@@ -1415,6 +1442,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/skills/setup-workflow/assets/agent-workflow-kit-update.yml",
+      "kind": "skill",
+      "ownerSkill": "setup-workflow",
+      "surface": "claude",
+      "sha256": "d8abf995d67184b4459b9565c9062319fc42e8a685042b288b3066a07a6fda59",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/setup-workflow/board-sync.md",
       "kind": "skill",
@@ -1483,7 +1519,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "ea0b75ccd1579820a09e7c8d4c151126aa0be7a0be6b76b23599fadebb44b554",
+      "sha256": "efc7818d98158a85a79f3a652787d2e557552fa5175b32b24916c894388b9b74",
       "mode": 420,
       "origin": "kit"
     },
@@ -1528,7 +1564,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "87e5ab578f1c17905b39b9cb39b515e4661f3437d96de919f1b23a5775760c4f",
+      "sha256": "6ce3954e4f94d112801cba0d145e4d3b6f101aca5e50e6b1f9794aa0288881a9",
       "mode": 420,
       "origin": "kit"
     },
@@ -1865,6 +1901,13 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": "scripts/kit-update-pr.mjs",
+      "kind": "script",
+      "sha256": "64e7818003d7c6db227eadad0b114e199399a52a96965ab2f0f496c0a1e5c79c",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": "scripts/loc_offender_core.py",
       "kind": "script",

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {
-    "agent-workflow-kit": "src/cli.mjs"
+    "agent-workflow-kit": "src/cli.mjs",
+    "agent-workflow-kit-update-pr": "scripts/kit-update-pr.mjs"
   },
   "scripts": {
     "test": "npm run test:node && npm run test:python",

package/scripts/build-kit.test.mjs

@@ -37,6 +37,9 @@ test('current build contains post-tag public files and repository metadata', asy
     const pkg = JSON.parse(await readFile(join(dist, 'package.json'), 'utf8'));
     assert.equal(pkg.name, '@ikon85/agent-workflow-kit');
     assert.equal(pkg.repository.url, 'git+https://github.com/iKon85/agent-workflow-kit.git');
+    assert.equal(pkg.bin['agent-workflow-kit'], 'src/cli.mjs');
+    assert.equal(pkg.bin['agent-workflow-kit-update-pr'], 'scripts/kit-update-pr.mjs');
+    await readFile(join(dist, 'scripts/kit-update-pr.mjs'));
   });
 });
 
@@ -52,9 +55,31 @@ test('npm pack keeps the complete scripts tree but excludes Python caches', () =
   const files = JSON.parse(output)[0].files.map((file) => file.path);
   assert.ok(files.includes('scripts/build-kit.mjs'));
   assert.ok(files.includes('scripts/board-sync.py'));
+  assert.ok(files.includes('scripts/kit-update-pr.mjs'));
   assert.ok(files.every((path) => !path.includes('__pycache__') && !path.endsWith('.pyc')));
   const pkg = JSON.parse(execFileSync('node', ['-p', 'JSON.stringify(require("./package.json"))'], {
     cwd: REPO, encoding: 'utf8',
   }));
   assert.ok(pkg.files.includes('scripts/'), 'package must ship future script file types');
 });
+
+test('packed scoped artifact keeps the existing npx default-bin inference', async () => {
+  const destination = await mkdtemp(join(tmpdir(), 'awkit-pack-'));
+  try {
+    const packed = JSON.parse(execFileSync('npm', [
+      'pack', '--pack-destination', destination, '--json',
+    ], { cwd: REPO, encoding: 'utf8' }));
+    const output = execFileSync('npx', [
+      '--yes', '--offline', `./${packed[0].filename}`,
+    ], { cwd: destination, encoding: 'utf8' });
+    assert.match(output, /Usage: agent-workflow-kit/);
+
+    const updater = execFileSync('npm', [
+      'exec', '--yes', '--offline', `--package=./${packed[0].filename}`,
+      '--', 'agent-workflow-kit-update-pr', 'help',
+    ], { cwd: destination, encoding: 'utf8' });
+    assert.match(updater, /Usage: agent-workflow-kit-update-pr/);
+  } finally {
+    await rm(destination, { recursive: true, force: true });
+  }
+});

package/scripts/kit-update-pr.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+import { execFile } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { appendFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+export const UPDATE_BRANCH = 'agent-workflow-kit/update';
+export const UPDATE_TITLE = 'chore: update agent workflow kit';
+const UPDATE_BODY = [
+  'Automated, parity-verified update of `@ikon85/agent-workflow-kit`.',
+  '',
+  'The transactional update candidate passed the consumer test suite before this branch was published.',
+  '',
+  'This pull request is never merged automatically.',
+].join('\n');
+const exec = promisify(execFile);
+
+export async function orchestrateUpdatePullRequest(options) {
+  const {
+    runUpdate, hasChanges, listPullRequests, publishBranch,
+    createPullRequest, updatePullRequest, branch = UPDATE_BRANCH,
+  } = options;
+  const update = await runUpdate();
+  if (update.exitCode !== 0) {
+    return { status: update.exitCode === 2 ? 'conflicted' : 'failed', branch, update };
+  }
+  if (!await hasChanges()) return { status: 'current', branch };
+
+  const pulls = await listPullRequests(branch);
+  if (pulls.length > 1) {
+    return { status: 'failed', branch, reason: 'multiple-open-pull-requests' };
+  }
+  await publishBranch(branch);
+  const input = { title: UPDATE_TITLE, body: UPDATE_BODY, branch };
+  if (pulls.length === 1) {
+    await updatePullRequest(pulls[0].number, input);
+    return { status: 'updated', branch, pullRequest: pulls[0].number };
+  }
+  await createPullRequest(input);
+  return { status: 'created', branch };
+}
+
+export function createSystemAdapters({
+  cwd = process.cwd(), env = process.env, execute = exec,
+} = {}) {
+  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+  const command = async (file, args) => {
+    try {
+      const result = await execute(file, args, { cwd, env, encoding: 'utf8' });
+      return { exitCode: 0, stdout: result.stdout, stderr: result.stderr };
+    } catch (error) {
+      if (typeof error.code !== 'number') throw error;
+      return { exitCode: error.code, stdout: error.stdout || '', stderr: error.stderr || '' };
+    }
+  };
+  const checked = async (file, args) => {
+    const result = await command(file, args);
+    if (result.exitCode !== 0) throw new Error(result.stderr || `${file} exited ${result.exitCode}`);
+    return result.stdout.trim();
+  };
+
+  return {
+    runUpdate: () => command(process.execPath, [join(packageRoot, 'src/cli.mjs'), 'update', '--yes']),
+    hasChanges: async () => Boolean(await checked('git', ['status', '--porcelain', '--untracked-files=all'])),
+    listPullRequests: async (branch) => JSON.parse(await checked('gh', [
+      'pr', 'list', '--state', 'open', '--head', branch, '--json', 'number,url',
+    ]) || '[]'),
+    publishBranch: async (branch) => {
+      await checked('git', ['config', 'user.name', 'agent-workflow-kit[bot]']);
+      await checked('git', ['config', 'user.email', 'agent-workflow-kit[bot]@users.noreply.github.com']);
+      await checked('git', ['add', '--all']);
+      await checked('git', ['commit', '-m', UPDATE_TITLE]);
+      const remote = await checked('git', ['ls-remote', 'origin', `refs/heads/${branch}`]);
+      const expected = remote.split(/\s+/)[0] || '';
+      await checked('git', [
+        'push', `--force-with-lease=refs/heads/${branch}:${expected}`,
+        'origin', `HEAD:refs/heads/${branch}`,
+      ]);
+    },
+    createPullRequest: ({ title, body, branch }) => checked('gh', [
+      'pr', 'create', '--head', branch, '--title', title, '--body', body,
+    ]),
+    updatePullRequest: (number, { title, body }) => checked('gh', [
+      'pr', 'edit', String(number), '--title', title, '--body', body,
+    ]),
+  };
+}
+
+export async function runCli(options = {}) {
+  let report;
+  try {
+    report = await orchestrateUpdatePullRequest(createSystemAdapters(options));
+  } catch (error) {
+    report = { status: 'failed', branch: UPDATE_BRANCH, reason: error.message };
+  }
+  const rendered = `${JSON.stringify(report, null, 2)}\n`;
+  process.stdout.write(rendered);
+  if (process.env.GITHUB_STEP_SUMMARY) {
+    await appendFile(process.env.GITHUB_STEP_SUMMARY, `## Agent Workflow Kit update\n\n\`\`\`json\n${rendered}\`\`\`\n`);
+  }
+  if (report.status === 'conflicted') process.exitCode = 2;
+  else if (report.status === 'failed') process.exitCode = 1;
+  return report;
+}
+
+const invokedPath = process.argv[1] ? realpathSync(process.argv[1]) : '';
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  if (process.argv.includes('--help') || process.argv.includes('-h') || process.argv.includes('help')) {
+    process.stdout.write('Usage: agent-workflow-kit-update-pr\n');
+  } else {
+    await runCli();
+  }
+}

package/scripts/kit-update-pr.test.mjs

@@ -0,0 +1,99 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createSystemAdapters, orchestrateUpdatePullRequest } from './kit-update-pr.mjs';
+
+function harness({ update = { exitCode: 0 }, changed = true, pulls = [] } = {}) {
+  const calls = [];
+  return {
+    calls,
+    options: {
+      runUpdate: async () => (calls.push('update'), update),
+      hasChanges: async () => (calls.push('changes'), changed),
+      listPullRequests: async (branch) => (calls.push(['list', branch]), pulls),
+      publishBranch: async (branch) => calls.push(['publish', branch]),
+      createPullRequest: async (input) => calls.push(['create', input]),
+      updatePullRequest: async (number, input) => calls.push(['upsert', number, input]),
+    },
+  };
+}
+
+test('a successful update creates one stable update pull request', async () => {
+  const h = harness();
+  const report = await orchestrateUpdatePullRequest(h.options);
+
+  assert.equal(report.status, 'created');
+  assert.equal(report.branch, 'agent-workflow-kit/update');
+  assert.deepEqual(h.calls.map((call) => Array.isArray(call) ? call[0] : call), [
+    'update', 'changes', 'list', 'publish', 'create',
+  ]);
+});
+
+test('a conflict produces a structured report without touching the stable branch', async () => {
+  const h = harness({ update: { exitCode: 2, stdout: 'conflicts: 1', stderr: '' } });
+  const report = await orchestrateUpdatePullRequest(h.options);
+
+  assert.deepEqual(report, {
+    status: 'conflicted',
+    branch: 'agent-workflow-kit/update',
+    update: { exitCode: 2, stdout: 'conflicts: 1', stderr: '' },
+  });
+  assert.deepEqual(h.calls, ['update']);
+});
+
+test('a release mismatch fails without touching the consumer update branch', async () => {
+  const h = harness({ update: { exitCode: 1, stdout: '', stderr: 'release mismatch' } });
+  const report = await orchestrateUpdatePullRequest(h.options);
+
+  assert.equal(report.status, 'failed');
+  assert.equal(report.update.stderr, 'release mismatch');
+  assert.deepEqual(h.calls, ['update']);
+});
+
+test('ambiguous existing pull requests fail before the last good branch is changed', async () => {
+  const h = harness({ pulls: [{ number: 7 }, { number: 9 }] });
+  const report = await orchestrateUpdatePullRequest(h.options);
+
+  assert.equal(report.status, 'failed');
+  assert.equal(report.reason, 'multiple-open-pull-requests');
+  assert.deepEqual(h.calls.map((call) => Array.isArray(call) ? call[0] : call), [
+    'update', 'changes', 'list',
+  ]);
+});
+
+test('an already current consumer is a no-op', async () => {
+  const h = harness({ changed: false });
+  const report = await orchestrateUpdatePullRequest(h.options);
+
+  assert.equal(report.status, 'current');
+  assert.deepEqual(h.calls, ['update', 'changes']);
+});
+
+test('a repeated run updates the one existing stable pull request', async () => {
+  const h = harness({ pulls: [{ number: 7 }] });
+  const report = await orchestrateUpdatePullRequest(h.options);
+
+  assert.equal(report.status, 'updated');
+  assert.equal(report.pullRequest, 7);
+  assert.deepEqual(h.calls.map((call) => Array.isArray(call) ? call[0] : call), [
+    'update', 'changes', 'list', 'publish', 'upsert',
+  ]);
+});
+
+test('publishing commits in place and lease-protects the stable remote branch', async () => {
+  const commands = [];
+  const execute = async (file, args) => {
+    commands.push([file, ...args]);
+    if (args[0] === 'ls-remote') return { stdout: 'abc123\trefs/heads/agent-workflow-kit/update\n', stderr: '' };
+    return { stdout: '', stderr: '' };
+  };
+  const adapter = createSystemAdapters({ cwd: '/consumer', env: {}, execute });
+
+  await adapter.publishBranch('agent-workflow-kit/update');
+
+  const gitCommands = commands.map((command) => command.slice(1));
+  assert.equal(gitCommands.some(([verb]) => ['switch', 'checkout', 'reset'].includes(verb)), false);
+  assert.deepEqual(gitCommands.at(-1), [
+    'push', '--force-with-lease=refs/heads/agent-workflow-kit/update:abc123',
+    'origin', 'HEAD:refs/heads/agent-workflow-kit/update',
+  ]);
+});

package/scripts/test_skill_setup_workflow_seeds.py

@@ -45,6 +45,16 @@ def classify(first_line, is_empty):
     return "create" if is_empty else "skip"
 
 
+def update_workflow_action(
+    provider, choice, destination_exists, prerequisites=True,
+    pull_requests_allowed=True,
+):
+    """Reference decision table for the prompt-driven setup contract."""
+    if provider != "github" or destination_exists or choice != "enable":
+        return "skip"
+    return "create" if prerequisites and pull_requests_allowed else "skip"
+
+
 class IdempotencyRule(unittest.TestCase):
     CASES = [
         # (first_line, is_empty, expected)
@@ -71,6 +81,61 @@ class IdempotencyRule(unittest.TestCase):
 
 
 class SeedTemplatesValid(unittest.TestCase):
+    def test_update_workflow_provider_and_choice_fixtures(self):
+        fixtures = [
+            ("github", "enable", False, True, True, "create"),
+            ("github", "opt-out", False, True, True, "skip"),
+            ("github", "later", False, True, True, "skip"),
+            ("github", "enable", True, True, True, "skip"),
+            ("github", "enable", False, False, True, "skip"),
+            ("github", "enable", False, True, False, "skip"),
+            ("gitlab", "enable", False, True, True, "skip"),
+            ("local", "enable", False, True, True, "skip"),
+        ]
+        for provider, choice, exists, prerequisites, allowed, expected in fixtures:
+            self.assertEqual(
+                update_workflow_action(
+                    provider, choice, exists, prerequisites, allowed,
+                ), expected,
+            )
+
+    def test_github_update_opt_in_is_provider_aware_and_idempotent(self):
+        skill = (SKILL / "SKILL.md").read_text(encoding="utf-8")
+        for token in (
+            "Automatic Kit update pull requests",
+            ".github/workflows/agent-workflow-kit-update.yml",
+            "Opt out",
+            "Ask later",
+            "GitHub tracker",
+            "skipped (already present)",
+            "package-lock.json",
+            "npm test",
+            "can_approve_pull_request_reviews",
+            "Allow GitHub Actions to create and approve pull requests",
+            "explicit confirmation",
+        ):
+            self.assertIn(token, skill)
+        self.assertIn("do not create a GitHub workflow", skill)
+
+    def test_github_update_workflow_has_safe_triggers_and_scoped_runner(self):
+        workflow = (SKILL / "assets/agent-workflow-kit-update.yml").read_text(encoding="utf-8")
+        for token in (
+            "schedule:", "workflow_dispatch:", "contents: write",
+            "pull-requests: write", "agent-workflow-kit-update-pr",
+            "@ikon85/agent-workflow-kit@latest", "fetch-depth: 0",
+            "node-version: 22.14", "npm ci --ignore-scripts",
+        ):
+            self.assertIn(token, workflow)
+        for forbidden in ("npm_token", "NPM_TOKEN", "auto-merge", "gh pr merge"):
+            self.assertNotIn(forbidden, workflow)
+
+        mirror = (REPO / ".agents/skills/setup-workflow/assets/agent-workflow-kit-update.yml")
+        self.assertEqual(workflow, mirror.read_text(encoding="utf-8"))
+
+    def test_update_pr_runner_is_an_installed_package_binary(self):
+        package = json.loads((REPO / "package.json").read_text(encoding="utf-8"))
+        self.assertEqual(package["bin"]["agent-workflow-kit-update-pr"], "scripts/kit-update-pr.mjs")
+
     def test_spec_completeness_seed_has_valid_self_critique_block(self):
         """A convention without a valid Trigger/Check/Korrektur block makes
         spec-self-critique point 8 warn — the seed must carry one (Codex R1 #14)."""

package/src/cli.mjs

@@ -6,6 +6,7 @@ import { init } from './commands/init.mjs';
 import { update } from './commands/update.mjs';
 import { diff } from './commands/diff.mjs';
 import { uninstall } from './commands/uninstall.mjs';
+import { createCommandAdapter } from '../scripts/release-state.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const consumerRoot = process.cwd();
@@ -42,11 +43,22 @@ try {
       const ok = await p.confirm({ message: `Upstream removed ${path} — delete it locally?` });
       return ok === true;
     };
-    const r = await update({ kitRoot: KIT_ROOT, consumerRoot, now: stamp(), decide });
+    const releaseIdentities = await readUpdateRelease();
+    const r = await update({
+      kitRoot: KIT_ROOT, consumerRoot, now: stamp(), decide, releaseIdentities,
+    });
     printPlan(r);
-    for (const c of r.conflicts) p.note(c.diff || '(binary/!text)', `conflict (backed up): ${c.path}`);
-    p.outro(`updated ${r.updated.length} · added ${r.added.length} · ` +
-      `conflicts ${r.conflicts.length} · deleted ${r.deleted.length}`);
+    for (const c of r.conflicts) p.note(c.diff || '(binary/!text)', `conflict (not applied): ${c.path}`);
+    if (r.state === 'failed') throw new Error(`candidate update failed: ${r.error}`);
+    if (r.state === 'conflicted') {
+      p.note(r.report.recommendation, 'recommendation');
+      p.outro(`not applied · conflicts ${r.conflicts.length}`);
+      process.exitCode = 2;
+    } else if (r.status === 'current') {
+      p.outro(`aktuell · unchanged ${r.unchanged.length} · local modifications ${r.userModified.length}`);
+    } else {
+      p.outro(`updated ${r.updated.length} · added ${r.added.length} · deleted ${r.deleted.length}`);
+    }
   } else if (cmd === 'uninstall') {
     const ok = yes || (await p.confirm({ message: 'Remove kit-installed files?' })) === true;
     if (!ok) { p.cancel('Aborted.'); process.exit(0); }
@@ -68,3 +80,16 @@ function printPlan(r) {
   if (r.conflicts?.length) lines.push(`conflicts: ${r.conflicts.length}`);
   p.note(lines.join('\n') || 'no changes', 'plan');
 }
+
+async function readUpdateRelease() {
+  const adapter = await createCommandAdapter({
+    repoRoot: KIT_ROOT,
+    env: { ...process.env, GH_REPO: 'iKon85/agent-workflow-kit' },
+  });
+  try {
+    const local = (await adapter.local()).identity;
+    return { local, npm: await adapter.npm(local), github: await adapter.github(local) };
+  } finally {
+    await adapter.dispose();
+  }
+}

package/src/commands/update.mjs

@@ -1,95 +1,129 @@
-import { readFile, access, rm } from 'node:fs/promises';
+import { readFile, rm } from 'node:fs/promises';
 import { join } from 'node:path';
-import { sha256File } from '../lib/hash.mjs';
-import { writeAtomic, backupFile, lineDiff } from '../lib/atomicWrite.mjs';
-import { hookReferenced } from '../lib/settings.mjs';
+import { assertReleaseParity } from '../../scripts/release-parity.mjs';
+import { activateCandidate, stageConsumer, verifyCandidate } from '../lib/updateCandidate.mjs';
+import { reconcile } from '../lib/updateReconcile.mjs';
 import {
-  readManifest, writeManifest, emptyConsumerManifest,
-  PACKAGE_MANIFEST_NAME, CONSUMER_MANIFEST_NAME, indexByPath,
+  CONSUMER_MANIFEST_NAME, PACKAGE_MANIFEST_NAME, readManifest,
 } from '../lib/manifest.mjs';
 
-const exists = (p) => access(p).then(() => true, () => false);
+const RELEASE_NAME = '@ikon85/agent-workflow-kit';
 
 /**
- * Reconcile an installed consumer against the current kit (three-way: installed
- * hash vs current file = user edit?, vs package desired = upstream change?).
- *  - unmodified + upstream changed → atomic overwrite (`updated`)
- *  - user-edited + upstream changed → timestamped backup + diff, NOT clobbered (`conflicts`)
- *  - user-edited + upstream same → left as-is (`userModified`)
- *  - new upstream file → installed (`added`)
- *  - upstream-removed + unmodified → offered for deletion via `decide` (`deleted`/`keptDeleted`)
- *  - a hook file referenced by the consumer's settings is never auto-deleted (R3#7)
- * `dryRun` classifies without writing (powers `diff`). `now` = backup stamp.
+ * Transactionally reconcile a consumer with a parity-proven kit release.
+ * checking -> preview/awaiting_decision -> staging -> verifying -> terminal state.
  */
-export async function update({ kitRoot, consumerRoot, now, decide = () => false, dryRun = false }) {
+export async function update(options) {
+  const {
+    kitRoot, consumerRoot, decide = () => false, dryRun = false,
+    releaseIdentities, verify = verifyCandidate, signal, onState = () => {}, resumeFrom,
+  } = options;
+  const history = [];
+  const transition = async (state) => { history.push(state); await onState(state); };
+
+  await transition('checking');
   const pkg = await readManifest(join(kitRoot, PACKAGE_MANIFEST_NAME));
   if (!pkg) throw new Error('kit package manifest not found');
-  const consumer = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
-  if (!consumer) throw new Error('not initialised — run `init` first');
-
-  const installedIdx = indexByPath(consumer, 'installed');
-  const pkgIdx = indexByPath(pkg, 'files');
-  const res = { unchanged: [], updated: [], conflicts: [], userModified: [], added: [], deleted: [], keptDeleted: [] };
-  const nextInstalled = [];
-
-  for (const f of pkg.files) {
-    const dest = join(consumerRoot, f.path);
-    const prior = installedIdx.get(f.path);
-    const cur = (await exists(dest)) ? await sha256File(dest) : null;
-
-    if (!prior || cur === null) {
-      if (!dryRun) await writeAtomic(dest, await readFile(join(kitRoot, f.path)), f.mode);
-      nextInstalled.push(entry(f, f.sha256));
-      res.added.push(f.path);
-      continue;
-    }
-    const userEdited = cur !== prior.installedSha256;
-    const upstreamChanged = f.sha256 !== prior.installedSha256;
+  if (!dryRun) verifyRelease(releaseIdentities, pkg.kitVersion);
+  const consumerManifestPath = join(consumerRoot, CONSUMER_MANIFEST_NAME);
+  if (!await readManifest(consumerManifestPath)) {
+    throw new Error('not initialised — run `init` first');
+  }
+  const consumerManifestBefore = await readFile(consumerManifestPath);
 
-    if (!userEdited && upstreamChanged) {
-      if (!dryRun) await writeAtomic(dest, await readFile(join(kitRoot, f.path)), f.mode);
-      nextInstalled.push(entry(f, f.sha256));
-      res.updated.push(f.path);
-    } else if (userEdited && upstreamChanged) {
-      const incoming = await readFile(join(kitRoot, f.path), 'utf8');
-      const diff = lineDiff(await readFile(dest, 'utf8'), incoming);
-      if (!dryRun) await backupFile(dest, now);
-      nextInstalled.push(prior); // keep installed-hash baseline; file stays user's
-      res.conflicts.push({ path: f.path, diff });
-    } else if (userEdited) {
-      nextInstalled.push(prior);
-      res.userModified.push(f.path);
-    } else {
-      nextInstalled.push(prior);
-      res.unchanged.push(f.path);
-    }
+  const decisions = new Map();
+  const choose = async (_action, path) => {
+    if (!decisions.has(path)) decisions.set(path, await decide('delete', path));
+    return decisions.get(path);
+  };
+  const preview = await reconcile({ kitRoot, consumerRoot, decide: choose, dryRun: true });
+  await transition('preview');
+  if (preview.deleted.length || preview.keptDeleted.length) await transition('awaiting_decision');
+  if (dryRun) return { ...preview, state: 'preview', history };
+  if (preview.conflicts.length) return terminal(preview, 'conflicted', history, transition);
+  if (!hasUpstreamDelta(preview)) {
+    return { ...await terminal(preview, 'applied', history, transition), status: 'current' };
   }
+  return applyTransaction({
+    kitRoot, consumerRoot, pkg, preview, decisions, verify, signal, resumeFrom,
+    consumerManifestBefore, history, transition,
+  });
+}
 
-  // upstream-removed files (in consumer manifest, gone from package)
-  for (const prior of consumer.installed) {
-    if (pkgIdx.has(prior.path)) continue;
-    const dest = join(consumerRoot, prior.path);
-    const cur = (await exists(dest)) ? await sha256File(dest) : null;
-    const userEdited = cur !== null && cur !== prior.installedSha256;
-    const referenced = prior.kind === 'hook' && (await hookReferenced(consumerRoot, prior.path));
-    if (userEdited || referenced || !(await decide('delete', prior.path))) {
-      nextInstalled.push(prior);
-      res.keptDeleted.push(prior.path);
-    } else {
-      if (!dryRun && cur !== null) await rm(dest);
-      res.deleted.push(prior.path);
+async function applyTransaction(context) {
+  const {
+    kitRoot, consumerRoot, pkg, preview, decisions, verify, signal, resumeFrom,
+    consumerManifestBefore, history, transition,
+  } = context;
+  let candidateRoot = resumeFrom;
+  let keepCandidate = false;
+  try {
+    await transition('staging');
+    if (!candidateRoot) {
+      candidateRoot = await stageConsumer(consumerRoot);
+      await reconcile({
+        kitRoot, consumerRoot: candidateRoot,
+        decide: (_action, path) => decisions.get(path) === true,
+      });
     }
+    await transition('verifying');
+    const abort = async () => {
+      keepCandidate = true;
+      return { ...await terminal(preview, 'aborted', history, transition), candidateRoot };
+    };
+    if (signal?.aborted) return abort();
+    await verify(candidateRoot);
+    if (signal?.aborted) return abort();
+    await activateCandidate({
+      candidateRoot, consumerRoot, pkg, preview, consumerManifestBefore,
+    });
+    return { ...await terminal(preview, 'applied', history, transition), status: 'updated' };
+  } catch (error) {
+    return { ...await terminal(preview, 'failed', history, transition), error: error.message };
+  } finally {
+    if (candidateRoot && !keepCandidate) await rm(candidateRoot, { recursive: true, force: true });
   }
+}
 
-  if (!dryRun) {
-    await writeManifest(
-      join(consumerRoot, CONSUMER_MANIFEST_NAME),
-      { ...emptyConsumerManifest(pkg.kitVersion), installed: nextInstalled }
-    );
+function verifyRelease(identities, kitVersion) {
+  const release = assertReleaseParity(identities);
+  if (release.name !== RELEASE_NAME) throw new Error(`invalid release origin: ${release.name}`);
+  if (release.version !== kitVersion) {
+    throw new Error(`release version ${release.version} does not match kit ${kitVersion}`);
   }
-  return res;
 }
 
-function entry(f, sha) {
-  return { path: f.path, kind: f.kind, ownerSkill: f.ownerSkill, surface: f.surface, installedSha256: sha, origin: 'kit' };
+function hasUpstreamDelta(result) {
+  return result.added.length + result.updated.length + result.deleted.length > 0;
 }
+
+async function terminal(result, state, history, transition) {
+  await transition(state);
+  return {
+    ...result,
+    state,
+    history,
+    report: {
+      unchanged: result.unchanged.length,
+      added: result.added.length,
+      updated: result.updated.length,
+      deleted: result.deleted.length,
+      localModified: result.userModified.length,
+      conflicts: result.conflicts.length,
+      keptDeleted: result.keptDeleted.length,
+      paths: {
+        added: result.added,
+        updated: result.updated,
+        deleted: result.deleted,
+        localModified: result.userModified,
+        conflicts: result.conflicts.map(({ path }) => path),
+        keptDeleted: result.keptDeleted,
+      },
+      recommendation: result.conflicts.length
+        ? 'Review each named conflict; keep the local file or apply the incoming diff manually.'
+        : null,
+    },
+  };
+}
+
+export { verifyCandidate } from '../lib/updateCandidate.mjs';

package/src/lib/bundle.mjs

@@ -47,6 +47,9 @@ export const HELPER_FILES = [
   // the parity primitive rather than growing a second registry/GitHub comparison.
   { path: 'scripts/release-parity.mjs', kind: 'script', mode: 0o644 },
   { path: 'scripts/release-state.mjs', kind: 'script', mode: 0o644 },
+  // GitHub-consumer automation: invokes the existing update command, then owns
+  // only the stable tested branch/pull-request upsert.
+  { path: 'scripts/kit-update-pr.mjs', kind: 'script', mode: 0o755 },
   // Shared hook utility imported by the shipped hooks (drift-guard,
   // sync-board-status). Library (imported, not run) → 0o644. MUST ship or those
   // hooks ImportError on arrival.

package/src/lib/updateCandidate.mjs

@@ -0,0 +1,101 @@
+import { execFile } from 'node:child_process';
+import { access, cp, mkdtemp, readFile, rm, stat, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, relative } from 'node:path';
+import { promisify } from 'node:util';
+import { writeAtomic } from './atomicWrite.mjs';
+import { sha256File } from './hash.mjs';
+import { CONSUMER_MANIFEST_NAME, indexByPath, readManifest } from './manifest.mjs';
+
+const run = promisify(execFile);
+const exists = (path) => access(path).then(() => true, () => false);
+
+/** Copy a verification candidate without duplicating git metadata or dependencies. */
+export async function stageConsumer(consumerRoot) {
+  const candidateRoot = await mkdtemp(join(tmpdir(), 'agent-workflow-kit-stage-'));
+  const nodeModules = join(consumerRoot, 'node_modules');
+  await cp(consumerRoot, candidateRoot, {
+    recursive: true,
+    filter: (source) => {
+      const rel = relative(consumerRoot, source);
+      return rel !== '.git' && !rel.startsWith('.git/') &&
+        rel !== 'node_modules' && !rel.startsWith('node_modules/');
+    },
+  });
+  if (await exists(nodeModules)) await symlink(nodeModules, join(candidateRoot, 'node_modules'), 'dir');
+  return candidateRoot;
+}
+
+/** Activate only verified kit-owned deltas, rolling every touched path back on failure. */
+export async function activateCandidate({
+  candidateRoot, consumerRoot, pkg, preview, consumerManifestBefore,
+}) {
+  const changed = [...preview.added, ...preview.updated];
+  const touched = [...changed, ...preview.deleted, CONSUMER_MANIFEST_NAME];
+  const currentManifest = await readFile(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  if (!currentManifest.equals(consumerManifestBefore)) {
+    throw new Error('consumer manifest changed during verification');
+  }
+  const pkgIdx = indexByPath(pkg, 'files');
+  for (const path of changed) {
+    if (await sha256File(join(candidateRoot, path)) !== pkgIdx.get(path)?.sha256) {
+      throw new Error(`candidate hash mismatch: ${path}`);
+    }
+  }
+  await assertConsumerStillMatchesPreview(consumerRoot, preview);
+  const rollback = new Map();
+  for (const path of touched) rollback.set(path, await snapshot(join(consumerRoot, path)));
+  try {
+    for (const path of changed) {
+      await writeAtomic(join(consumerRoot, path), await readFile(join(candidateRoot, path)), pkgIdx.get(path)?.mode);
+    }
+    for (const path of preview.deleted) await rm(join(consumerRoot, path), { force: true });
+    await writeAtomic(
+      join(consumerRoot, CONSUMER_MANIFEST_NAME),
+      await readFile(join(candidateRoot, CONSUMER_MANIFEST_NAME)),
+    );
+  } catch (error) {
+    for (const path of touched.reverse()) await restore(join(consumerRoot, path), rollback.get(path));
+    throw error;
+  }
+}
+
+async function assertConsumerStillMatchesPreview(consumerRoot, preview) {
+  const manifest = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  const installed = indexByPath(manifest, 'installed');
+  for (const path of preview.added) {
+    if (await exists(join(consumerRoot, path))) throw new Error(`consumer changed during verification: ${path}`);
+  }
+  for (const path of [...preview.updated, ...preview.deleted]) {
+    const prior = installed.get(path);
+    const current = await exists(join(consumerRoot, path))
+      ? await sha256File(join(consumerRoot, path)) : null;
+    if (!prior || current !== prior.installedSha256) {
+      throw new Error(`consumer changed during verification: ${path}`);
+    }
+  }
+}
+
+async function snapshot(path) {
+  if (!await exists(path)) return null;
+  const info = await stat(path);
+  return { bytes: await readFile(path), mode: info.mode };
+}
+
+async function restore(path, saved) {
+  if (!saved) return rm(path, { force: true });
+  await writeAtomic(path, saved.bytes, saved.mode);
+}
+
+/** Default candidate gate: run the consumer's existing npm test command. */
+export async function verifyCandidate(candidateRoot) {
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(join(candidateRoot, 'package.json'), 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new Error('candidate has no package.json test command');
+    throw error;
+  }
+  if (!pkg.scripts?.test) throw new Error('candidate has no package.json test command');
+  await run('npm', ['test'], { cwd: candidateRoot });
+}

package/src/lib/updateReconcile.mjs

@@ -0,0 +1,89 @@
+import { access, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { sha256File } from './hash.mjs';
+import { lineDiff, writeAtomic } from './atomicWrite.mjs';
+import { hookReferenced } from './settings.mjs';
+import {
+  CONSUMER_MANIFEST_NAME, PACKAGE_MANIFEST_NAME, emptyConsumerManifest,
+  indexByPath, readManifest, writeManifest,
+} from './manifest.mjs';
+
+const exists = (path) => access(path).then(() => true, () => false);
+
+/** Classify or apply one three-way reconcile inside a supplied root. */
+export async function reconcile({ kitRoot, consumerRoot, decide = () => false, dryRun = false }) {
+  const pkg = await readManifest(join(kitRoot, PACKAGE_MANIFEST_NAME));
+  if (!pkg) throw new Error('kit package manifest not found');
+  const consumer = await readManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME));
+  if (!consumer) throw new Error('not initialised — run `init` first');
+
+  const installedIdx = indexByPath(consumer, 'installed');
+  const pkgIdx = indexByPath(pkg, 'files');
+  const result = emptyResult();
+  const nextInstalled = [];
+
+  for (const file of pkg.files) {
+    const dest = join(consumerRoot, file.path);
+    const prior = installedIdx.get(file.path);
+    const current = (await exists(dest)) ? await sha256File(dest) : null;
+    if (!prior || current === null) {
+      if (!dryRun) await writeAtomic(dest, await readFile(join(kitRoot, file.path)), file.mode);
+      nextInstalled.push(entry(file, file.sha256));
+      result.added.push(file.path);
+      continue;
+    }
+    const userEdited = current !== prior.installedSha256;
+    const upstreamChanged = file.sha256 !== prior.installedSha256;
+    if (!userEdited && upstreamChanged) {
+      if (!dryRun) await writeAtomic(dest, await readFile(join(kitRoot, file.path)), file.mode);
+      nextInstalled.push(entry(file, file.sha256));
+      result.updated.push(file.path);
+    } else if (userEdited && upstreamChanged) {
+      const incoming = await readFile(join(kitRoot, file.path), 'utf8');
+      result.conflicts.push({ path: file.path, diff: lineDiff(await readFile(dest, 'utf8'), incoming) });
+      nextInstalled.push(prior);
+    } else if (userEdited) {
+      nextInstalled.push(prior);
+      result.userModified.push(file.path);
+    } else {
+      nextInstalled.push(prior);
+      result.unchanged.push(file.path);
+    }
+  }
+
+  for (const prior of consumer.installed) {
+    if (pkgIdx.has(prior.path)) continue;
+    const dest = join(consumerRoot, prior.path);
+    const current = (await exists(dest)) ? await sha256File(dest) : null;
+    const userEdited = current !== null && current !== prior.installedSha256;
+    const referenced = prior.kind === 'hook' && (await hookReferenced(consumerRoot, prior.path));
+    if (userEdited || referenced || !(await decide('delete', prior.path))) {
+      nextInstalled.push(prior);
+      result.keptDeleted.push(prior.path);
+    } else {
+      if (!dryRun && current !== null) await rm(dest);
+      result.deleted.push(prior.path);
+    }
+  }
+
+  if (!dryRun) {
+    await writeManifest(join(consumerRoot, CONSUMER_MANIFEST_NAME), {
+      ...emptyConsumerManifest(pkg.kitVersion), installed: nextInstalled,
+    });
+  }
+  return result;
+}
+
+function emptyResult() {
+  return {
+    unchanged: [], updated: [], conflicts: [], userModified: [],
+    added: [], deleted: [], keptDeleted: [],
+  };
+}
+
+function entry(file, installedSha256) {
+  return {
+    path: file.path, kind: file.kind, ownerSkill: file.ownerSkill, surface: file.surface,
+    installedSha256, origin: 'kit',
+  };
+}