@ikon85/agent-workflow-kit 0.25.0 → 0.26.1

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

@@ -7,10 +7,10 @@ description: "Preview and transactionally apply a parity-verified agent-workflow
 
 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.
+to another publisher and is never a valid update source. Existing direct
+GitHub installs 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
 

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

@@ -26,7 +26,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `## 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) |
 | `docs/agents/census.md` | optional-census choice, paths, state, and safe disable contract seeded from [census.md](./census.md) (Section A3) |
-| `docs/agents/workflow-capabilities.json` + capability assets | consumer-owned Worktree Lifecycle, Memory Lifecycle, and Workflow Advisories choices (Sections A4–A6) |
+| `docs/agents/workflow-capabilities.json` + capability assets | consumer-owned Worktree Lifecycle, Memory Lifecycle, Workflow Advisories, and Safety Guardrails choices (Sections A4–A7) |
 
 ## Idempotency contract — read before writing anything
 
@@ -57,7 +57,7 @@ Read the current state; don't assume. For every target file, read its first line
 - `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/` — domain-doc layout.
 - `docs/agents/`, `docs/agents/skills/`, `docs/conventions/` — prior output of this skill.
 - `docs/agents/census.md`, `.census/profile.json`, `.census/active.json` — an existing census choice or consumer-owned census to adopt.
-- `docs/agents/workflow-capabilities.json`, `.claude/settings.json` — existing capability choices/profile plus Worktree Lifecycle and Workflow Advisories hook wiring to adopt.
+- `docs/agents/workflow-capabilities.json`, `.claude/settings.json`, `git config --get core.hooksPath` — existing capability choices/profile plus Worktree Lifecycle, Workflow Advisories, and Safety Guardrails wiring to adopt.
 - `.memory/active/`, `.memory/archive/`, and `.memory/receipts/` — consumer-owned Memory Lifecycle policies or recovery evidence to adopt without normalization.
 - `gh auth status` (if GitHub) — is `gh` authenticated, and with which scopes?
 
@@ -218,6 +218,31 @@ repository?"* Offer exactly **Yes**, **Later**, and **No**.
 - **Disable** — remove exact kit-owned commands first, then set `enabled:
   false`; preserve every profile value and unknown key.
 
+### 2f. Section A7 — Optional Safety Guardrails
+
+> Safety Guardrails is a counted group of seven independently selectable
+> protections: four agent-tool guards and three repository-security
+> capabilities. Setup stages and validates the chosen profile plus wiring
+> before activation; disabled rows remain exact no-ops.
+
+Read [safety-guardrails.md](./safety-guardrails.md) in full. Reconcile its
+complete `yes / later / no / existing / disable` matrix. If no choice exists,
+ask: *"Should setup configure the portable Safety Guardrails for this
+repository?"* Offer exactly **Yes**, **Later**, and **No**.
+
+- **Yes** — ask which of the seven counted rows to enable, then reconcile only
+  `safetyGuardrails`, exact selected Agent-hook commands, and the selected
+  native Git-hook path. Report `N of 7 enabled`.
+- **Later / No** — record the choice without Agent- or Git-hook wiring.
+- **Existing** — adopt profile and wiring byte-safely; preserve unknown keys
+  and consumer-specific policies.
+- **Disable** — remove only exact kit-owned Agent commands and Git wiring
+  first, then set `enabled: false`.
+
+The seed's reference consumer uses the parity-on profile. Other consumers are
+opt-in/manual: never copy its package-manager, path, shim, surface, or outage
+decisions without repository evidence and user confirmation.
+
 ### 3. Section B — Triage labels
 
 > When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.
@@ -305,10 +330,11 @@ request changes a recorded choice.
 
 For `docs/agents/workflow-capabilities.json`, reconcile only each selected
 capability section. Never replace the whole file: Project Release, Memory
-Lifecycle, Worktree Lifecycle, Workflow Advisories, future sections, and
+Lifecycle, Worktree Lifecycle, Workflow Advisories, Safety Guardrails, future sections, and
 unknown consumer keys share this profile. Apply the transition and hook
-ownership rules from [worktree-lifecycle.md](./worktree-lifecycle.md) and
-[workflow-advisories.md](./workflow-advisories.md) transactionally.
+ownership rules from [worktree-lifecycle.md](./worktree-lifecycle.md),
+[workflow-advisories.md](./workflow-advisories.md), and
+[safety-guardrails.md](./safety-guardrails.md) transactionally.
 
 For Memory Lifecycle, use only the deterministic setup helper from Section A5.
 Do not copy templates with shell commands or edit the capability profile by

package/.agents/skills/setup-workflow/safety-guardrails.md

@@ -0,0 +1,155 @@
+# Safety Guardrails setup contract
+
+Safety Guardrails is a counted, opt-in capability group backed by the
+consumer-owned `docs/agents/workflow-capabilities.json` profile. Its seven
+rows are selected independently: four protect agent tool calls and three
+bootstrap repository security. No repository name, package manager, hook
+surface, threshold, path, or outage policy is inferred from the kit.
+
+## Choice matrix
+
+| State | Setup action |
+|---|---|
+| `missing` | Ask `yes / later / no`; do not infer or write before the answer. |
+| `yes` | Ask which rows to enable, stage profile plus selected wiring, validate, then activate. |
+| `later` | Record the retryable deferral; do not activate any wiring. |
+| `no` | Record the opt-out; do not activate any wiring. |
+| `existing` | Adopt the consumer profile and existing wiring byte-safely. |
+| `disable` | Remove exact kit-owned Agent and Git wiring first, then set `enabled: false`. |
+
+```json safety-guardrails-setup-effects
+[
+  {"state":"missing","choice":null,"operations":[]},
+  {"state":"yes","choice":"yes","operations":["record-choice","stage-enabled-profile","stage-agent-hook-wiring","stage-git-hook-wiring","activate-staged-profile"]},
+  {"state":"later","choice":"later","operations":["record-choice"]},
+  {"state":"no","choice":"no","operations":["record-choice"]},
+  {"state":"existing","choice":"yes","operations":["adopt-existing"]},
+  {"state":"disable","choice":"yes","operations":["remove-agent-hook-wiring","remove-git-hook-wiring","update-profile-disabled"]}
+]
+```
+
+## Counted capability map
+
+Every historical Safety row maps to one profile decision and one shipped
+artifact. Setup reports the result as `N of 7 enabled`, never as one
+all-or-nothing switch.
+
+```json safety-guardrails-capabilities
+[
+  {"id":"secrets","profilePath":"safetyGuardrails.secrets.enabled","artifact":".claude/hooks/block-secrets.py"},
+  {"id":"packageManager","profilePath":"safetyGuardrails.packageManager.enabled","artifact":".claude/hooks/block-npm-install-in-pnpm.py"},
+  {"id":"doubleBackground","profilePath":"safetyGuardrails.doubleBackground.enabled","artifact":".claude/hooks/block-bg-double-background.py"},
+  {"id":"searchShim","profilePath":"safetyGuardrails.searchShim.enabled","artifact":".claude/hooks/grep-shim-guard.py"},
+  {"id":"gitHooks","profilePath":"safetyGuardrails.repositorySecurity.gitHooks.enabled","artifact":"scripts/security/install-git-hooks.mjs"},
+  {"id":"gitleaks","profilePath":"safetyGuardrails.repositorySecurity.gitleaks.enabled","artifact":"scripts/security/ensure-gitleaks.mjs"},
+  {"id":"dependencyAudit","profilePath":"safetyGuardrails.repositorySecurity.dependencyAudit.enabled","artifact":"scripts/security/audit-gate.mjs"}
+]
+```
+
+## Profile shape
+
+Reconcile only `safetyGuardrails`; preserve every sibling section, unknown key,
+and consumer-owned value. The following is the reference consumer's parity-on
+example, not a universal default. Other consumers choose each `enabled` value
+and fill only facts proven in their repository.
+
+```json
+{
+  "safetyGuardrails": {
+    "choice": "yes",
+    "enabled": true,
+    "secrets": {
+      "enabled": true,
+      "sensitiveNames": [".env", ".npmrc", "credentials.json"],
+      "sensitivePathFragments": ["secrets/", ".ssh/"],
+      "safeTemplateSuffixes": [".example", ".sample", ".template", ".dist"]
+    },
+    "packageManager": {
+      "enabled": true,
+      "lockfiles": {
+        "pnpm-lock.yaml": "pnpm",
+        "package-lock.json": "npm",
+        "yarn.lock": "yarn",
+        "bun.lockb": "bun"
+      }
+    },
+    "doubleBackground": {"enabled": true, "surfaces": ["claude"]},
+    "searchShim": {
+      "enabled": true,
+      "detected": true,
+      "commandNames": ["grep", "rg"]
+    },
+    "repositorySecurity": {
+      "gitHooks": {"enabled": true, "hooksPath": ".githooks"},
+      "gitleaks": {"enabled": true, "required": false},
+      "dependencyAudit": {
+        "enabled": true,
+        "packageManager": "pnpm",
+        "outagePolicy": "warn",
+        "blockSeverities": ["high", "critical"]
+      }
+    }
+  }
+}
+```
+
+An empty or disabled row is an honest no-op. `searchShim.detected` is a
+consumer fact, not an installation request. `gitleaks.required: false` keeps
+the verified optional provisioner non-blocking when the platform or network is
+unsupported. Dependency-audit outage policy must be explicit.
+
+## Agent-hook ownership
+
+Wire only enabled rows, using the exact kit-owned commands:
+
+- `secrets` — `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/block-secrets.py"`
+- `packageManager` —
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/block-npm-install-in-pnpm.py"`
+- `doubleBackground` —
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/block-bg-double-background.py"`
+- `searchShim` —
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/grep-shim-guard.py"`
+
+All four are PreToolUse adapters. Preserve unrelated matchers and commands in
+`.claude/settings.json`. Disable removes only these exact commands.
+
+## Repository wiring
+
+When `gitHooks.enabled` is true, run:
+
+```bash
+node scripts/security/install-git-hooks.mjs <hooksPath>
+```
+
+only after confirming the configured directory exists and contains the
+consumer's intended hooks. Never create or replace consumer hook bodies.
+
+When `gitleaks.enabled` is true, the pinned profile may be provisioned through
+`scripts/security/ensure-gitleaks.mjs`; checksum mismatch, unsupported platform,
+offline state, and unwritable destination remain distinct visible outcomes.
+Never read a secret file to test the provisioner.
+
+When `dependencyAudit.enabled` is true, use
+`scripts/security/audit-gate.mjs` with the configured package manager and
+outage policy. High/Critical findings block; Low/Moderate findings pass.
+
+## Transaction and failure contract
+
+Prepare the next profile and `.claude/settings.json` in same-directory staging
+files. Validate JSON, all selected artifact paths, the seven-row count, the
+configured Git-hook directory, and package-manager facts before mutation.
+Then:
+
+1. reconcile selected Agent commands in the staged settings;
+2. remember the prior `core.hooksPath` and apply the selected Git wiring;
+3. atomically rename staged settings and profile into place;
+4. on any failure, restore the prior Git config and leave active files
+   byte-for-byte unchanged.
+
+Disable reverses the safety order: remove exact Agent commands and restore or
+unset only the kit-owned Git wiring before committing `enabled: false`.
+Repeated activation with the same choices is byte-idempotent.
+
+Setup and verification may inspect paths, profile metadata, command exit
+status, advisory counts, and hashes. They must never read secret contents or
+print environment/config values.

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

@@ -7,10 +7,10 @@ description: "Preview and transactionally apply a parity-verified agent-workflow
 
 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.
+to another publisher and is never a valid update source. Existing direct
+GitHub installs 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
 

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

@@ -26,7 +26,7 @@ This is a prompt-driven skill, not a deterministic script. Explore, present what
 | `## 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) |
 | `docs/agents/census.md` | optional-census choice, paths, state, and safe disable contract seeded from [census.md](./census.md) (Section A3) |
-| `docs/agents/workflow-capabilities.json` + capability assets | consumer-owned Worktree Lifecycle, Memory Lifecycle, and Workflow Advisories choices (Sections A4–A6) |
+| `docs/agents/workflow-capabilities.json` + capability assets | consumer-owned Worktree Lifecycle, Memory Lifecycle, Workflow Advisories, and Safety Guardrails choices (Sections A4–A7) |
 
 ## Idempotency contract — read before writing anything
 
@@ -57,7 +57,7 @@ Read the current state; don't assume. For every target file, read its first line
 - `CONTEXT.md`, `CONTEXT-MAP.md`, `docs/adr/` — domain-doc layout.
 - `docs/agents/`, `docs/agents/skills/`, `docs/conventions/` — prior output of this skill.
 - `docs/agents/census.md`, `.census/profile.json`, `.census/active.json` — an existing census choice or consumer-owned census to adopt.
-- `docs/agents/workflow-capabilities.json`, `.claude/settings.json` — existing capability choices/profile plus Worktree Lifecycle and Workflow Advisories hook wiring to adopt.
+- `docs/agents/workflow-capabilities.json`, `.claude/settings.json`, `git config --get core.hooksPath` — existing capability choices/profile plus Worktree Lifecycle, Workflow Advisories, and Safety Guardrails wiring to adopt.
 - `.memory/active/`, `.memory/archive/`, and `.memory/receipts/` — consumer-owned Memory Lifecycle policies or recovery evidence to adopt without normalization.
 - `gh auth status` (if GitHub) — is `gh` authenticated, and with which scopes?
 
@@ -218,6 +218,31 @@ repository?"* Offer exactly **Yes**, **Later**, and **No**.
 - **Disable** — remove exact kit-owned commands first, then set `enabled:
   false`; preserve every profile value and unknown key.
 
+### 2f. Section A7 — Optional Safety Guardrails
+
+> Safety Guardrails is a counted group of seven independently selectable
+> protections: four agent-tool guards and three repository-security
+> capabilities. Setup stages and validates the chosen profile plus wiring
+> before activation; disabled rows remain exact no-ops.
+
+Read [safety-guardrails.md](./safety-guardrails.md) in full. Reconcile its
+complete `yes / later / no / existing / disable` matrix. If no choice exists,
+ask: *"Should setup configure the portable Safety Guardrails for this
+repository?"* Offer exactly **Yes**, **Later**, and **No**.
+
+- **Yes** — ask which of the seven counted rows to enable, then reconcile only
+  `safetyGuardrails`, exact selected Agent-hook commands, and the selected
+  native Git-hook path. Report `N of 7 enabled`.
+- **Later / No** — record the choice without Agent- or Git-hook wiring.
+- **Existing** — adopt profile and wiring byte-safely; preserve unknown keys
+  and consumer-specific policies.
+- **Disable** — remove only exact kit-owned Agent commands and Git wiring
+  first, then set `enabled: false`.
+
+The seed's reference consumer uses the parity-on profile. Other consumers are
+opt-in/manual: never copy its package-manager, path, shim, surface, or outage
+decisions without repository evidence and user confirmation.
+
 ### 3. Section B — Triage labels
 
 > When `triage` processes an incoming issue it applies labels (or your tracker's equivalent). It needs strings you've actually configured, or it creates duplicates.
@@ -305,10 +330,11 @@ request changes a recorded choice.
 
 For `docs/agents/workflow-capabilities.json`, reconcile only each selected
 capability section. Never replace the whole file: Project Release, Memory
-Lifecycle, Worktree Lifecycle, Workflow Advisories, future sections, and
+Lifecycle, Worktree Lifecycle, Workflow Advisories, Safety Guardrails, future sections, and
 unknown consumer keys share this profile. Apply the transition and hook
-ownership rules from [worktree-lifecycle.md](./worktree-lifecycle.md) and
-[workflow-advisories.md](./workflow-advisories.md) transactionally.
+ownership rules from [worktree-lifecycle.md](./worktree-lifecycle.md),
+[workflow-advisories.md](./workflow-advisories.md), and
+[safety-guardrails.md](./safety-guardrails.md) transactionally.
 
 For Memory Lifecycle, use only the deterministic setup helper from Section A5.
 Do not copy templates with shell commands or edit the capability profile by

package/.claude/skills/setup-workflow/safety-guardrails.md

@@ -0,0 +1,155 @@
+# Safety Guardrails setup contract
+
+Safety Guardrails is a counted, opt-in capability group backed by the
+consumer-owned `docs/agents/workflow-capabilities.json` profile. Its seven
+rows are selected independently: four protect agent tool calls and three
+bootstrap repository security. No repository name, package manager, hook
+surface, threshold, path, or outage policy is inferred from the kit.
+
+## Choice matrix
+
+| State | Setup action |
+|---|---|
+| `missing` | Ask `yes / later / no`; do not infer or write before the answer. |
+| `yes` | Ask which rows to enable, stage profile plus selected wiring, validate, then activate. |
+| `later` | Record the retryable deferral; do not activate any wiring. |
+| `no` | Record the opt-out; do not activate any wiring. |
+| `existing` | Adopt the consumer profile and existing wiring byte-safely. |
+| `disable` | Remove exact kit-owned Agent and Git wiring first, then set `enabled: false`. |
+
+```json safety-guardrails-setup-effects
+[
+  {"state":"missing","choice":null,"operations":[]},
+  {"state":"yes","choice":"yes","operations":["record-choice","stage-enabled-profile","stage-agent-hook-wiring","stage-git-hook-wiring","activate-staged-profile"]},
+  {"state":"later","choice":"later","operations":["record-choice"]},
+  {"state":"no","choice":"no","operations":["record-choice"]},
+  {"state":"existing","choice":"yes","operations":["adopt-existing"]},
+  {"state":"disable","choice":"yes","operations":["remove-agent-hook-wiring","remove-git-hook-wiring","update-profile-disabled"]}
+]
+```
+
+## Counted capability map
+
+Every historical Safety row maps to one profile decision and one shipped
+artifact. Setup reports the result as `N of 7 enabled`, never as one
+all-or-nothing switch.
+
+```json safety-guardrails-capabilities
+[
+  {"id":"secrets","profilePath":"safetyGuardrails.secrets.enabled","artifact":".claude/hooks/block-secrets.py"},
+  {"id":"packageManager","profilePath":"safetyGuardrails.packageManager.enabled","artifact":".claude/hooks/block-npm-install-in-pnpm.py"},
+  {"id":"doubleBackground","profilePath":"safetyGuardrails.doubleBackground.enabled","artifact":".claude/hooks/block-bg-double-background.py"},
+  {"id":"searchShim","profilePath":"safetyGuardrails.searchShim.enabled","artifact":".claude/hooks/grep-shim-guard.py"},
+  {"id":"gitHooks","profilePath":"safetyGuardrails.repositorySecurity.gitHooks.enabled","artifact":"scripts/security/install-git-hooks.mjs"},
+  {"id":"gitleaks","profilePath":"safetyGuardrails.repositorySecurity.gitleaks.enabled","artifact":"scripts/security/ensure-gitleaks.mjs"},
+  {"id":"dependencyAudit","profilePath":"safetyGuardrails.repositorySecurity.dependencyAudit.enabled","artifact":"scripts/security/audit-gate.mjs"}
+]
+```
+
+## Profile shape
+
+Reconcile only `safetyGuardrails`; preserve every sibling section, unknown key,
+and consumer-owned value. The following is the reference consumer's parity-on
+example, not a universal default. Other consumers choose each `enabled` value
+and fill only facts proven in their repository.
+
+```json
+{
+  "safetyGuardrails": {
+    "choice": "yes",
+    "enabled": true,
+    "secrets": {
+      "enabled": true,
+      "sensitiveNames": [".env", ".npmrc", "credentials.json"],
+      "sensitivePathFragments": ["secrets/", ".ssh/"],
+      "safeTemplateSuffixes": [".example", ".sample", ".template", ".dist"]
+    },
+    "packageManager": {
+      "enabled": true,
+      "lockfiles": {
+        "pnpm-lock.yaml": "pnpm",
+        "package-lock.json": "npm",
+        "yarn.lock": "yarn",
+        "bun.lockb": "bun"
+      }
+    },
+    "doubleBackground": {"enabled": true, "surfaces": ["claude"]},
+    "searchShim": {
+      "enabled": true,
+      "detected": true,
+      "commandNames": ["grep", "rg"]
+    },
+    "repositorySecurity": {
+      "gitHooks": {"enabled": true, "hooksPath": ".githooks"},
+      "gitleaks": {"enabled": true, "required": false},
+      "dependencyAudit": {
+        "enabled": true,
+        "packageManager": "pnpm",
+        "outagePolicy": "warn",
+        "blockSeverities": ["high", "critical"]
+      }
+    }
+  }
+}
+```
+
+An empty or disabled row is an honest no-op. `searchShim.detected` is a
+consumer fact, not an installation request. `gitleaks.required: false` keeps
+the verified optional provisioner non-blocking when the platform or network is
+unsupported. Dependency-audit outage policy must be explicit.
+
+## Agent-hook ownership
+
+Wire only enabled rows, using the exact kit-owned commands:
+
+- `secrets` — `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/block-secrets.py"`
+- `packageManager` —
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/block-npm-install-in-pnpm.py"`
+- `doubleBackground` —
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/block-bg-double-background.py"`
+- `searchShim` —
+  `python3 "$CLAUDE_PROJECT_DIR/.claude/hooks/grep-shim-guard.py"`
+
+All four are PreToolUse adapters. Preserve unrelated matchers and commands in
+`.claude/settings.json`. Disable removes only these exact commands.
+
+## Repository wiring
+
+When `gitHooks.enabled` is true, run:
+
+```bash
+node scripts/security/install-git-hooks.mjs <hooksPath>
+```
+
+only after confirming the configured directory exists and contains the
+consumer's intended hooks. Never create or replace consumer hook bodies.
+
+When `gitleaks.enabled` is true, the pinned profile may be provisioned through
+`scripts/security/ensure-gitleaks.mjs`; checksum mismatch, unsupported platform,
+offline state, and unwritable destination remain distinct visible outcomes.
+Never read a secret file to test the provisioner.
+
+When `dependencyAudit.enabled` is true, use
+`scripts/security/audit-gate.mjs` with the configured package manager and
+outage policy. High/Critical findings block; Low/Moderate findings pass.
+
+## Transaction and failure contract
+
+Prepare the next profile and `.claude/settings.json` in same-directory staging
+files. Validate JSON, all selected artifact paths, the seven-row count, the
+configured Git-hook directory, and package-manager facts before mutation.
+Then:
+
+1. reconcile selected Agent commands in the staged settings;
+2. remember the prior `core.hooksPath` and apply the selected Git wiring;
+3. atomically rename staged settings and profile into place;
+4. on any failure, restore the prior Git config and leave active files
+   byte-for-byte unchanged.
+
+Disable reverses the safety order: remove exact Agent commands and restore or
+unset only the kit-owned Git wiring before committing `enabled: false`.
+Repeated activation with the same choices is byte-idempotent.
+
+Setup and verification may inspect paths, profile metadata, command exit
+status, advisory counts, and hashes. They must never read secret contents or
+print environment/config values.

package/README.md

@@ -332,6 +332,34 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.26.1
+
+- changed: `.agents/skills/kit-update/SKILL.md`
+- changed: `.agents/skills/setup-workflow/SKILL.md`
+- changed: `.agents/skills/setup-workflow/safety-guardrails.md`
+- changed: `.claude/skills/kit-update/SKILL.md`
+- changed: `.claude/skills/setup-workflow/SKILL.md`
+- changed: `.claude/skills/setup-workflow/safety-guardrails.md`
+- changed: `scripts/release-delta-guard.mjs`
+
+### 0.26.0
+
+- added: `.agents/skills/setup-workflow/safety-guardrails.md`
+- added: `.claude/hooks/_safety_guard.py`
+- added: `.claude/hooks/block-bg-double-background.py`
+- added: `.claude/hooks/block-npm-install-in-pnpm.py`
+- added: `.claude/hooks/block-secrets.py`
+- added: `.claude/hooks/grep-shim-guard.py`
+- added: `.claude/skills/setup-workflow/safety-guardrails.md`
+- added: `scripts/safety-guardrails/core.py`
+- added: `scripts/safety-guardrails/search.py`
+- added: `scripts/security/audit-gate.mjs`
+- added: `scripts/security/ensure-gitleaks.mjs`
+- added: `scripts/security/gitleaks-profile.json`
+- added: `scripts/security/install-git-hooks.mjs`
+- changed: `.agents/skills/setup-workflow/SKILL.md`
+- changed: `.claude/skills/setup-workflow/SKILL.md`
+
 ### 0.25.0
 
 - added: `.claude/hooks/convention-drift-hint.py`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.25.0",
+  "kitVersion": "0.26.1",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -339,7 +339,7 @@
       "kind": "skill",
       "ownerSkill": "kit-update",
       "surface": "codex",
-      "sha256": "5b7a8c11b5852ee115fa8d3f66a3938d7b4db173a47d711da48abab635b2c261",
+      "sha256": "dbf2c0f696bd0ce45c5c2a315d40a3bbb99635e4ab384c788ac59f799fbf43de",
       "mode": 420,
       "origin": "kit"
     },
@@ -568,12 +568,21 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".agents/skills/setup-workflow/safety-guardrails.md",
+      "kind": "skill",
+      "ownerSkill": "setup-workflow",
+      "surface": "codex",
+      "sha256": "8e223f625dcf941142005cbd9a4b6214358f68e3fd63cbee7bffef35b8b14ec8",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".agents/skills/setup-workflow/SKILL.md",
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "96c0c3ba9ed6b194030a8c45be618caf934e9c4ca8415ea19d726af33cd763cb",
+      "sha256": "e4cac2f46ac5f16e9a1473b38a64979a7d767ccdc834a2540d20c733305ea2e7",
       "mode": 420,
       "origin": "kit"
     },
@@ -890,6 +899,13 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/hooks/_safety_guard.py",
+      "kind": "hook",
+      "sha256": "1f5c387b11731c7b1cd027fc58acd4c1e45c64799975dc50eeff72469df0deb0",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/hooks/baseline-capture-hint.py",
       "kind": "hook",
@@ -897,6 +913,27 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": ".claude/hooks/block-bg-double-background.py",
+      "kind": "hook",
+      "sha256": "ad0c763e3afbb25685f91eea2c39fc3ee58c765536a961810a49bd0c7bbd47b8",
+      "mode": 493,
+      "origin": "kit"
+    },
+    {
+      "path": ".claude/hooks/block-npm-install-in-pnpm.py",
+      "kind": "hook",
+      "sha256": "54da075f8e63e5e927cb752c26c47880da49eb1f730f078558f3f5eec9377c82",
+      "mode": 493,
+      "origin": "kit"
+    },
+    {
+      "path": ".claude/hooks/block-secrets.py",
+      "kind": "hook",
+      "sha256": "962c4f7f035c5cb4c322ee7c76b707a148526000427f4ebd49bfcac50af003b4",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": ".claude/hooks/branch-context.py",
       "kind": "hook",
@@ -946,6 +983,13 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": ".claude/hooks/grep-shim-guard.py",
+      "kind": "hook",
+      "sha256": "9f69541c60c795bd5ec2a4f5d155f6fd3ced4f2ac6a28ed0c55c9a57772dd0d2",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": ".claude/hooks/loc-offender-forewarn.py",
       "kind": "hook",
@@ -1455,7 +1499,7 @@
       "kind": "skill",
       "ownerSkill": "kit-update",
       "surface": "claude",
-      "sha256": "5b7a8c11b5852ee115fa8d3f66a3938d7b4db173a47d711da48abab635b2c261",
+      "sha256": "dbf2c0f696bd0ce45c5c2a315d40a3bbb99635e4ab384c788ac59f799fbf43de",
       "mode": 420,
       "origin": "kit"
     },
@@ -1702,12 +1746,21 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/skills/setup-workflow/safety-guardrails.md",
+      "kind": "skill",
+      "ownerSkill": "setup-workflow",
+      "surface": "claude",
+      "sha256": "8e223f625dcf941142005cbd9a4b6214358f68e3fd63cbee7bffef35b8b14ec8",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/setup-workflow/SKILL.md",
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "96c0c3ba9ed6b194030a8c45be618caf934e9c4ca8415ea19d726af33cd763cb",
+      "sha256": "e4cac2f46ac5f16e9a1473b38a64979a7d767ccdc834a2540d20c733305ea2e7",
       "mode": 420,
       "origin": "kit"
     },
@@ -2250,7 +2303,7 @@
     {
       "path": "scripts/release-delta-guard.mjs",
       "kind": "script",
-      "sha256": "37a6f27b350bb98a19a8c53e1f6ee187b3a39c0ff5317141717bf9ab65129bad",
+      "sha256": "a51f30e7261e4efb0b5c5002f39353ef8e8be18a2bd39ad7139f1ce7a2e7e18d",
       "mode": 420,
       "origin": "kit"
     },
@@ -2268,6 +2321,48 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": "scripts/safety-guardrails/core.py",
+      "kind": "script",
+      "sha256": "c69c9d4e1b17efca51de12454b119e9ee6758aa6c8d73fe64e4bafd76c804f4e",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/safety-guardrails/search.py",
+      "kind": "script",
+      "sha256": "345b1456f1a00320b6ad3e4fad1b050d8dd21a16b51b5e5cfdaf6a579530eac1",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/security/audit-gate.mjs",
+      "kind": "script",
+      "sha256": "c6129e77f58e80f5880ebd6d2d235e27e9e31a20ee3cd967ce64815738e61e54",
+      "mode": 493,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/security/ensure-gitleaks.mjs",
+      "kind": "script",
+      "sha256": "5591f31d88362aa0df75f7b6bb7f22c094822b4bd00c5f6bf9ccff6a2313ed56",
+      "mode": 493,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/security/gitleaks-profile.json",
+      "kind": "doc",
+      "sha256": "2480f7b4656d28cea1ede895970275d7b97f58d396341ee5e36b3df12575c1b6",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/security/install-git-hooks.mjs",
+      "kind": "script",
+      "sha256": "8cf43120ea485fae7dc6aae38a14a3e703dbd18422ef13a199aedb3ec66b0184",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": "scripts/workflow-advisories/capabilities.json",
       "kind": "doc",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.25.0",
+  "version": "0.26.1",
   "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": {

package/scripts/release-delta-guard.mjs

@@ -1,9 +1,10 @@
 /** Block shipped changes whose version or checked manifest does not match a fresh build. */
 import { execFileSync } from 'node:child_process';
-import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { sha256 } from '../src/lib/hash.mjs';
 import { buildKit } from './build-kit.mjs';
 
 const byPath = (manifest) => new Map(manifest.files.map((entry) => [entry.path, entry.sha256]));
@@ -41,6 +42,7 @@ function bumpKind(before, after) {
 export function assessRelease(input) {
   const delta = manifestDelta(input.baseManifest, input.builtManifest);
   const checkedDrift = manifestDelta(input.checkedManifest, input.builtManifest);
+  const payloadDrift = manifestDelta(input.builtManifest, input.payloadManifest);
   const errors = [];
   if (hasDelta(delta) && input.currentVersion === input.baseVersion) {
     errors.push(`shipped delta has no version bump (${describe(delta)}); version remains ${input.currentVersion}`);
@@ -52,6 +54,9 @@ export function assessRelease(input) {
   if (checkedDrift.added.length || checkedDrift.changed.length) {
     errors.push(`checked manifest is stale (${describe(checkedDrift)})`);
   }
+  if (hasDelta(payloadDrift)) {
+    errors.push(`npm package payload does not match built manifest (${describe(payloadDrift)})`);
+  }
   const recommendedBump = recommendBump(delta);
   const actual = bumpKind(input.baseVersion, input.currentVersion);
   const rank = { patch: 1, minor: 2, major: 3 };
@@ -68,18 +73,43 @@ function gitShowJson(repoRoot, ref, path) {
   return JSON.parse(execFileSync('git', ['show', `${ref}:${path}`], { cwd: repoRoot, encoding: 'utf8' }));
 }
 
+export async function packedPayloadManifest({ repoRoot, manifest }) {
+  const tempRoot = await mkdtemp(join(tmpdir(), 'awkit-package-payload-'));
+  try {
+    const packOutput = execFileSync(
+      'npm', ['pack', '--json', '--ignore-scripts', '--pack-destination', tempRoot],
+      { cwd: repoRoot, encoding: 'utf8' },
+    );
+    const [{ filename }] = JSON.parse(packOutput);
+    const unpackDir = join(tempRoot, 'unpacked');
+    await mkdir(unpackDir);
+    execFileSync('tar', ['-xzf', join(tempRoot, filename), '-C', unpackDir]);
+    return {
+      kitVersion: manifest.kitVersion,
+      files: await Promise.all(manifest.files.map(async (entry) => ({
+        ...entry,
+        sha256: sha256(await readFile(join(unpackDir, 'package', entry.path))),
+      }))),
+    };
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
 export async function checkReleaseDelta({ repoRoot, baseRef = 'origin/main' } = {}) {
   repoRoot ??= join(dirname(fileURLToPath(import.meta.url)), '..');
   const distDir = await mkdtemp(join(tmpdir(), 'awkit-release-guard-'));
   try {
     await buildKit({ repoRoot, distDir });
     const currentPackage = JSON.parse(await readFile(join(repoRoot, 'package.json'), 'utf8'));
+    const builtManifest = JSON.parse(await readFile(join(distDir, 'agent-workflow-kit.package.json'), 'utf8'));
     return assessRelease({
       baseVersion: gitShowJson(repoRoot, baseRef, 'package.json').version,
       currentVersion: currentPackage.version,
       baseManifest: gitShowJson(repoRoot, baseRef, 'agent-workflow-kit.package.json'),
       checkedManifest: JSON.parse(await readFile(join(repoRoot, 'agent-workflow-kit.package.json'), 'utf8')),
-      builtManifest: JSON.parse(await readFile(join(distDir, 'agent-workflow-kit.package.json'), 'utf8')),
+      builtManifest,
+      payloadManifest: await packedPayloadManifest({ repoRoot, manifest: builtManifest }),
     });
   } finally { await rm(distDir, { recursive: true, force: true }); }
 }

package/scripts/release-delta-guard.test.mjs

@@ -1,8 +1,29 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { assessRelease } from './release-delta-guard.mjs';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildKit } from './build-kit.mjs';
+import {
+  assessRelease, manifestDelta, packedPayloadManifest,
+} from './release-delta-guard.mjs';
 
 const file = (path, sha256) => ({ path, sha256 });
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+test('fresh build manifest hashes match the actual npm package payload', async () => {
+  const tempRoot = await mkdtemp(join(tmpdir(), 'awkit-packed-manifest-test-'));
+  try {
+    const distDir = join(tempRoot, 'dist');
+    await buildKit({ repoRoot, distDir });
+    const built = JSON.parse(await readFile(join(distDir, 'agent-workflow-kit.package.json'), 'utf8'));
+    const packed = await packedPayloadManifest({ repoRoot, manifest: built });
+    assert.deepEqual(manifestDelta(built, packed), { added: [], removed: [], changed: [] });
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+});
 
 test('an unbumped shipped change is blocked with its concrete delta', () => {
   const result = assessRelease({
@@ -10,6 +31,7 @@ test('an unbumped shipped change is blocked with its concrete delta', () => {
     baseManifest: { kitVersion: '1.2.3', files: [file('skill.md', 'old')] },
     builtManifest: { kitVersion: '1.2.3', files: [file('skill.md', 'new')] },
     checkedManifest: { kitVersion: '1.2.3', files: [file('skill.md', 'old')] },
+    payloadManifest: { kitVersion: '1.2.3', files: [file('skill.md', 'new')] },
   });
   assert.equal(result.ok, false);
   assert.deepEqual(result.delta.changed, ['skill.md']);
@@ -23,6 +45,7 @@ test('dead checked-manifest entries are rejected', () => {
     baseManifest: { kitVersion: '1.2.3', files: [] },
     builtManifest: { kitVersion: '1.3.0', files: [] },
     checkedManifest: { kitVersion: '1.3.0', files: [file('gone.md', 'old')] },
+    payloadManifest: { kitVersion: '1.3.0', files: [] },
   });
   assert.equal(result.ok, false);
   assert.match(result.errors.join('\n'), /dead entry: gone\.md/);
@@ -33,7 +56,7 @@ test('a matching regenerated manifest and semantic bump pass', () => {
   const result = assessRelease({
     baseVersion: '1.2.3', currentVersion: '1.3.0',
     baseManifest: { kitVersion: '1.2.3', files: [] }, builtManifest: current,
-    checkedManifest: current,
+    checkedManifest: current, payloadManifest: current,
   });
   assert.equal(result.ok, true);
   assert.equal(result.recommendedBump, 'minor');
@@ -45,9 +68,20 @@ test('shipped content rejects downgrade and malformed version transitions', () =
     const result = assessRelease({
       baseVersion: '1.2.3', currentVersion,
       baseManifest: { kitVersion: '1.2.3', files: [file('skill.md', 'old')] },
-      builtManifest: current, checkedManifest: current,
+      builtManifest: current, checkedManifest: current, payloadManifest: current,
     });
     assert.equal(result.ok, false, currentVersion);
     assert.match(result.errors.join('\n'), /invalid version transition: 1\.2\.3 ->/);
   }
 });
+
+test('actual npm payload drift is blocked even when checked and built manifests match', () => {
+  const scrubbed = { kitVersion: '1.2.3', files: [file('skill.md', 'scrubbed')] };
+  const result = assessRelease({
+    baseVersion: '1.2.3', currentVersion: '1.2.3',
+    baseManifest: scrubbed, builtManifest: scrubbed, checkedManifest: scrubbed,
+    payloadManifest: { kitVersion: '1.2.3', files: [file('skill.md', 'source')] },
+  });
+  assert.equal(result.ok, false);
+  assert.match(result.errors.join('\n'), /npm package payload.*changed: skill\.md/);
+});

package/scripts/test_skill_publish_audit.py

@@ -124,6 +124,13 @@ def _known_hashes(root: Path) -> set:
         for f in data.get("files", []):
             if "sha256" in f:
                 hashes.add(f["sha256"])
+    gitleaks = root / "scripts/security/gitleaks-profile.json"
+    if gitleaks.exists():
+        data = json.loads(gitleaks.read_text(encoding="utf-8"))
+        for platform in data.get("platforms", {}).values():
+            checksum = platform.get("sha256")
+            if isinstance(checksum, str):
+                hashes.add(checksum)
     return hashes
 
 
@@ -293,6 +300,14 @@ class Exemptions(unittest.TestCase):
                 {"path": "x", "sha256": "f" * 64}]}), encoding="utf-8")
         self.assertEqual(audit_dir(self.dir), [])
 
+    def test_gitleaks_profile_checksums_are_verified_pin_metadata(self):
+        profile = self.dir / "scripts/security"
+        profile.mkdir(parents=True)
+        (profile / "gitleaks-profile.json").write_text(json.dumps({
+            "platforms": {"linux-x64": {"sha256": "e" * 64}},
+        }), encoding="utf-8")
+        self.assertEqual(audit_dir(self.dir), [])
+
     def test_loc_offender_traversal_guard_allowed(self):
         p = self.dir / "scripts"
         p.mkdir()

package/src/lib/bundle.mjs

@@ -104,6 +104,20 @@ export const HELPER_FILES = [
   { path: '.claude/hooks/migration-snapshot-reminder.py', kind: 'hook', mode: 0o755 },
   { path: '.claude/hooks/loc-offender-forewarn.py', kind: 'hook', mode: 0o755 },
   { path: '.claude/hooks/drift-guard.py', kind: 'hook', mode: 0o755 },
+  // Counted Safety Guardrails unit: shared policy/search core, one loader,
+  // four thin Agent adapters, and three portable repository-security
+  // primitives. Activation stays consumer-owned through setup-workflow.
+  { path: 'scripts/safety-guardrails/core.py', kind: 'script', mode: 0o644 },
+  { path: 'scripts/safety-guardrails/search.py', kind: 'script', mode: 0o644 },
+  { path: '.claude/hooks/_safety_guard.py', kind: 'hook', mode: 0o644 },
+  { path: '.claude/hooks/block-secrets.py', kind: 'hook', mode: 0o755 },
+  { path: '.claude/hooks/block-npm-install-in-pnpm.py', kind: 'hook', mode: 0o755 },
+  { path: '.claude/hooks/block-bg-double-background.py', kind: 'hook', mode: 0o755 },
+  { path: '.claude/hooks/grep-shim-guard.py', kind: 'hook', mode: 0o755 },
+  { path: 'scripts/security/install-git-hooks.mjs', kind: 'script', mode: 0o755 },
+  { path: 'scripts/security/ensure-gitleaks.mjs', kind: 'script', mode: 0o755 },
+  { path: 'scripts/security/gitleaks-profile.json', kind: 'doc', mode: 0o644 },
+  { path: 'scripts/security/audit-gate.mjs', kind: 'script', mode: 0o755 },
   // SessionStart skill-freshness drift-hint (audit-skills names it). For each
   // <skill>/SOURCES.txt it flags sources newer in git than the SKILL.md. Imports
   // _hook_utils (shipped above); stdlib-only otherwise. Executable hook → 0o755.