dev-loops 0.1.3 → 0.2.0

package/extension/post-merge-update.ts

@@ -1,14 +1,39 @@
-import type {
-  AgentEndEvent,
-  ExecResult,
-  ExtensionAPI,
-  ExtensionContext,
-  ToolResultEvent,
-  UserBashEvent,
-  UserBashEventResult,
-} from '@earendil-works/pi-coding-agent';
-
-export const TARGET_REPO_SLUG = 'mfittko/dev-loops';
+import type { ExtensionHarnessAdapter, HarnessContext, HarnessExecResult } from './harness-types.ts';
+import {
+  TARGET_REPO_SLUG,
+  trimToNull,
+  normalizeGitHubRepoSlug,
+  isMergeCapableCommand,
+  isGhPrReadyCommand,
+  extractPrNumberFromGhPrReady,
+  extractRepoFlagFromGhPrReady,
+} from '@dev-loops/core/loop/bash-command-classify';
+
+// The bash-command classifiers now live in `@dev-loops/core/loop/bash-command-classify` so the
+// Pi extension and the Claude Code Bash hook share one source of truth. Re-export them here so
+// existing importers (and tests) that reference them from this module keep resolving.
+export {
+  TARGET_REPO_SLUG,
+  normalizeGitHubRepoSlug,
+  isMergeCapableCommand,
+  isGhPrReadyCommand,
+  extractPrNumberFromGhPrReady,
+  extractRepoFlagFromGhPrReady,
+};
+
+// Neutral event shapes the post-merge hook reads. The harness adapter forwards the
+// harness-native event object through unchanged; these capture only the fields used here.
+type ToolResultLike = { toolName?: string; input?: { command?: unknown } | null; isError?: boolean };
+type UserBashLike = { command: string; cwd: string };
+type UserBashResultLike = {
+  result: {
+    output: string;
+    exitCode: number | undefined;
+    cancelled: boolean;
+    truncated: boolean;
+  };
+};
+
 export const POST_MERGE_UPDATE_COMMAND = 'pi update git:github.com/mfittko/dev-loops';
 export const PRE_PR_READY_GATE_SCRIPT = 'node scripts/loop/pre-pr-ready-gate.mjs';
 
@@ -17,9 +42,6 @@ const POST_MERGE_UPDATE_TIMEOUT_MS = 10 * 60 * 1000;
 const REPO_RESOLUTION_TIMEOUT_MS = 5_000;
 const PR_READY_GATE_TIMEOUT_MS = 30_000;
 
-// Flags known to take a value argument for gh pr ready (not boolean flags)
-const FLAGS_THAT_TAKE_VALUE = new Set(["-r", "--repo"]);
-
 type RepoContext = {
   repoRoot: string | null;
   repoSlug: string | null;
@@ -31,7 +53,7 @@ type RunCommandArgs = {
   timeout?: number;
 };
 
-type RunCommandResult = ExecResult;
+type RunCommandResult = HarnessExecResult;
 
 type PostMergeUpdateHookState = {
   pendingPostMergeUpdate: boolean;
@@ -40,15 +62,11 @@ type PostMergeUpdateHookState = {
 };
 
 type CreatePostMergeUpdateHookOptions = {
+  exec?: ExtensionHarnessAdapter['exec'];
   resolveRepoContext?: (cwd: string) => Promise<RepoContext>;
   runCommand?: (args: RunCommandArgs) => Promise<RunCommandResult>;
 };
 
-function trimToNull(value: string | null | undefined): string | null {
-  const trimmed = `${value ?? ''}`.trim();
-  return trimmed ? trimmed : null;
-}
-
 function buildShellOutput(result: Pick<RunCommandResult, 'stdout' | 'stderr'>): string {
   const stdout = `${result.stdout ?? ''}`.trimEnd();
   const stderr = `${result.stderr ?? ''}`.trimEnd();
@@ -66,22 +84,22 @@ function buildFailureSummary(result: Pick<RunCommandResult, 'stdout' | 'stderr'
       : (typeof result.code === 'number' ? `exit code ${result.code}` : 'exit code unavailable'));
 }
 
-function getBashCommandFromToolResult(event: ToolResultEvent): string | null {
-  if (event.toolName !== 'bash') {
+function getBashCommandFromToolResult(event: ToolResultLike | null | undefined): string | null {
+  if (!event || event.toolName !== 'bash') {
     return null;
   }
   const command = event.input?.command;
   return typeof command === 'string' ? command : null;
 }
 
-function notify(ctx: ExtensionContext, message: string, level: 'info' | 'warning' | 'error' = 'info'): void {
+function notify(ctx: Pick<HarnessContext, 'hasUI' | 'ui'>, message: string, level: 'info' | 'warning' | 'error' = 'info'): void {
   if (ctx.hasUI) {
     ctx.ui.notify(message, level);
   }
 }
 
-async function defaultResolveRepoContext(pi: ExtensionAPI, cwd: string): Promise<RepoContext> {
-  const rootResult = await pi.exec('bash', ['-lc', 'git rev-parse --show-toplevel'], {
+async function defaultResolveRepoContext(exec: ExtensionHarnessAdapter['exec'], cwd: string): Promise<RepoContext> {
+  const rootResult = await exec('git rev-parse --show-toplevel', {
     cwd,
     timeout: REPO_RESOLUTION_TIMEOUT_MS,
   });
@@ -94,7 +112,7 @@ async function defaultResolveRepoContext(pi: ExtensionAPI, cwd: string): Promise
     return { repoRoot: null, repoSlug: null };
   }
 
-  const remoteResult = await pi.exec('bash', ['-lc', 'git config --get remote.origin.url'], {
+  const remoteResult = await exec('git config --get remote.origin.url', {
     cwd: repoRoot,
     timeout: REPO_RESOLUTION_TIMEOUT_MS,
   });
@@ -104,12 +122,12 @@ async function defaultResolveRepoContext(pi: ExtensionAPI, cwd: string): Promise
 
   return {
     repoRoot,
-    repoSlug: normalizeGitHubRepoSlug(remoteResult.stdout),
+    repoSlug: normalizeGitHubRepoSlug(remoteResult.stdout ?? ''),
   };
 }
 
-async function defaultRunCommand(pi: ExtensionAPI, args: RunCommandArgs): Promise<RunCommandResult> {
-  return pi.exec('bash', ['-lc', args.command], {
+async function defaultRunCommand(exec: ExtensionHarnessAdapter['exec'], args: RunCommandArgs): Promise<RunCommandResult> {
+  return exec(args.command, {
     cwd: args.cwd,
     timeout: args.timeout,
   });
@@ -159,165 +177,17 @@ async function queueIfEligible(
   return true;
 }
 
-export function normalizeGitHubRepoSlug(remoteUrl: string): string | null {
-  const normalized = trimToNull(remoteUrl);
-  if (!normalized) {
-    return null;
-  }
-
-  const patterns = [
-    /^git@github\.com:([^\s]+?)(?:\.git)?$/i,
-    /^https:\/\/github\.com\/([^\s]+?)(?:\.git)?$/i,
-    /^ssh:\/\/git@github\.com\/([^\s]+?)(?:\.git)?$/i,
-    /^git:github\.com\/([^\s]+?)(?:\.git)?$/i,
-  ];
-
-  for (const pattern of patterns) {
-    const match = normalized.match(pattern);
-    if (!match) {
-      continue;
-    }
-    return trimToNull(match[1])?.toLowerCase() ?? null;
-  }
-
-  return null;
-}
-
-function isGhPrMergeCommand(segment: string): boolean {
-  if (!/^gh\s+pr\s+merge(?:\s|$)/i.test(segment)) {
-    return false;
-  }
-
-  const remainder = segment.replace(/^gh\s+pr\s+merge(?:\s|$)/i, '').trim();
-  if (!remainder) {
-    return true;
-  }
-
-  const firstArg = remainder.match(/^(\S+)/)?.[1]?.toLowerCase() ?? '';
-  return !['--help', '-h'].includes(firstArg);
-}
-
-function isGitMergeCompletionCommand(segment: string): boolean {
-  if (!/^git\s+merge(?:\s|$)/i.test(segment)) {
-    return false;
-  }
-
-  const remainder = segment.replace(/^git\s+merge(?:\s|$)/i, '').trim();
-  if (!remainder) {
-    return true;
-  }
-
-  const firstArg = remainder.match(/^(\S+)/)?.[1]?.toLowerCase() ?? '';
-  return !['--abort', '--continue', '--quit', '--help', '-h'].includes(firstArg);
-}
-
-export function isMergeCapableCommand(command: string): boolean {
-  const normalized = command.trim();
-  if (!normalized) {
-    return false;
-  }
-
-  return normalized
-    .split(/\s*(?:&&|\|\||;|\|)\s*/)
-    .some((segment) => isGhPrMergeCommand(segment) || isGitMergeCompletionCommand(segment));
-}
-
-function firstShellSegment(command: string): string {
-  return command.trim().split(/\s*(?:&&|\|\||;|\|)\s*/)[0]?.trim() ?? '';
-}
-
-export function isGhPrReadyCommand(command: string): boolean {
-  const segment = firstShellSegment(command);
-  if (!segment || !/^gh\s+pr\s+ready(?:\s|$)/i.test(segment)) {
-    return false;
-  }
 
-  const remainder = segment.replace(/^gh\s+pr\s+ready(?:\s|$)/i, '').trim();
-  if (!remainder) {
-    return true;
-  }
-  // Block interception if --help or -h appears anywhere in the arguments
-  const args = remainder.split(/\s+/).map(a => a.toLowerCase());
-  return !args.includes('--help') && !args.includes('-h');
-}
-
-export function extractPrNumberFromGhPrReady(command: string): number | null {
-  const segment = firstShellSegment(command);
-  if (!/^gh\s+pr\s+ready(?:\s|$)/i.test(segment)) {
-    return null;
-  }
-  const remainder = segment.replace(/^gh\s+pr\s+ready(?:\s|$)/i, '').trim();
-  if (!remainder) {
-    return null;
-  }
-  // Skip flags (--flag or --flag=value)
-  const tokens = remainder.split(/\s+/);
-  for (let i = 0; i < tokens.length; i++) {
-    const token = tokens[i];
-    if (token.startsWith('-')) {
-      // Only skip the next token for flags known to take a value argument
-      const flagName = token.replace(/=.*$/, '').toLowerCase();
-      if (!token.includes('=') && FLAGS_THAT_TAKE_VALUE.has(flagName)) {
-        i++; // skip next token (the flag value)
-      }
-      continue;
-    }
-    if (/^\d+$/.test(token)) {
-      const num = Number(token);
-      if (num > 0) {
-        return num;
-      }
-    }
-    // Non-numeric non-flag token — not a PR number
-    return null;
-  }
-  return null;
-}
-
-export function extractRepoFlagFromGhPrReady(command: string): string | null {
-  const segment = firstShellSegment(command);
-  if (!/^gh\s+pr\s+ready(?:\s|$)/i.test(segment)) {
-    return null;
-  }
-  const remainder = segment.replace(/^gh\s+pr\s+ready(?:\s|$)/i, '').trim();
-  if (!remainder) {
-    return null;
-  }
-  const tokens = remainder.split(/\s+/);
-  for (let i = 0; i < tokens.length; i++) {
-    const token = tokens[i];
-    const lower = token.toLowerCase();
-    if (lower === '-r' || lower === '--repo') {
-      // Next token is the repo slug value
-      if (i + 1 < tokens.length && !tokens[i + 1].startsWith('-')) {
-        return tokens[i + 1];
-      }
-    }
-    // Handle --repo=value and -R=value
-    const repoEqMatch = token.match(/^(?:--repo|-R)=(.+)$/i);
-    if (repoEqMatch) {
-      return repoEqMatch[1];
-    }
-
-  }
-  return null;
-}
-
-export function createPostMergeUpdateHook(
-  piOrOptions: ExtensionAPI | CreatePostMergeUpdateHookOptions,
-  maybeOptions: CreatePostMergeUpdateHookOptions = {},
-) {
-  const hasPiExec = typeof (piOrOptions as ExtensionAPI)?.exec === 'function';
-  const pi = hasPiExec ? piOrOptions as ExtensionAPI : null;
-  const options = hasPiExec ? maybeOptions : (piOrOptions as CreatePostMergeUpdateHookOptions);
+export function createPostMergeUpdateHook(options: CreatePostMergeUpdateHookOptions = {}) {
+  const exec = options.exec ?? null;
 
   const resolveRepoContext = options.resolveRepoContext
-    ?? (pi ? ((cwd: string) => defaultResolveRepoContext(pi, cwd)) : null);
+    ?? (exec ? ((cwd: string) => defaultResolveRepoContext(exec, cwd)) : null);
   const runCommand = options.runCommand
-    ?? (pi ? ((args: RunCommandArgs) => defaultRunCommand(pi, args)) : null);
+    ?? (exec ? ((args: RunCommandArgs) => defaultRunCommand(exec, args)) : null);
 
   if (!resolveRepoContext || !runCommand) {
-    throw new Error('createPostMergeUpdateHook requires an ExtensionAPI or explicit resolveRepoContext/runCommand overrides.');
+    throw new Error('createPostMergeUpdateHook requires an `exec` function or explicit resolveRepoContext/runCommand overrides.');
   }
 
   const state: PostMergeUpdateHookState = {
@@ -341,15 +211,24 @@ export function createPostMergeUpdateHook(
       reset();
     },
 
-    async onToolResult(event: Pick<ToolResultEvent, 'toolName' | 'input' | 'isError'>, ctx: Pick<ExtensionContext, 'cwd'>): Promise<void> {
-      const command = getBashCommandFromToolResult(event as ToolResultEvent);
+    async onToolResult(rawEvent: unknown, ctx: Pick<HarnessContext, 'cwd'>): Promise<void> {
+      // Harness events arrive as `unknown` across the neutral seam; narrow here, at the
+      // single place that knows which fields this hook reads.
+      const event = rawEvent as ToolResultLike;
+      const command = getBashCommandFromToolResult(event);
       if (!command || event.isError) {
         return;
       }
       await queueIfEligible(state, resolveRepoContext, command, ctx.cwd);
     },
 
-    async onUserBash(event: Pick<UserBashEvent, 'command' | 'cwd'>, _ctx?: ExtensionContext): Promise<UserBashEventResult | undefined> {
+    async onUserBash(rawEvent: unknown, _ctx?: HarnessContext): Promise<UserBashResultLike | undefined> {
+      const event = rawEvent as UserBashLike;
+      // The seam forwards events as `unknown`; a malformed/foreign-harness event must pass
+      // through untouched rather than crash the handler (downstream calls .trim() on command).
+      if (!event || typeof event.command !== 'string') {
+        return undefined;
+      }
       // Intercept gh pr ready before any other checks
       if (isGhPrReadyCommand(event.command)) {
         // Check if the command explicitly targets a different repo via -R/--repo
@@ -477,13 +356,13 @@ export function createPostMergeUpdateHook(
       }
     },
 
-    async onAgentEnd(_event: AgentEndEvent, ctx: Pick<ExtensionContext, 'cwd' | 'hasUI' | 'ui'>): Promise<void> {
+    async onAgentEnd(_event: unknown, ctx: Pick<HarnessContext, 'cwd' | 'hasUI' | 'ui'>): Promise<void> {
       if (!state.pendingPostMergeUpdate || state.updateInFlight) {
         return;
       }
 
       state.updateInFlight = true;
-      notify(ctx as ExtensionContext, `Post-merge update running: ${POST_MERGE_UPDATE_COMMAND}`, 'info');
+      notify(ctx, `Post-merge update running: ${POST_MERGE_UPDATE_COMMAND}`, 'info');
 
       try {
         const result = await runCommand({
@@ -493,17 +372,17 @@ export function createPostMergeUpdateHook(
         });
 
         if (result.code === 0 && !result.killed) {
-          notify(ctx as ExtensionContext, `Post-merge update completed: ${POST_MERGE_UPDATE_COMMAND}`, 'info');
+          notify(ctx, `Post-merge update completed: ${POST_MERGE_UPDATE_COMMAND}`, 'info');
         } else {
           notify(
-            ctx as ExtensionContext,
+            ctx,
             `Post-merge update failed (warning only): ${buildFailureSummary(result)}`,
             'warning',
           );
         }
       } catch (error) {
         const detail = error instanceof Error ? error.message : String(error);
-        notify(ctx as ExtensionContext, `Post-merge update failed (warning only): ${detail}`, 'warning');
+        notify(ctx, `Post-merge update failed (warning only): ${detail}`, 'warning');
       } finally {
         reset();
       }

package/package.json

@@ -2,15 +2,17 @@
   "name": "dev-loops",
   "license": "MIT",
   "type": "module",
-  "description": "Shared Pi workflow infrastructure for reusable local and remote development loops",
+  "description": "Agent-harness-agnostic dev-loop infrastructure (Pi and Claude Code) for reusable local and remote development loops",
   "keywords": [
-    "pi-package",
-    "pi",
-    "pi-coding-agent",
-    "workflow",
     "dev-loop",
+    "workflow",
     "github",
-    "copilot"
+    "copilot",
+    "claude-code",
+    "claude",
+    "pi",
+    "pi-coding-agent",
+    "pi-package"
   ],
   "engines": {
     "node": ">=20"
@@ -22,11 +24,12 @@
     "verify": "npm test && npm run test:dev-loop",
     "test": "npm run test:assets && npm run test:extension && npm run test:scripts && npm run test:core && npm run test:docs",
     "test:assets": "node --test --test-reporter ./test/failure-summary-reporter.mjs test/dev-loop-init-phase-smoke.test.mjs test/contracts/*.test.mjs test/workflow-handoff-contract.test.mjs",
-    "test:extension": "node --import tsx --test --test-reporter ./test/failure-summary-reporter.mjs test/extension-checks.test.mjs test/extension-post-merge-update.test.mjs test/extension-command-contract.test.mjs test/extension-package-contract.test.mjs test/dev-loops-core.test.mjs test/dev-loops-cli.test.mjs",
+    "test:extension": "node --import tsx --test --test-reporter ./test/failure-summary-reporter.mjs test/extension-checks.test.mjs test/extension-post-merge-update.test.mjs test/extension-command-contract.test.mjs test/extension-package-contract.test.mjs test/extension-pi-adapter.test.mjs test/extension-claude-adapter.test.mjs test/dev-loops-core.test.mjs test/dev-loops-cli.test.mjs",
     "test:scripts": "node --test --test-reporter ./test/failure-summary-reporter.mjs test/github/*.test.mjs test/loop/*.test.mjs test/docs/*.test.mjs test/projects/*.test.mjs",
     "test:core": "node --test --test-reporter ./test/failure-summary-reporter.mjs packages/core/test/*.test.mjs",
     "test:dev-loop": "node --test --test-reporter ./test/failure-summary-reporter.mjs skills/dev-loop/scripts/dev-mode-context.test.mjs skills/dev-loop/scripts/render-template.test.mjs skills/dev-loop/scripts/post-gate-verdict-fallback.test.mjs",
     "test:playwright:viewer": "playwright test -c playwright.inspect-run-viewer.config.mjs",
+    "smoke:headless": "node scripts/claude/headless-info-smoke.mjs",
     "test:docs": "node scripts/docs/validate-links.mjs && node scripts/docs/validate-no-duplicate-rules.mjs",
     "repo-wiki": "node scripts/repo-wiki.mjs",
     "repo-wiki:bootstrap": "node scripts/repo-wiki.mjs scan --repo . && node scripts/repo-wiki.mjs plan --repo . && node scripts/repo-wiki.mjs compile --repo .",
@@ -72,7 +75,7 @@
   "dependencies": {
     "mermaid": "11.15.0",
     "zod": "^4.4.3",
-    "@dev-loops/core": "^0.1.3"
+    "@dev-loops/core": "^0.2.0"
   },
   "repository": {
     "type": "git",
@@ -82,7 +85,7 @@
     "url": "https://github.com/mfittko/dev-loops/issues"
   },
   "homepage": "https://github.com/mfittko/dev-loops#readme",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "files": [
     "cli/",
     "lib/",
@@ -90,6 +93,10 @@
     "extension/",
     "skills/",
     "agents/",
+    ".claude/.claude-plugin/",
+    ".claude/agents/",
+    ".claude/skills/",
+    ".claude/hooks/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE",

package/scripts/README.md

@@ -45,7 +45,7 @@ Failure behavior:
 
 ### `scripts/github/capture-review-threads.mjs`
 
-Capture and normalize PR review-thread JSON.
+Capture and normalize PR review-thread JSON from all reviewers.
 
 Supported inputs:
 - `--input <path>`
@@ -55,6 +55,9 @@ Supported inputs:
 Optional:
 - `--output <path>` writes the same success JSON emitted on stdout
 
+Contract:
+- live capture loads review threads from all reviewers; no author filter is applied
+
 Success output shape:
 - `{ "ok": true, "source": { ... }, "summary": { ... }, "threads": [...], "comments": [...] }`
 - normalized `comments[]` preserve both the GraphQL comment node id (`id`) and the REST-safe numeric review-comment id (`databaseId`) when available
@@ -280,7 +283,7 @@ Required:
 - `--pr <number>`
 
 Optional:
-- `--author <login>` (default `Copilot`)
+- `--author <login>` (default `all`)
 - exactly one message source: `--message <text>` or stdin
 - `--resolve`
 
@@ -294,7 +297,7 @@ Contract:
 - zero-match runs are deterministic no-ops with success JSON
 
 Success output shape:
-- `{ "ok": true, "repo": "owner/name", "pr": 17, "author": "Copilot", "resolve": true|false, "matchedThreadCount": 2, "repliedThreadCount": 2, "resolvedThreadCount": 2, "skippedThreadCount": 1, "results": [{ "threadId": "...", "commentId": 123, "replyId": 456, "replyUrl": "...", "resolved": true }] }`
+- `{ "ok": true, "repo": "owner/name", "pr": 17, "author": "all", "resolve": true|false, "matchedThreadCount": 2, "repliedThreadCount": 2, "resolvedThreadCount": 2, "skippedThreadCount": 1, "results": [{ "threadId": "...", "commentId": 123, "replyId": 456, "replyUrl": "...", "resolved": true }] }`
 
 Failure behavior:
 - malformed arguments, empty/conflicting message input, malformed thread snapshots, unexpected `gh` failures, reply failures, resolve failures, and failed post-resolve verification emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero

package/scripts/claude/generate-claude-assets.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * Generate the Claude Code asset tree (.claude/agents, .claude/skills) from the canonical
+ * Pi sources (agents/*.agent.md, skills/<name>/SKILL.md). The sources remain the single
+ * source of truth; the generated tree is committed and kept in sync by `--check` (CI/test).
+ *
+ * Usage:
+ *   node scripts/claude/generate-claude-assets.mjs            Write the .claude tree.
+ *   node scripts/claude/generate-claude-assets.mjs --check    Exit non-zero if the committed
+ *                                                             tree drifts from the sources.
+ *   --repo-root <path>   Override the repo root (default: cwd).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { transformAgent, transformSkill } from "@dev-loops/core/claude/asset-generation";
+
+/**
+ * Collect the generated assets as { target, content } pairs (target is repo-relative).
+ * @param {{ repoRoot?: string }} [options]
+ * @returns {{ target: string, content: string }[]}
+ */
+export function collectGeneratedAssets({ repoRoot = process.cwd() } = {}) {
+  const assets = [];
+
+  const agentsDir = path.join(repoRoot, "agents");
+  if (fs.existsSync(agentsDir)) {
+    for (const entry of fs.readdirSync(agentsDir).sort()) {
+      if (!entry.endsWith(".agent.md")) continue;
+      const source = `agents/${entry}`;
+      const raw = fs.readFileSync(path.join(repoRoot, source), "utf8");
+      const base = entry.slice(0, -".agent.md".length);
+      assets.push({ target: `.claude/agents/${base}.md`, content: transformAgent({ source, raw }) });
+    }
+  }
+
+  const skillsDir = path.join(repoRoot, "skills");
+  if (fs.existsSync(skillsDir)) {
+    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (!entry.isDirectory()) continue;
+      const source = `skills/${entry.name}/SKILL.md`;
+      const abs = path.join(repoRoot, source);
+      if (!fs.existsSync(abs)) continue; // e.g. skills/docs/ holds shared docs, not a SKILL.md
+      const raw = fs.readFileSync(abs, "utf8");
+      assets.push({ target: `.claude/skills/${entry.name}/SKILL.md`, content: transformSkill({ source, raw }) });
+    }
+  }
+
+  // Bundle the shared markdown the generated skills reference via relative links so they resolve
+  // inside the .claude/ tree (#816). The skills live at .claude/skills/<name>/, so:
+  //   `../docs/<contract>.md`        → .claude/skills/docs/<contract>.md      (skills/docs/*.md)
+  //   `../dev-loop/templates/<t>.md` → .claude/skills/dev-loop/templates/<t>.md (skills/dev-loop/templates/*.md)
+  // Copied verbatim; the no-drift test keeps them in sync with source. (Repo-root `../../` refs —
+  // PLAN.md/AGENTS.md/docs/phases — point at the *consumer project's* files and are out of scope.)
+  for (const [srcRel, targetRel] of [
+    ["skills/docs", ".claude/skills/docs"],
+    ["skills/dev-loop/templates", ".claude/skills/dev-loop/templates"],
+  ]) {
+    assets.push(...collectBundle(repoRoot, srcRel, targetRel));
+  }
+
+  return assets;
+}
+
+/** Recursively collect `*.md` files under a source dir as verbatim {target, content} bundle assets. */
+function collectBundle(repoRoot, srcRel, targetRel) {
+  const out = [];
+  const absDir = path.join(repoRoot, srcRel);
+  if (!fs.existsSync(absDir)) return out;
+  for (const entry of fs.readdirSync(absDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.isDirectory()) {
+      out.push(...collectBundle(repoRoot, `${srcRel}/${entry.name}`, `${targetRel}/${entry.name}`));
+    } else if (entry.name.endsWith(".md")) {
+      out.push({
+        target: `${targetRel}/${entry.name}`,
+        content: fs.readFileSync(path.join(absDir, entry.name), "utf8"),
+      });
+    }
+  }
+  return out;
+}
+
+/** Write the generated assets to disk. Returns the list of written targets. */
+export function writeAssets(assets, { repoRoot = process.cwd() } = {}) {
+  for (const { target, content } of assets) {
+    const abs = path.join(repoRoot, target);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content, "utf8");
+  }
+  return assets.map((a) => a.target);
+}
+
+/** Recursively list committed files under a `.claude/` subtree (repo-relative, sorted). */
+function listFilesRecursive(repoRoot, rel) {
+  const out = [];
+  const abs = path.join(repoRoot, rel);
+  if (!fs.existsSync(abs)) return out;
+  for (const entry of fs.readdirSync(abs, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.isDirectory()) out.push(...listFilesRecursive(repoRoot, `${rel}/${entry.name}`));
+    else out.push(`${rel}/${entry.name}`);
+  }
+  return out;
+}
+
+/**
+ * List committed generated-asset files currently on disk (repo-relative, posix separators).
+ * Recurses the whole `.claude/agents` + `.claude/skills` trees so stale orphans — including
+ * bundled docs/templates whose source was removed — are detected, not just SKILL.md files.
+ */
+function listExistingAssetFiles(repoRoot) {
+  return [
+    ...listFilesRecursive(repoRoot, ".claude/agents"),
+    ...listFilesRecursive(repoRoot, ".claude/skills"),
+  ];
+}
+
+/**
+ * Compare generated assets against the committed tree. Returns drifted targets, covering both
+ * missing/out-of-date generated files AND orphaned committed files no longer produced by a
+ * source (e.g. after a source agent/skill is renamed or removed).
+ */
+export function checkAssets(assets, { repoRoot = process.cwd() } = {}) {
+  const drifted = [];
+  const expected = new Set(assets.map((a) => a.target));
+  for (const { target, content } of assets) {
+    const abs = path.join(repoRoot, target);
+    const current = fs.existsSync(abs) ? fs.readFileSync(abs, "utf8") : null;
+    if (current !== content) {
+      drifted.push({ target, reason: current === null ? "missing" : "out-of-date" });
+    }
+  }
+  for (const existing of listExistingAssetFiles(repoRoot)) {
+    if (!expected.has(existing)) {
+      drifted.push({ target: existing, reason: "orphaned" });
+    }
+  }
+  return drifted;
+}
+
+function main(argv) {
+  const check = argv.includes("--check");
+  const rootIdx = argv.indexOf("--repo-root");
+  let repoRoot = process.cwd();
+  if (rootIdx !== -1) {
+    const value = argv[rootIdx + 1];
+    if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
+      process.stderr.write(JSON.stringify({ ok: false, error: "--repo-root requires a path value" }) + "\n");
+      process.exit(1);
+    }
+    repoRoot = value;
+  }
+
+  const assets = collectGeneratedAssets({ repoRoot });
+
+  if (check) {
+    const drifted = checkAssets(assets, { repoRoot });
+    if (drifted.length > 0) {
+      process.stderr.write(
+        JSON.stringify({ ok: false, error: "generated .claude assets are out of date", drifted }, null, 2) + "\n",
+      );
+      process.stderr.write("Run `node scripts/claude/generate-claude-assets.mjs` and commit the result.\n");
+      process.exit(1);
+    }
+    process.stdout.write(JSON.stringify({ ok: true, checked: assets.length }) + "\n");
+    return;
+  }
+
+  const written = writeAssets(assets, { repoRoot });
+  process.stdout.write(JSON.stringify({ ok: true, written }, null, 2) + "\n");
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main(process.argv.slice(2));
+}