@lifeaitools/rdc-skills 0.9.36 → 0.9.38

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.9.36",
+  "version": "0.9.38",
   "description": "RDC typed-agent dispatch skill suite for Claude Code — plan, build, review, overnight unattended builds with work-item tracking and TDD enforcement.",
   "author": {
     "name": "LIFEAI",

package/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## v0.9.38 — Clean-box npm install hardening
+
+### Fixed
+
+- **Fresh Claude home install.** The installer now creates `CLAUDE_HOME` and `settings.json` when they do not exist, so a first-time machine is not blocked before Claude has written config files.
+- **Public package portability.** Removed the most brittle user-machine paths from public skill docs and hooks, replacing them with `{PROJECT_ROOT}`, `{RDC_SKILLS_ROOT}`, or environment-derived paths.
+- **Hook path fallback.** Commit hygiene hooks now use the current OS home directory instead of a user-specific fallback path.
+
+### Added
+
+- **npm binaries.** `rdc-skills-install` and `rdc-skills-self-test` are exposed from the npm package for simpler clean-box installs.
+
+---
+
+## v0.9.37 — RDC hook loop guard and behavior tests
+
+### Fixed
+
+- **Stop hook reentry.** `rdc-output-contract-gate.js` now exits cleanly when Claude is already inside an active Stop-hook retry, preventing noncompliant-but-legitimate turns from hard-looping the session.
+- **Marker deduplication.** `rdc-invocation-marker.js` now preserves the original marker when `UserPromptExpansion` and `UserPromptSubmit` both fire for the same RDC command within the same second.
+
+### Added
+
+- **Hook behavioral tests.** New `scripts/test-rdc-hooks.mjs` executes the marker and Stop hooks against real JSON payloads, and `self-test --strict` now fails if those behavioral checks fail.
+
+---
+
 ## v0.9.36 — Portable installer profiles and startup onboarding
 
 ### Added

package/commands/deploy.md

@@ -55,7 +55,7 @@ rdc:deploy: <slug> → <domain>
 ```
 rdc:deploy new: <slug>
 [ ] Registry entry loaded (or interactive create)
-[ ] DNS path chosen (A: *.dev.place.fund  B: apex  C: other zone)
+[ ] DNS path chosen (A: staging wildcard  B: apex  C: other zone)
 [ ] DNS record verified or wildcard confirmed
 [ ] Cloudflare proxy setting correct for DNS path
 [ ] server_uuid, project_uuid, environment_uuid, github_app_uuid resolved
@@ -103,7 +103,7 @@ rdc:deploy audit: fleet scan
 [ ] Env var drift (registry.env_vars_needed vs Coolify env)
 [ ] Branch mismatches (Coolify git_branch ≠ expected)
 [ ] Disk space on 64.237.54.189
-[ ] CF proxy misconfigs on *.dev.place.fund
+[ ] DNS/proxy misconfigs on configured staging wildcard
 [ ] Duplicate apps (same repo, multiple UUIDs)
 
 Findings:
@@ -127,7 +127,7 @@ There is no Coolify MCP server — do not reference `@masonator/coolify-mcp`.
 
 ```bash
 _COOLIFY=$(curl -s http://127.0.0.1:52437/v/coolify-api)
-curl -s -H "Authorization: Bearer $_COOLIFY" https://deploy.regendevcorp.com/api/v1/applications
+curl -s -H "Authorization: Bearer $_COOLIFY" "$DEPLOY_API_BASE/api/v1/applications"
 ```
 
 If clauth daemon is not responding:
@@ -143,7 +143,7 @@ BLOCKED: clauth daemon not responding. Run scripts\restart-clauth.bat, unlock at
   ```
   Server UUID:     ih386anenvvvn6fy1umtyow0
   Server IP:       64.237.54.189
-  Dashboard:       https://deploy.regendevcorp.com
+  Dashboard:       <deployment-dashboard-url>
   GitHub App UUID: xdmcy60putp5h9j7k4kwg9c3
   ```
 

package/commands/design.md

@@ -15,7 +15,7 @@ Use `skills/design/SKILL.md` as the source of truth.
 
 - Studio, Palette Library, brand-token, theme, component, or live-editor work
 - Any design task that must understand RDC's real token tables and Studio routes
-- UI critique, audit, polish, colorize, type, layout, or craft work in `regen-root`
+- UI critique, audit, polish, colorize, type, layout, or craft work in `{PROJECT_ROOT}`
 - Agent-side color-system exploration using Rampa CLI
 
 ## Arguments

package/commands/overnight.md

@@ -30,13 +30,13 @@ description: >-
 **First action — set the overnight sentinel** so the `no-stop-open-epics` Stop hook engages (interactive sessions are not gated by it):
 
 ```bash
-mkdir -p C:/Dev/regen-root/.rdc && touch C:/Dev/regen-root/.rdc/overnight.lock
+mkdir -p {PROJECT_ROOT}/.rdc && touch {PROJECT_ROOT}/.rdc/overnight.lock
 ```
 
 **Last action at end of run (success OR failure) — remove the sentinel:**
 
 ```bash
-rm -f C:/Dev/regen-root/.rdc/overnight.lock
+rm -f {PROJECT_ROOT}/.rdc/overnight.lock
 ```
 
 If the sentinel file does not exist, the Stop hook will NOT block — which means interactive sessions stop freely and only `rdc:overnight` is held to the "drain the queue" contract.

package/commands/release.md

@@ -1,159 +1,49 @@
 ---
-name: rdc:release
 description: >-
-  Atomic release. Usage `rdc:release <repo> [version]` or `rdc:release <repo> --patch|--minor|--major` or `rdc:release <repo> --dry-run` — bump, commit, tag, push, wait CI, install, verify, restart. Known repos: clauth, rdc-skills, regen-media, gws. No user handoff.
+  Atomic release. Usage `rdc:release <repo> [version]` or `rdc:release <repo> --patch|--minor|--major|--dry-run` — bump, commit, tag, push, wait CI/publish, install, and verify. Uses repo-local release metadata.
 ---
 
+# rdc:release — Generic Release
+
 > **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Checklist-only output. No tool-call narration. No raw git/npm/CI dumps.
+> Checklist-only output. No raw git/npm/CI dumps.
 > One checklist upfront, updated in place, shown again at end with 1-line verdict.
 
-> **Sandbox contract:** This skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls (git tag push, CI poll, npm publish verification, global install, daemon restart) short-circuit under the flag — the checklist still runs, but each destructive step echoes `[RDC_TEST] skipping <step>` instead of mutating external state.
-
-# rdc:release — Atomic LIFEAI Package Release
-
-## Purpose
-
-Dave has Bash access. Therefore Dave should never be asked to run install
-commands. This skill handles the complete release loop for any LIFEAI-published
-package so the user sees one checklist and one verdict, not a series of "now run
-this" handoffs.
-
-## Arguments
-
-- `rdc:release <repo>` — patch bump (default), full loop
-- `rdc:release <repo> <version>` — explicit version (e.g. `1.6.0`)
-- `rdc:release <repo> --minor` | `--major` | `--patch` — semver bump
-- `rdc:release <repo> --dry-run` — show checklist and planned version, do nothing
-- `rdc:release` (no args) — list known repos, ask which
-
-## Known repos
-
-Resolve `<repo>` to source path + install mechanism:
-
-| Repo | Source path | Publish | Install | Post-install |
-|------|-------------|---------|---------|--------------|
-| `clauth` | `C:/Dev/clauth` | npm via tag → GitHub Actions | `npm install -g @lifeaitools/clauth@latest` | `curl -s -X POST http://127.0.0.1:52437/restart` |
-| `rdc-skills` | `C:/Dev/rdc-skills` | local (no npm) | `bash C:/Dev/rdc-skills/scripts/install.sh` + cp fallback | none |
-| `regen-media` | `C:/Dev/regen-root/mcp-servers/regen-media` | local | restart MCP server | none |
-| `gws` | `C:/Dev/regen-root/mcp-servers/gws` | local | restart MCP server | none |
-
-Add new repos to this table as they emerge. If user specifies an unknown repo,
-ask for the source path and install command.
-
-## Checklist (run every mode)
+## Checklist
 
 ```
-rdc:release: <repo> vX.Y.Z → vA.B.C
+rdc:release: <repo> vX.Y.Z -> vA.B.C
 [ ] Source path resolved
-[ ] Working tree clean (git status)
-[ ] Current version detected (package.json)
+[ ] Release metadata read
+[ ] Working tree clean or user-approved dirty scope identified
+[ ] Current version detected
 [ ] New version computed
-[ ] Dry-run gate (if --dry-run, stop here)
-[ ] package.json bumped (all version fields)
+[ ] Dry-run gate handled
+[ ] Version files updated
+[ ] Tests/self-test passed
 [ ] Commit created
-[ ] Tag vA.B.C created
-[ ] Push to origin
-[ ] Push --tags to origin
-[ ] CI run located (gh run list, if applicable)
-[ ] CI completed successfully (poll every 20s, 10min timeout)
-[ ] npm registry shows vA.B.C (if npm package, poll every 15s, 3min timeout)
-[ ] Local install executed
-[ ] Installed version verified matches vA.B.C
-[ ] Post-install action (daemon restart, etc., if applicable)
-[ ] Smoke test (ping health endpoint or binary --version)
-✅ rdc:release <repo>: vA.B.C live and installed
+[ ] Tag created
+[ ] Branch and tag pushed
+[ ] CI/publish status verified
+[ ] Registry/package/deploy target shows vA.B.C, if applicable
+[ ] Local install/update executed, if applicable
+[ ] Installed/runtime version verified
+[ ] Smoke test passed
+✅ rdc:release <repo>: vA.B.C live and verified
 ```
 
-## Execution details (silent to user — don't narrate)
+## Rules
 
-### 1. Version bump
-- Read `package.json`, parse version
-- Apply bump: patch (default), minor, major, or explicit
-- Rewrite all `version` fields (some packages have version in `claude.version` too)
+- Do not release without explicit user authorization.
+- Prefer repo-local release instructions in `.rdc/release.json`, README, package scripts, or CI workflows.
+- Never force push or bypass hooks.
+- Never declare success without verifying the installed or deployed version.
 
-### 2. Commit + tag + push
-```bash
-cd <source_path>
-git add package.json
-git commit -m "chore(release): vA.B.C"
-if [ "$RDC_TEST" != "1" ]; then
-  git tag vA.B.C
-  git push && git push --tags
-else
-  echo "[RDC_TEST] skipping git tag + git push --tags"
-fi
-```
-Never `--no-verify`. Never `--force`. If pre-commit hook fails, fix root cause, don't skip.
+## RDC Skills Package
 
-*Under `$RDC_TEST=1`, sections 3 (CI poll), 4 (npm registry poll), 5 (install), 6 (verify install), 7 (post-install), and 8 (smoke test) are also skipped — echo `[RDC_TEST] skipping <section>` for each and mark the checklist line as `[~]`.*
+After publishing this package to npm, a clean-box install should use:
 
-### 3. CI poll (for repos with GH Actions publish)
 ```bash
-# Locate the run triggered by the tag push
-gh run list --repo LIFEAI/<repo> --limit 5 --json status,conclusion,headBranch,databaseId
-# Poll its status field every 20s until conclusion ∈ {success, failure, cancelled}
-# Max 10 minutes — if timeout, fail with [!] and report run URL
+npm install -g @lifeaitools/rdc-skills@latest
+rdc-skills-install --profile core
 ```
-
-### 4. npm registry poll (only if published to npm)
-```bash
-npm view @lifeaitools/<repo> version
-# Poll every 15s until matches new version
-# Max 3 minutes — usually lands within 30-60s after CI success
-```
-
-### 5. Install
-- **clauth:** `npm install -g @lifeaitools/clauth@latest`
-- **rdc-skills:** `bash C:/Dev/rdc-skills/scripts/install.sh` — if output shows only one file copied (known bug), fall back to `cp C:/Dev/rdc-skills/skills/*.md ~/.claude/skills/user/ && cp C:/Dev/rdc-skills/skills/*.md C:/Dev/regen-root/.claude/skills/user/`
-- **MCP servers:** restart the server process (find its PID, kill, respawn — or document how)
-
-### 6. Verify install
-- **clauth:** `curl -s http://127.0.0.1:52437/ping | jq -r .app_version` — must equal new version
-- **rdc-skills:** `ls ~/.claude/skills/user/rdc-release.md` (or whichever file is new in this release) — must exist
-- **Global npm:** `npm list -g --depth=0 @lifeaitools/<repo>` — version matches
-
-### 7. Post-install
-- **clauth:** `curl -s -X POST http://127.0.0.1:52437/restart` — wait 3s — ping again
-- Others: N/A
-
-### 8. Smoke test
-- **clauth:** new tool roundtrip (e.g., `curl -s http://127.0.0.1:52437/get/openai | head -c 10` succeeds without error)
-- **rdc-skills:** load one new skill file and check frontmatter parses
-- **MCP:** server responds to `tools/list`
-
-## Failure modes → checklist outcome
-
-| Failure | Marker | Next |
-|---------|--------|------|
-| Dirty working tree | `[!]` line 2 | Abort with one-sentence diff summary; ask user to commit or stash |
-| Pre-commit hook fails | `[!]` line 7 | Fix root cause, re-stage, retry (NEVER --no-verify) |
-| CI fails | `[!]` line 11 | Print run URL, tail 20 lines of failing job, ask user |
-| npm doesn't register | `[!]` line 12 | Print npm error, check if CI actually published (not a silent skip) |
-| Install script broken | `[!]` line 13 | Fall back to manual cp; note the installer bug as a task |
-| Version mismatch after install | `[!]` line 14 | Uninstall + clean install; if still wrong, likely cache issue |
-| Post-install restart fails | `[!]` line 15 | Print ping error; instruct user to run `scripts\restart-clauth.bat` manually |
-
-Even on failure, show the full checklist with `[!]` markers so user sees exactly
-where it stopped.
-
-## Dry-run mode
-
-Prints the checklist + resolved version bump + every command that WOULD run, but
-executes nothing beyond reads. Use when user says "what would you do" or before
-risky major bumps.
-
-## Never
-
-- Never release on behalf of the user without an explicit `rdc:release` invocation
-- Never skip CI verification ("it'll probably work" is how stale installs happen)
-- Never `--force` push, never `--no-verify`, never `--no-gpg-sign`
-- Never touch `main` — release tags go on the default branch the repo uses (`master` for clauth, rdc-skills)
-- Never declare success without verifying the installed version matches
-
-## Related
-
-- `.claude/rules/clauth.md` — clauth release workflow source of truth
-- `feedback_version_bump_must_tag.md` (memory) — never bump without tagging
-- `feedback_clauth_ci.md` (memory) — CI publish pattern
-- `feedback_just_do_it.md` (memory) — don't hand commands to Dave; run them

package/commands/self-test.md

@@ -29,7 +29,7 @@ description: >-
 
 1. **Run the linter:**
    ```bash
-   node C:/Dev/rdc-skills/scripts/self-test.mjs
+   node {RDC_SKILLS_ROOT}/scripts/self-test.mjs
    ```
 
 2. **Interpret exit codes:**

package/commands/watch.md

@@ -24,7 +24,7 @@ description: >-
    ```bash
    node ${CLAUDE_PLUGIN_ROOT}/scripts/watch-init.mjs
    ```
-   (If `CLAUDE_PLUGIN_ROOT` is not set, resolve the plugin path from your invocation context. On Windows it's typically `C:/Dev/rdc-skills`.)
+   (If `CLAUDE_PLUGIN_ROOT` is not set, resolve the plugin path from your invocation context or the installed plugin cache.)
 
 2. **Parse the output.** The script prints `run_id`, `log_path`, `current`, `viewer`, and `open_hint`. Capture `log_path` and `viewer` for the rest of the session.
 

package/guides/agent-bootstrap.md

@@ -137,7 +137,7 @@ When `RDC_TEST=1` is set, the skill is running inside the Tier 2 sandbox harness
 **Bash pattern:**
 ```bash
 if [ "$RDC_TEST" != "1" ]; then
-  curl -X POST "https://deploy.regendevcorp.com/api/v1/applications/$UUID/deploy" ...
+  curl -X POST "$DEPLOY_API_BASE/api/v1/applications/$UUID/deploy" ...
 else
   echo "[RDC_TEST] skipping Coolify deploy"
 fi
@@ -156,7 +156,7 @@ if (process.env.RDC_TEST !== '1') {
 
 **New-skill contract:** every new `rdc:*` skill MUST honor `RDC_TEST` before shipping. Tier 2 manifests will fail any skill that writes to external state under the flag.
 
-**Known blocker:** The `check-cwd.js` SessionStart hook hard-blocks Claude sessions launched from `C:/Dev/rdc-skills`. The hook must check `process.env.RDC_TEST === '1'` and call `process.exit(0)` early to allow Tier 2 sandbox runs. Without this bypass, all Tier 2 headless invocations fail with `exit_code: -1`. File: `~/.claude/hooks/check-cwd.js`.
+**Known blocker:** Project-specific cwd hooks must check `process.env.RDC_TEST === '1'` and call `process.exit(0)` early to allow Tier 2 sandbox runs. Without this bypass, headless self-test invocations can fail before the skill loads. File: `~/.claude/hooks/check-cwd.js`.
 
 ---
 

package/hooks/check-cwd.js

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
-// Hard blocks session if CWD is not the regen-root project directory.
+// Hard blocks session if CWD is not the expected project directory.
 // Exits with code 1 to fail the hook + outputs a blocking systemMessage.
 
 const { execSync } = require('child_process');
 const hookLog = require('./hook-logger');
 const cwd     = process.cwd().replace(/\\/g, '/');
 
-let expected = 'regen-root';
+let expected = process.env.RDC_PROJECT_SCOPE || 'regen-root';
 try {
   expected = execSync('git rev-parse --show-toplevel', { encoding: 'utf8', stdio: 'pipe' })
     .trim().replace(/\\/g, '/');
 } catch (_) {}
 
-if (!cwd.endsWith('regen-root')) {
+if (!cwd.endsWith(expected)) {
   hookLog('check-cwd', 'SessionStart', 'block', { cwd, expected });
   process.stdout.write(JSON.stringify({
     systemMessage:

package/hooks/no-stop-open-epics.js

@@ -5,7 +5,7 @@
  * Fires on every Stop event where Claude decided to end_turn.
  * Queries get_open_epics() via Supabase REST.
  * Only blocks if epics with status=todo exist — in_progress means another session owns them.
- * Only fires in the regen-root project (scope guard on event.cwd).
+ * Only fires in the configured project scope (scope guard on event.cwd).
  *
  * Exit codes:
  *   0 = allow stop
@@ -15,8 +15,9 @@
  *   NEXT_PUBLIC_SUPABASE_URL=https://<ref>.supabase.co
  *   NEXT_PUBLIC_SUPABASE_ANON_KEY=<key>
  *
- * PROJECT SCOPE in package.json or plugin config:
- *   "hookScope": "regen-root"   ← folder name that must appear in event.cwd
+ * PROJECT SCOPE:
+ *   RDC_PROJECT_SCOPE=<folder-name>   folder name that must appear in event.cwd
+ *   RDC_PROJECT_ROOT=<path>           root used to find .rdc/overnight.lock and .env.local
  */
 
 const fs = require('fs');
@@ -24,11 +25,12 @@ const path = require('path');
 
 // ── Config — override these per project ──────────────────────────────────────
 
-const PROJECT_SCOPE = 'regen-root'; // only block in sessions inside this folder name
-const OVERNIGHT_SENTINEL = 'C:/Dev/regen-root/.rdc/overnight.lock'; // only fire when this exists
+const PROJECT_SCOPE = process.env.RDC_PROJECT_SCOPE || 'regen-root'; // LIFEAI default; override per project
+const PROJECT_ROOT = process.env.RDC_PROJECT_ROOT || process.cwd();
+const OVERNIGHT_SENTINEL = process.env.RDC_OVERNIGHT_LOCK || path.join(PROJECT_ROOT, '.rdc', 'overnight.lock');
 const ENV_PATHS = [
-  'C:/Dev/regen-root/apps/rdc-marketing-engine/.env.local',
-  'C:/Dev/regen-root/.env.local',
+  ...(process.env.RDC_ENV_PATHS ? process.env.RDC_ENV_PATHS.split(path.delimiter) : []),
+  path.join(PROJECT_ROOT, '.env.local'),
 ];
 const SUPABASE_URL = process.env.SUPABASE_URL || readEnvVar('NEXT_PUBLIC_SUPABASE_URL');
 

package/hooks/rdc-invocation-marker.js

@@ -76,7 +76,7 @@ function detectRdc(raw) {
 
   if (event === 'UserPromptSubmit') {
     const prompt = String(raw.prompt || '').trim();
-    const m = prompt.match(/^\/(?:rdc[:-])?([a-z][a-z0-9-]*)\b/i);
+    const m = prompt.match(/^\/rdc[:-]([a-z][a-z0-9-]*)\b/i);
     if (!m) return null;
     const command = normalizeCommandName(m[1]);
     if (RDC_COMMANDS.has(command)) return command;
@@ -87,6 +87,20 @@ function detectRdc(raw) {
 
 function writeMarker(raw, command) {
   fs.mkdirSync(markerDir(), { recursive: true });
+  const p = markerPath(raw.session_id);
+  if (fs.existsSync(p)) {
+    try {
+      const existing = JSON.parse(fs.readFileSync(p, 'utf8'));
+      const started = Date.parse(existing.started_at || '');
+      const isRecentDuplicate = Number.isFinite(started) &&
+        Date.now() - started <= 1000 &&
+        existing.session_id === (raw.session_id || null) &&
+        existing.command === command;
+      if (isRecentDuplicate) {
+        return { ...existing, deduped: true };
+      }
+    } catch {}
+  }
   const marker = {
     session_id: raw.session_id || null,
     command,
@@ -98,7 +112,7 @@ function writeMarker(raw, command) {
     started_at: new Date().toISOString(),
     hook_event_name: raw.hook_event_name || null,
   };
-  fs.writeFileSync(markerPath(raw.session_id), JSON.stringify(marker, null, 2));
+  fs.writeFileSync(p, JSON.stringify(marker, null, 2));
   return marker;
 }
 
@@ -127,7 +141,7 @@ async function main() {
 
   try {
     const marker = writeMarker(raw, command);
-    hookLog('rdc-invocation-marker', raw.hook_event_name || 'unknown', 'marked', {
+    hookLog('rdc-invocation-marker', raw.hook_event_name || 'unknown', marker.deduped ? 'deduped' : 'marked', {
       command,
       session_id: marker.session_id,
     });

package/hooks/rdc-output-contract-gate.js

@@ -60,6 +60,14 @@ function pass(marker) {
   process.exit(0);
 }
 
+function passReentry(marker) {
+  try { fs.unlinkSync(marker.path); } catch {}
+  hookLog('rdc-output-contract-gate', 'Stop', 'pass-reentry', {
+    command: marker.data.command || null,
+  });
+  process.exit(0);
+}
+
 async function main() {
   let raw;
   try { raw = JSON.parse(await readStdin()); } catch { process.exit(0); }
@@ -70,6 +78,7 @@ async function main() {
   const checklist = hasChecklist(message);
   const verdict = hasVerdict(message);
   if (checklist && verdict) pass(marker);
+  if (raw.stop_hook_active === true) passReentry(marker);
 
   const command = marker.data.command || 'rdc';
   const missing = [];

package/hooks/require-work-item-on-commit.js

@@ -18,10 +18,11 @@
 
 const fs      = require('fs');
 const path    = require('path');
+const os      = require('os');
 const hookLog = require('./hook-logger');
 
 const MARKER_FILE = path.join(
-  process.env.USERPROFILE || process.env.HOME || 'C:/Users/DaveLadouceur',
+  process.env.USERPROFILE || process.env.HOME || os.homedir(),
   '.claude',
   'fixit.marker'
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/rdc-skills",
-  "version": "0.9.36",
+  "version": "0.9.38",
   "description": "RDC typed-agent dispatch skill suite for Claude Code - plan, build, review, overnight builds",
   "keywords": [
     "claude-code",
@@ -19,14 +19,19 @@
     "type": "plugin",
     "skills": "skills/",
     "guides": "guides/",
-    "version": "0.9.36",
+    "version": "0.9.38",
     "commands": "commands/"
   },
+  "bin": {
+    "rdc-skills-install": "scripts/install-rdc-skills.js",
+    "rdc-skills-self-test": "scripts/self-test.mjs"
+  },
   "scripts": {
     "install-rdc-skills": "node scripts/install-rdc-skills.js",
     "uninstall:win": "powershell -ExecutionPolicy Bypass -File scripts/uninstall.ps1",
     "uninstall:unix": "bash scripts/uninstall.sh",
     "validate": "node tests/validate-skills.js",
-    "rdc-design": "node scripts/rdc-design-cli.mjs"
+    "rdc-design": "node scripts/rdc-design-cli.mjs",
+    "test:hooks": "node scripts/test-rdc-hooks.mjs"
   }
 }

package/scripts/install-rdc-skills.js

@@ -766,8 +766,12 @@ async function main() {
   console.log('');
 
   if (!fs.existsSync(claudeHome)) {
-    fail(`CLAUDE_HOME not found: ${claudeHome}`);
-    process.exit(1);
+    fs.mkdirSync(claudeHome, { recursive: true });
+    warn(`CLAUDE_HOME did not exist — created ${claudeHome}`);
+  }
+  if (!fs.existsSync(settingsPath)) {
+    writeJson(settingsPath, {});
+    info(`       created settings.json`);
   }
 
   // Read version + git SHA once

package/scripts/self-test.mjs

@@ -31,6 +31,7 @@
 import { readFileSync, readdirSync, existsSync, writeFileSync, appendFileSync, renameSync, mkdirSync, statSync } from "node:fs";
 import { join, basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
 import { loadAllManifests } from "./lib/manifest-schema.mjs";
 import { runManifest } from "./lib/runner.mjs";
 import {
@@ -802,6 +803,19 @@ function auditRequiredHookWiring() {
   return findings;
 }
 
+function runHookBehaviorTests() {
+  const result = spawnSync(process.execPath, [join(REPO_ROOT, "scripts", "test-rdc-hooks.mjs")], {
+    cwd: REPO_ROOT,
+    encoding: "utf8",
+  });
+  return {
+    ok: result.status === 0,
+    status: result.status,
+    stdout: (result.stdout || "").trim(),
+    stderr: (result.stderr || "").trim(),
+  };
+}
+
 // ─── Tier 2 behavioral runner ──────────────────────────────────────────────
 
 async function runPool(items, concurrency, worker) {
@@ -1038,6 +1052,7 @@ function main() {
     }
 
     const guideValidatorResultJson = !ONLY_SKILL ? runGuideContentValidator() : null;
+    const hookBehaviorResultJson = !ONLY_SKILL ? runHookBehaviorTests() : null;
 
     const failed = results.filter((r) => r.errors.length > 0);
     const warned = results.filter((r) => r.warnings.length > 0 && r.errors.length === 0);
@@ -1050,6 +1065,11 @@ function main() {
       ...duplicateFindings.filter((f) => f.level === "error"),
       ...orphanHookFindings.filter((f) => f.level === "error"),
       ...(guideValidatorResultJson ? guideValidatorResultJson.errors : []),
+      ...(hookBehaviorResultJson && !hookBehaviorResultJson.ok ? [{
+        level: "error",
+        code: "hook-behavior-test-failed",
+        message: hookBehaviorResultJson.stderr || hookBehaviorResultJson.stdout || `exit ${hookBehaviorResultJson.status}`,
+      }] : []),
     ];
     const globalWarnings = [
       ...manifestAudit.findings.filter((f) => f.level === "warn"),
@@ -1092,6 +1112,7 @@ function main() {
                 findings: guideValidatorResultJson.findings,
               }
             : null,
+          hook_behavior_tests: hookBehaviorResultJson,
           results: results.map((r) => ({
             skill: r.skill,
             file: r.file,
@@ -1217,10 +1238,12 @@ function main() {
   let duplicateFindings = [];
   let orphanHookFindings = [];
   let requiredHookFindings = [];
+  let hookBehaviorResult = null;
   if (!ONLY_SKILL) {
     duplicateFindings = auditDuplicates(results);
     orphanHookFindings = auditOrphanHooks(results);
     requiredHookFindings = auditRequiredHookWiring();
+    hookBehaviorResult = runHookBehaviorTests();
   }
 
   if (duplicateFindings.length + orphanHookFindings.length + requiredHookFindings.length > 0) {
@@ -1230,6 +1253,14 @@ function main() {
     }
   }
 
+  if (hookBehaviorResult) {
+    console.log("\nhook behavior tests\n");
+    console.log("─".repeat(80));
+    console.log(hookBehaviorResult.ok ? "  pass  rdc marker/gate behavioral smoke tests" : "  FAIL  rdc marker/gate behavioral smoke tests");
+    if (hookBehaviorResult.stdout) console.log(`  ${hookBehaviorResult.stdout}`);
+    if (hookBehaviorResult.stderr) console.log(`  ${hookBehaviorResult.stderr}`);
+  }
+
   if (FIXED_FILES.length > 0) {
     console.log("\nfixed files (review with git diff):");
     for (const p of FIXED_FILES) console.log(`  ${p}`);
@@ -1243,6 +1274,11 @@ function main() {
     ...orphanHookFindings.filter((f) => f.level === "error"),
     ...requiredHookFindings.filter((f) => f.level === "error"),
     ...(guideValidatorResult ? guideValidatorResult.errors : []),
+    ...(hookBehaviorResult && !hookBehaviorResult.ok ? [{
+      level: "error",
+      code: "hook-behavior-test-failed",
+      message: hookBehaviorResult.stderr || hookBehaviorResult.stdout || `exit ${hookBehaviorResult.status}`,
+    }] : []),
   ];
   const globalWarnings = [
     ...manifestAudit.findings.filter((f) => f.level === "warn"),