@lifeaitools/rdc-skills 0.9.32 → 0.9.34

package/hooks/work-item-exit-gate.js

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse hook — hard-stop unsafe work item exit transitions.
+ *
+ * This gate runs before tool calls and blocks legacy or supervisor-mutated
+ * CodeFlow/work-item close patterns before they reach Supabase. The database
+ * remains the final authority; this hook gives agents an immediate stop sign.
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const hookLog = require('./hook-logger');
+
+const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+const DEFAULT_SUPABASE_URL = 'https://uvojezuorjgqzmhhgluu.supabase.co';
+const EVENT_LOG = path.join(os.homedir(), '.claude', 'work-item-checklist-events.jsonl');
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let input = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', () => resolve(input));
+    process.stdin.resume();
+  });
+}
+
+function block(message, details = {}) {
+  hookLog('work-item-exit-gate', 'PreToolUse', 'block', details);
+  process.stdout.write(JSON.stringify({
+    systemMessage: `HARD BLOCK — Work item exit gate rejected this tool call.\n\n${message}`,
+  }));
+  process.exit(1);
+}
+
+function pass(details = {}) {
+  hookLog('work-item-exit-gate', 'PreToolUse', 'pass', details);
+  process.exit(0);
+}
+
+function stringifyTool(toolInput) {
+  if (typeof toolInput === 'string') return toolInput;
+  try { return JSON.stringify(toolInput); } catch { return ''; }
+}
+
+function stripCasts(value) {
+  return String(value || '')
+    .replace(/::\s*[a-z_][\w.]*/gi, '')
+    .trim();
+}
+
+function unquote(value) {
+  const v = stripCasts(value);
+  const m = v.match(/^'(.*)'$/s) || v.match(/^"(.*)"$/s);
+  return (m ? m[1] : v).replace(/''/g, "'").trim();
+}
+
+function getNamedArg(text, name) {
+  const re = new RegExp(`${name}\\s*:?=\\s*('(?:''|[^'])*'|"(?:\\\\"|[^"])*"|true|false|null|[0-9a-f-]{36})`, 'i');
+  const m = text.match(re);
+  return m ? unquote(m[1]) : null;
+}
+
+function splitArgs(argsText) {
+  const args = [];
+  let current = '';
+  let quote = null;
+  let depth = 0;
+  for (let i = 0; i < argsText.length; i++) {
+    const ch = argsText[i];
+    const next = argsText[i + 1];
+    if (quote) {
+      current += ch;
+      if (ch === quote && !(quote === "'" && next === "'")) quote = null;
+      else if (ch === "'" && next === "'") current += argsText[++i];
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch;
+      current += ch;
+      continue;
+    }
+    if (ch === '(' || ch === '[' || ch === '{') depth++;
+    if (ch === ')' || ch === ']' || ch === '}') depth = Math.max(0, depth - 1);
+    if (ch === ',' && depth === 0) {
+      args.push(current.trim());
+      current = '';
+      continue;
+    }
+    current += ch;
+  }
+  if (current.trim()) args.push(current.trim());
+  return args;
+}
+
+function findCall(text, name) {
+  const idx = text.toLowerCase().indexOf(name.toLowerCase());
+  if (idx < 0) return null;
+  const open = text.indexOf('(', idx + name.length);
+  if (open < 0) return null;
+  let quote = null;
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    const next = text[i + 1];
+    if (quote) {
+      if (ch === quote && !(quote === "'" && next === "'")) quote = null;
+      else if (ch === "'" && next === "'") i++;
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch;
+      continue;
+    }
+    if (ch === '(') depth++;
+    if (ch === ')') {
+      depth--;
+      if (depth === 0) return text.slice(open + 1, i);
+    }
+  }
+  return null;
+}
+
+function objectArg(blob, name) {
+  const re = new RegExp(`"${name}"\\s*:\\s*("([^"]*)"|true|false|null)`, 'i');
+  const m = blob.match(re);
+  if (!m) return null;
+  if (m[1] === 'true' || m[1] === 'false' || m[1] === 'null') return m[1];
+  return m[2] || null;
+}
+
+function extractStatusCall(blob) {
+  if (!/update_work_item_status/i.test(blob)) return null;
+  const call = findCall(blob, 'update_work_item_status');
+  const args = call ? splitArgs(call) : [];
+  return {
+    id: objectArg(blob, 'p_id') || getNamedArg(blob, 'p_id') || unquote(args[0] || '').match(UUID_RE)?.[0] || blob.match(UUID_RE)?.[0] || null,
+    status: objectArg(blob, 'p_status') || getNamedArg(blob, 'p_status') || unquote(args[1] || ''),
+    actorSessionId: objectArg(blob, 'p_actor_session_id') || getNamedArg(blob, 'p_actor_session_id') || unquote(args[3] || ''),
+    actorRole: objectArg(blob, 'p_actor_role') || getNamedArg(blob, 'p_actor_role') || unquote(args[4] || ''),
+  };
+}
+
+function extractTickCall(blob) {
+  if (!/update_checklist_item/i.test(blob)) return null;
+  const call = findCall(blob, 'update_checklist_item');
+  const args = call ? splitArgs(call) : [];
+  return {
+    workItemId: objectArg(blob, 'p_work_item_id') || getNamedArg(blob, 'p_work_item_id') || unquote(args[0] || '').match(UUID_RE)?.[0] || blob.match(UUID_RE)?.[0] || null,
+    itemId: objectArg(blob, 'p_item_id') || getNamedArg(blob, 'p_item_id') || unquote(args[1] || ''),
+    checked: (objectArg(blob, 'p_checked') || getNamedArg(blob, 'p_checked') || unquote(args[2] || '')).toLowerCase() === 'true',
+    actorSessionId: objectArg(blob, 'p_actor_session_id') || getNamedArg(blob, 'p_actor_session_id') || unquote(args[3] || ''),
+    actorRole: objectArg(blob, 'p_actor_role') || getNamedArg(blob, 'p_actor_role') || unquote(args[4] || ''),
+  };
+}
+
+function logTick(tick, rawTool) {
+  try {
+    fs.mkdirSync(path.dirname(EVENT_LOG), { recursive: true });
+    fs.appendFileSync(EVENT_LOG, JSON.stringify({
+      ts: new Date().toISOString(),
+      work_item_id: tick.workItemId || null,
+      item_id: tick.itemId || null,
+      checked: tick.checked,
+      actor_session_id: tick.actorSessionId || null,
+      actor_role: tick.actorRole || null,
+      tool_name: rawTool.tool_name || null,
+    }) + '\n');
+  } catch (_) {}
+}
+
+async function getServiceKey() {
+  if (process.env.SUPABASE_SERVICE_ROLE_KEY) return process.env.SUPABASE_SERVICE_ROLE_KEY;
+  if (process.env.SUPABASE_SERVICE_KEY) return process.env.SUPABASE_SERVICE_KEY;
+  for (const endpoint of ['supabase-service', 'supabase-service-role']) {
+    try {
+      const res = await fetch(`http://127.0.0.1:52437/v/${endpoint}`, { signal: AbortSignal.timeout(2000) });
+      if (res.ok) {
+        const text = (await res.text()).trim();
+        if (text && !text.startsWith('{')) return text;
+      }
+    } catch (_) {}
+  }
+  return null;
+}
+
+async function supabaseGet(pathname) {
+  const key = await getServiceKey();
+  if (!key) throw new Error('clauth/env did not provide a Supabase service key');
+  const base = (process.env.SUPABASE_URL || process.env.NEXT_PUBLIC_SUPABASE_URL || DEFAULT_SUPABASE_URL).replace(/\/$/, '');
+  const res = await fetch(`${base}/rest/v1/${pathname}`, {
+    headers: {
+      apikey: key,
+      Authorization: `Bearer ${key}`,
+      Accept: 'application/json',
+    },
+    signal: AbortSignal.timeout(3500),
+  });
+  if (!res.ok) throw new Error(`Supabase verification HTTP ${res.status}`);
+  return res.json();
+}
+
+function requiredItems(checklist) {
+  return Array.isArray(checklist)
+    ? checklist.filter((item) => item && item.required === true)
+    : [];
+}
+
+async function verifyDone(statusCall, blob) {
+  if (!statusCall.id) block('`update_work_item_status(..., done)` must include a work item UUID.', statusCall);
+  if (!statusCall.actorSessionId || !statusCall.actorRole) {
+    block('`done` requires the 5-argument RPC shape with `p_actor_session_id` and `p_actor_role`.', statusCall);
+  }
+  if (statusCall.actorRole !== 'validator') {
+    block('Only a validator may transition a non-epic work item to `done`; implementation agents move work to `review`.', statusCall);
+  }
+  if (/submit_implementation_report/i.test(blob)) {
+    block('Submit the implementation report in a separate tool call before `done`; the gate verifies committed DB state.', statusCall);
+  }
+
+  let rows;
+  let events;
+  try {
+    rows = await supabaseGet(`work_items?id=eq.${encodeURIComponent(statusCall.id)}&select=id,status,item_type,implementation_report,checklist`);
+    events = await supabaseGet(`work_item_checklist_events?work_item_id=eq.${encodeURIComponent(statusCall.id)}&select=item_id,checked,actor_session_id,actor_role,created_at&order=created_at.desc&limit=200`);
+  } catch (e) {
+    block(`Cannot live-verify work item exit gate: ${e.message}. Do not close the item until clauth/Supabase verification is available.`, statusCall);
+  }
+
+  const item = rows && rows[0];
+  if (!item) block(`Work item ${statusCall.id} was not found.`, statusCall);
+  if (item.item_type === 'epic') return;
+  if (item.status !== 'review') block('Non-epic work items must be in `review` before a validator may mark them `done`.', { ...statusCall, currentStatus: item.status });
+
+  const report = item.implementation_report;
+  if (!report || typeof report !== 'object') block('`done` rejected because `implementation_report` is null or not an object.', statusCall);
+  if (!report.codeflow_post || typeof report.codeflow_post !== 'object') block('`done` rejected because `implementation_report.codeflow_post` is missing.', statusCall);
+
+  const missing = requiredItems(item.checklist).filter((ci) => ci.checked !== true);
+  if (missing.length > 0) {
+    block(`Required checklist items are unchecked: ${missing.map((ci) => ci.id || ci.text || '<unknown>').join(', ')}`, statusCall);
+  }
+
+  const latestByItem = new Map();
+  for (const event of Array.isArray(events) ? events : []) {
+    if (!latestByItem.has(event.item_id)) latestByItem.set(event.item_id, event);
+  }
+  const supervisorReticks = requiredItems(item.checklist)
+    .map((ci) => latestByItem.get(ci.id))
+    .filter((event) => event && event.checked === true && event.actor_role !== 'agent');
+  if (supervisorReticks.length > 0) {
+    block(
+      `Required checklist items were last ticked by a non-agent session: ${supervisorReticks.map((e) => e.item_id).join(', ')}`,
+      { ...statusCall, supervisorReticks: supervisorReticks.map((e) => e.item_id) },
+    );
+  }
+}
+
+function validateTick(tick, rawTool) {
+  logTick(tick, rawTool);
+  if (!tick.checked) return;
+  if (!tick.workItemId || !tick.itemId) {
+    block('Checklist ticks must include `p_work_item_id` and `p_item_id`.', tick);
+  }
+  if (!tick.actorSessionId) {
+    block('Checklist ticks must include `p_actor_session_id`; unaudited ticks are rejected.', tick);
+  }
+  if (tick.actorRole !== 'agent') {
+    block('Only the originating implementation agent may tick required checklist evidence. Supervisors/validators reopen or review; they do not re-tick.', tick);
+  }
+}
+
+async function main() {
+  let raw;
+  try { raw = JSON.parse(await readStdin()); } catch { process.exit(0); }
+
+  const blob = stringifyTool(raw.tool_input || raw);
+  const tick = extractTickCall(blob);
+  if (tick) validateTick(tick, raw);
+
+  const statusCall = extractStatusCall(blob);
+  if (!statusCall) pass({ reason: 'no-status-call' });
+
+  const status = String(statusCall.status || '').toLowerCase();
+  if (status === 'review' && (!statusCall.actorSessionId || statusCall.actorRole !== 'agent')) {
+    block('Implementation agents must move completed work to `review` with `p_actor_session_id` and `p_actor_role := agent`.', statusCall);
+  }
+  if (status === 'done') {
+    await verifyDone(statusCall, blob);
+  }
+
+  pass({ status });
+}
+
+main().catch((e) => block(`Exit gate crashed: ${e.message}`));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lifeaitools/rdc-skills",
-  "version": "0.9.32",
-  "description": "RDC typed-agent dispatch skill suite for Claude Code — plan, build, review, overnight builds",
+  "version": "0.9.34",
+  "description": "RDC typed-agent dispatch skill suite for Claude Code - plan, build, review, overnight builds",
   "keywords": [
     "claude-code",
     "claude-code-plugin",
@@ -19,7 +19,7 @@
     "type": "plugin",
     "skills": "skills/",
     "guides": "guides/",
-    "version": "0.9.26",
+    "version": "0.9.34",
     "commands": "commands/"
   },
   "scripts": {

package/rules/work-items-rpc.md

@@ -135,6 +135,10 @@ const { data } = await supabase.rpc('insert_work_item', {
 
 Transition a work item's status. Auto-manages `completed_at`.
 
+**Hard gate:** implementation agents do not set non-epic work directly to `done`.
+They submit a report and move the item to `review`. A validator closes it as
+`done` only after fresh verification.
+
 **Supabase SQL:**
 ```sql
 SELECT update_work_item_status(
@@ -142,10 +146,20 @@ SELECT update_work_item_status(
   'in_progress'
 );
 
+SELECT update_work_item_status(
+  'work-item-uuid'::uuid,
+  'review',
+  '["Implementation complete; ready for validator"]'::jsonb,
+  'agent-session-id',
+  'agent'
+);
+
 SELECT update_work_item_status(
   'work-item-uuid'::uuid,
   'done',
-  '["Completed by agent session xyz"]'::jsonb
+  '["Validator verified implementation report, CodeFlow post, and checklist evidence"]'::jsonb,
+  'validator-session-id',
+  'validator'
 );
 ```
 
@@ -156,10 +170,20 @@ const { data } = await supabase.rpc('update_work_item_status', {
   p_status: 'in_progress'
 });
 
+const { data } = await supabase.rpc('update_work_item_status', {
+  p_id: itemId,
+  p_status: 'review',
+  p_notes_append: ['Implementation complete; ready for validator'],
+  p_actor_session_id: agentSessionId,
+  p_actor_role: 'agent'
+});
+
 const { data } = await supabase.rpc('update_work_item_status', {
   p_id: itemId,
   p_status: 'done',
-  p_notes_append: ['Completed by agent session xyz']
+  p_notes_append: ['Validator verified implementation report, CodeFlow post, and checklist evidence'],
+  p_actor_session_id: validatorSessionId,
+  p_actor_role: 'validator'
 });
 ```
 
@@ -170,10 +194,13 @@ const { data } = await supabase.rpc('update_work_item_status', {
 | `p_id` | uuid | yes | work_item ID |
 | `p_status` | text | yes | One of: `todo`, `in_progress`, `blocked`, `review`, `done`, `archived` |
 | `p_notes_append` | jsonb | no | Array of strings appended to existing notes |
+| `p_actor_session_id` | text | review/done | Current agent or validator session ID |
+| `p_actor_role` | text | review/done | `agent` for `review`, `validator` for `done` |
 
 **Behavior:**
 - Setting `done` auto-sets `completed_at = now()`
-- Setting `done` raises EXCEPTION if any `required: true` checklist item has `checked: false` — DoD gate
+- Setting non-epic work to `review` raises EXCEPTION unless `implementation_report.codeflow_post` exists and caller role is `agent`
+- Setting non-epic work to `done` raises EXCEPTION unless current status is `review`, caller role is `validator`, `implementation_report.codeflow_post` exists, every required checklist item is checked, and required checklist evidence was ticked by the originating agent session
 - Setting `todo`, `in_progress`, `blocked`, or `review` clears `completed_at`
 - `updated_at` always refreshed to current timestamp
 - Raises exception if ID not found
@@ -190,7 +217,10 @@ const { data } = await supabase.rpc('update_work_item_status', {
 SELECT update_checklist_item(
   'work-item-uuid'::uuid,
   'tsc-clean',   -- string id of the checklist item
-  true           -- checked state
+  true,          -- checked state
+  'agent-session-id',
+  'agent',
+  'rpc'
 );
 ```
 
@@ -201,8 +231,13 @@ SELECT update_checklist_item(
 | `p_work_item_id` | uuid | yes | the work item ID |
 | `p_item_id` | text | yes | the `id` field of the checklist item |
 | `p_checked` | boolean | yes | `true` = checked, `false` = unchecked |
+| `p_actor_session_id` | text | yes for checked=true | originating implementation agent session ID |
+| `p_actor_role` | text | yes for checked=true | must be `agent` for completion evidence ticks |
+| `p_event_source` | text | no | source label, default `rpc` |
 
 Call this as each checklist item is completed — not all at once at the end.
+The tick is written to `work_item_checklist_events`; supervisor or validator
+re-ticks are rejected by the exit gate.
 
 **Returns:** updated checklist JSONB array.
 
@@ -210,7 +245,7 @@ Call this as each checklist item is completed — not all at once at the end.
 
 ### 5. submit_implementation_report — File agent completion narrative
 
-MUST be called BEFORE `update_work_item_status('done')`.
+MUST be called BEFORE `update_work_item_status(..., 'review', ...)`.
 
 **Supabase SQL:**
 ```sql
@@ -222,7 +257,14 @@ SELECT submit_implementation_report(
     "deviations": [],
     "uncertainty": [],
     "detail": "Full narrative",
-    "flags": []
+    "flags": [],
+    "codeflow_post": {
+      "agent_session_id": "agent-session-id",
+      "summary": "What changed and why",
+      "files_changed": ["path/to/file"],
+      "verification": ["command or evidence"],
+      "commit": "optional commit hash"
+    }
   }'::jsonb
 );
 ```
@@ -244,7 +286,14 @@ SELECT submit_implementation_report(
   "deviations": ["string — deviation from plan", "..."],
   "uncertainty": ["string — anything unclear", "..."],
   "detail": "string — full narrative",
-  "flags": ["string — supervisor attention needed", "..."]
+  "flags": ["string — supervisor attention needed", "..."],
+  "codeflow_post": {
+    "agent_session_id": "string — originating implementation session",
+    "summary": "string — agent-authored CodeFlow post",
+    "files_changed": ["string", "..."],
+    "verification": ["string", "..."],
+    "commit": "string — optional"
+  }
 }
 ```
 

package/scripts/install-rdc-skills.js

@@ -77,6 +77,18 @@ function copyDir(src, dst, ext) {
   return count;
 }
 
+function copyHookFiles(src, dst) {
+  if (!fs.existsSync(src)) { warn(`Source not found: ${src}`); return 0; }
+  fs.mkdirSync(dst, { recursive: true });
+  const files = fs.readdirSync(src).filter(f => /\.(?:js|ps1)$/i.test(f));
+  let count = 0;
+  for (const f of files) {
+    const s = path.join(src, f);
+    if (fs.statSync(s).isFile()) { fs.copyFileSync(s, path.join(dst, f)); count++; }
+  }
+  return count;
+}
+
 function copyDirRecursive(src, dst) {
   if (!fs.existsSync(src)) return;
   fs.mkdirSync(dst, { recursive: true });
@@ -88,6 +100,22 @@ function copyDirRecursive(src, dst) {
   }
 }
 
+function copyMissingProjectGuides(projectRoot) {
+  if (!projectRoot) return 0;
+  const src = path.join(repoRoot, 'guides');
+  const dst = path.join(projectRoot, '.rdc', 'guides');
+  if (!fs.existsSync(src) || !fs.existsSync(dst)) return 0;
+  let copied = 0;
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    const target = path.join(dst, entry.name);
+    if (fs.existsSync(target)) continue;
+    fs.copyFileSync(path.join(src, entry.name), target);
+    copied++;
+  }
+  return copied;
+}
+
 function readJson(p, fallback = {}) {
   if (!fs.existsSync(p)) return fallback;
   try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return fallback; }
@@ -214,6 +242,29 @@ function cleanStaleHooks(hooksDstDir) {
   return removed;
 }
 
+// Project-local hookify docs were a temporary workaround for work item exit
+// enforcement. The plugin hook is now authoritative, so installs clean those
+// local shims from known RDC workspaces instead of leaving two gates to drift.
+function cleanProjectHookifyShims(projectRoot) {
+  if (!projectRoot) return 0;
+  const hookifyDir = path.join(projectRoot, '.claude');
+  if (!fs.existsSync(hookifyDir)) return 0;
+  const stale = [
+    'hookify.work-item-done-gate-bash.local.md',
+    'hookify.work-item-done-gate-mcp.local.md',
+    'hookify.work-item-review-gate-bash.local.md',
+    'hookify.work-item-review-gate-mcp.local.md',
+  ];
+  let removed = 0;
+  for (const f of stale) {
+    const p = path.join(hookifyDir, f);
+    if (fs.existsSync(p)) {
+      try { fs.unlinkSync(p); removed++; } catch {}
+    }
+  }
+  return removed;
+}
+
 // ── Cache flush helper ────────────────────────────────────────────────────────
 // Only `latest/` is ever kept. Earlier versions wrote BOTH `<version>/` and
 // `latest/`, which caused the plugin loader to scan and register every rdc:*
@@ -479,7 +530,7 @@ function buildZip(version) {
         ? 'C:\\Program Files\\PowerShell\\7\\pwsh.exe'
         : 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe';
       execSync(
-        `"${psExe}" -NoProfile -Command "Compress-Archive -Path '${tmp}\\*' -DestinationPath '${zipPath}' -Force"`,
+        `"${psExe}" -NoProfile -NonInteractive -WindowStyle Hidden -Command "Compress-Archive -Path '${tmp}\\*' -DestinationPath '${zipPath}' -Force"`,
         { stdio: 'pipe' }
       );
       fs.rmSync(tmp, { recursive: true, force: true });
@@ -498,7 +549,10 @@ function buildZip(version) {
 function buildHooksConfig(hooksDir) {
   const base = hooksDir.replace(/\\/g, '/');
   const cmd  = (file, msg) => {
-    const entry = { type: 'command', command: `node "${base}/${file}"` };
+    const command = process.platform === 'win32'
+      ? `powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File "${base}/run-hidden-hook.ps1" "${base}/${file}"`
+      : `node "${base}/${file}"`;
+    const entry = { type: 'command', command };
     if (msg) entry.statusMessage = msg;
     return entry;
   };
@@ -507,9 +561,15 @@ function buildHooksConfig(hooksDir) {
       cmd('check-cwd.js'),
       cmd('check-stale-work-items.js', 'Checking for stale work items...'),
     ]}],
-    PreToolUse: [{ matcher: 'Bash', hooks: [
-      cmd('require-work-item-on-commit.js'),
-    ]}],
+    PreToolUse: [
+      { hooks: [
+        cmd('foreground-process-gate.js', 'Checking foreground process policy...'),
+        cmd('work-item-exit-gate.js', 'Checking work item exit gates...'),
+      ]},
+      { matcher: 'Bash', hooks: [
+        cmd('require-work-item-on-commit.js'),
+      ]},
+    ],
     PostToolUse: [{ hooks: [
       cmd('check-services.js'),
     ]}],
@@ -654,6 +714,8 @@ async function main() {
   {
     const staleRemoved = cleanStaleHooks(hooksDst);
     if (staleRemoved > 0) ok(`[0.5b] Hook cleanup — removed ${staleRemoved} orphaned hook file(s)`);
+    const shimRemoved = cleanProjectHookifyShims(codexRoot);
+    if (shimRemoved > 0) ok(`[0.5b] Hook cleanup — removed ${shimRemoved} project-local work-item hookify shim(s)`);
   }
 
   // 0.5. Legacy cleanup — remove old commands/rdc/ (pre-plugin-system format)
@@ -722,9 +784,7 @@ async function main() {
       } catch {}
       try {
         if (process.platform === 'win32') {
-          const winLink   = linkPath.replace(/\//g, '\\');
-          const winTarget = target.replace(/\//g, '\\');
-          execSync(`cmd /c mklink /J "${winLink}" "${winTarget}"`, { stdio: 'pipe' });
+          fs.symlinkSync(target, linkPath, 'junction');
         } else {
           fs.symlinkSync(target, linkPath, 'dir');
         }
@@ -736,12 +796,18 @@ async function main() {
     } else {
       info('[2.7] Symlinks   — no rdc skill links created (skills may already be linked)');
     }
+    const projectGuideCount = copyMissingProjectGuides(codexRoot);
+    if (projectGuideCount > 0) {
+      ok(`[2.8] Guides     — ${projectGuideCount} missing guide(s) copied to ${path.join(codexRoot, '.rdc', 'guides')}`);
+    } else {
+      info('[2.8] Guides     — project .rdc/guides already has base guide files or is absent');
+    }
   } else {
     info('[2.7] Symlinks   — skipped (no codex root found)');
   }
 
   // 3. Hook files
-  const hookCount = copyDir(hooksSrc, hooksDst, '.js');
+  const hookCount = copyHookFiles(hooksSrc, hooksDst);
   ok(`[3/6] Hook files — ${hookCount} file(s) → ${hooksDst}`);
 
   // 4. Hook wiring

package/scripts/install.ps1

@@ -58,7 +58,7 @@ if (-not (Test-Path $hooksDir)) {
 }
 
 $srcHooks  = Join-Path $repoRoot "hooks"
-$hookFiles = Get-ChildItem -Path $srcHooks -Filter "*.js" -ErrorAction SilentlyContinue
+$hookFiles = Get-ChildItem -Path $srcHooks -File -ErrorAction SilentlyContinue | Where-Object { $_.Extension -in @(".js", ".ps1") }
 foreach ($f in $hookFiles) {
     Copy-Item -Path $f.FullName -Destination (Join-Path $hooksDir $f.Name) -Force
 }
@@ -85,47 +85,53 @@ if ($SkipHooks) {
         SessionStart = @(
             [PSCustomObject]@{
                 hooks = @(
-                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/check-cwd.js`"" },
-                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/check-stale-work-items.js`""; statusMessage = "Checking for stale work items..." }
+                    [PSCustomObject]@{ type = "command"; command = "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$hooksBase/run-hidden-hook.ps1`" `"$hooksBase/check-cwd.js`"" },
+                    [PSCustomObject]@{ type = "command"; command = "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$hooksBase/run-hidden-hook.ps1`" `"$hooksBase/check-stale-work-items.js`""; statusMessage = "Checking for stale work items..." }
                 )
             }
         )
         PreToolUse = @(
+            [PSCustomObject]@{
+                hooks   = @(
+                    [PSCustomObject]@{ type = "command"; command = "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$hooksBase/run-hidden-hook.ps1`" `"$hooksBase/foreground-process-gate.js`""; statusMessage = "Checking foreground process policy..." },
+                    [PSCustomObject]@{ type = "command"; command = "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$hooksBase/run-hidden-hook.ps1`" `"$hooksBase/work-item-exit-gate.js`""; statusMessage = "Checking work item exit gates..." }
+                )
+            },
             [PSCustomObject]@{
                 matcher = "Bash"
                 hooks   = @(
-                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/require-work-item-on-commit.js`"" }
+                    [PSCustomObject]@{ type = "command"; command = "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$hooksBase/run-hidden-hook.ps1`" `"$hooksBase/require-work-item-on-commit.js`"" }
                 )
             }
         )
         PostToolUse = @(
             [PSCustomObject]@{
                 hooks = @(
-                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/check-services.js`"" }
+                    [PSCustomObject]@{ type = "command"; command = "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$hooksBase/run-hidden-hook.ps1`" `"$hooksBase/check-services.js`"" }
                 )
             }
         )
         PreCompact = @(
             [PSCustomObject]@{
                 hooks = @(
-                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/precompact-log.js`"" }
+                    [PSCustomObject]@{ type = "command"; command = "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$hooksBase/run-hidden-hook.ps1`" `"$hooksBase/precompact-log.js`"" }
                 )
             }
         )
         PostCompact = @(
             [PSCustomObject]@{
                 hooks = @(
-                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/postcompact-log.js`"" },
-                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/restart-brief.js`""; statusMessage = "Writing restart brief..." }
+                    [PSCustomObject]@{ type = "command"; command = "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$hooksBase/run-hidden-hook.ps1`" `"$hooksBase/postcompact-log.js`"" },
+                    [PSCustomObject]@{ type = "command"; command = "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$hooksBase/run-hidden-hook.ps1`" `"$hooksBase/restart-brief.js`""; statusMessage = "Writing restart brief..." }
                 )
             }
         )
         Stop = @(
             [PSCustomObject]@{
                 hooks = @(
-                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/rate-limit-retry.js`""; statusMessage = "Checking for rate limits..." },
-                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/post-work-check.js`""; statusMessage = "Checking for undocumented work..." },
-                    [PSCustomObject]@{ type = "command"; command = "node `"$hooksBase/no-stop-open-epics.js`""; statusMessage = "Checking for open epics..." }
+                    [PSCustomObject]@{ type = "command"; command = "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$hooksBase/run-hidden-hook.ps1`" `"$hooksBase/rate-limit-retry.js`""; statusMessage = "Checking for rate limits..." },
+                    [PSCustomObject]@{ type = "command"; command = "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$hooksBase/run-hidden-hook.ps1`" `"$hooksBase/post-work-check.js`""; statusMessage = "Checking for undocumented work..." },
+                    [PSCustomObject]@{ type = "command"; command = "powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$hooksBase/run-hidden-hook.ps1`" `"$hooksBase/no-stop-open-epics.js`""; statusMessage = "Checking for open epics..." }
                 )
             }
         )