@punks/cli 1.0.5 → 1.0.7

package/README.md

@@ -67,7 +67,7 @@ Current scaffold-managed global tools:
 - `portless`
 - `skills`
 
-On startup, `punks` starts best-effort checks for a newer CLI version and the `dp-cli` operator skill. CLI package updates prompt before running the inferred package-manager command. The `dp-cli` skill is auto-installed when missing and auto-updated when present through targeted `skills add ... --skill dp-cli` / `skills update dp-cli ...` commands only; startup never runs or suggests plain root `skills update`. Set `DP_NO_UPDATE_CHECK=1` or `DP_NO_SKILL_UPDATE_CHECK=1` to skip those checks.
+On startup, `punks` may start a detached best-effort worker for a newer CLI version and the presence of the `dp-cli` operator skill. The requested command renders immediately; startup checks are advisory, run at most once per 12 hours by default, and never install/update packages or skills while another CLI command is starting. Set `DP_NO_UPDATE_CHECK=1` or `DP_NO_SKILL_UPDATE_CHECK=1` to skip those checks, or `DP_STARTUP_CHECK_INTERVAL_MS=0` to force the worker during local testing.
 
 ## Publishing
 

package/dist/data/catalog/hooks.ts

@@ -15,12 +15,4 @@ export const hookCatalog = [
       "Shared hook that auto-formats edited JS/TS/JSON files and lint-checks product files after tool use.",
     sourcePath: "hooks/format-edited-file.mjs",
   },
-  {
-    id: "require-tests-for-pr",
-    harness: "shared",
-    outputPath: ".agents/hooks/require-tests-for-pr.mjs",
-    description:
-      "Shared hook that blocks PR creation while tests are failing.",
-    sourcePath: "hooks/require-tests-for-pr.mjs",
-  },
 ] as const satisfies ReadonlyArray<HookDefinition>;

package/dist/data/catalog/packs.ts

@@ -2,7 +2,7 @@ import type { PackCategory, PackId } from "../../core/models";
 import type { LintAssetId } from "./lint";
 import type { SkillId } from "./skills";
 
-export type PackHookId = "format-edited-file" | "require-tests-for-pr";
+export type PackHookId = "format-edited-file";
 export type PackPromptSurfaceId =
   | "shared-agents"
   | "root-prompt-spec"
@@ -42,5 +42,5 @@ export const packCatalog = [
   { id: "trpc", category: "detected", triggerPackages: ["@trpc/"], description: "tRPC guidance pack.", skills: [], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared contract-first baseline", "workspace client/server boundaries"] },
   { id: "turborepo", category: "detected", triggerPackages: ["turbo"], description: "Turborepo guidance pack.", skills: ["turborepo"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared monorepo baseline", "workspace task boundary rules"] },
   { id: "python", category: "language", triggerPackages: [], description: "Shared Python language pack for async, style, structure, testing, and design guidance.", skills: ["async-python-patterns", "python-code-style", "python-design-patterns", "python-project-structure", "python-testing-patterns"], lintAssets: [], hooks: [], promptSurfaces: [], promptDetails: [] },
-  { id: "typescript", category: "language", triggerPackages: ["typescript"], description: "Shared JavaScript / TypeScript language pack for hook and language-level scaffold assets.", skills: ["quality-types"], lintAssets: [], hooks: ["format-edited-file", "require-tests-for-pr"], promptSurfaces: [], promptDetails: [] },
+  { id: "typescript", category: "language", triggerPackages: ["typescript"], description: "Shared JavaScript / TypeScript language pack for hook and language-level scaffold assets.", skills: ["quality-types"], lintAssets: [], hooks: ["format-edited-file"], promptSurfaces: [], promptDetails: [] },
 ] as const satisfies ReadonlyArray<PackCatalogEntry>;

package/dist/data/hooks/format-edited-file.mjs

@@ -11,6 +11,7 @@ const formattableSuffixes = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs
 const lintableSuffixes = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 const ignoredParts = new Set([".git", "node_modules", ".next", "dist"]);
 const productRoots = new Set(["apps", "packages"]);
+const packageManagers = new Set(["bun", "pnpm", "npm", "yarn"]);
 
 function readStdinJson() {
   try {
@@ -93,7 +94,54 @@ function commandExists(command) {
   );
 }
 
+function packageManagerFromPackageJson(root) {
+  const packageManager = loadJson(path.join(root, "package.json"))?.packageManager;
+
+  if (typeof packageManager !== "string") {
+    return null;
+  }
+
+  const name = packageManager.split("@")[0];
+  return packageManagers.has(name) ? name : null;
+}
+
+function packageManagerFromLockfile(root) {
+  if (existsSync(path.join(root, "bun.lock")) || existsSync(path.join(root, "bun.lockb"))) {
+    return "bun";
+  }
+
+  if (
+    existsSync(path.join(root, "pnpm-lock.yaml")) ||
+    existsSync(path.join(root, "pnpm-workspace.yaml"))
+  ) {
+    return "pnpm";
+  }
+
+  if (existsSync(path.join(root, "yarn.lock"))) {
+    return "yarn";
+  }
+
+  if (existsSync(path.join(root, "package-lock.json"))) {
+    return "npm";
+  }
+
+  return null;
+}
+
 function toolCommand(root, tool, args) {
+  switch (packageManagerFromPackageJson(root) ?? packageManagerFromLockfile(root)) {
+    case "bun":
+      return ["bunx", tool, ...args];
+    case "pnpm":
+      return ["pnpm", "exec", tool, ...args];
+    case "yarn":
+      return ["yarn", "exec", tool, ...args];
+    case "npm":
+      return ["npm", "exec", "--", tool, ...args];
+    default:
+      break;
+  }
+
   if (commandExists("bunx")) {
     return ["bunx", tool, ...args];
   }
@@ -524,6 +572,10 @@ export const FormatAndLintPlugin = async ({ client, worktree }) => {
   };
 };
 
+export const testHooks = {
+  toolCommand,
+};
+
 function main() {
   const mode = process.argv[2] ?? "";
 

package/dist/data/hooks.test.ts

@@ -0,0 +1,58 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { describe, expect, it } from "@effect/vitest";
+
+type HookModule = {
+  readonly testHooks: {
+    readonly testCommand?: (root: string) => ReadonlyArray<string>;
+    readonly toolCommand?: (
+      root: string,
+      tool: string,
+      args: ReadonlyArray<string>,
+    ) => ReadonlyArray<string>;
+  };
+};
+
+const repoRoot = path.resolve(import.meta.dirname, "../..");
+
+const loadHookModule = (relativePath: string) =>
+  import(path.join(repoRoot, "src/data/hooks", relativePath)) as Promise<HookModule>;
+
+const tempRepo = (files: Record<string, string>) => {
+  const root = mkdtempSync(path.join(tmpdir(), "dp-hook-test-"));
+
+  for (const [filePath, content] of Object.entries(files)) {
+    writeFileSync(path.join(root, filePath), content);
+  }
+
+  return root;
+};
+
+describe("scaffolded hooks", () => {
+  it("executes formatter tools with the repo package manager", async () => {
+    const { testHooks } = await loadHookModule("format-edited-file.mjs");
+
+    expect(
+      testHooks.toolCommand?.(
+        tempRepo({
+          "package.json": JSON.stringify({ packageManager: "bun@1.3.5" }),
+        }),
+        "oxfmt",
+        ["--write", "src/index.ts"],
+      ),
+    ).toEqual(["bunx", "oxfmt", "--write", "src/index.ts"]);
+
+    expect(
+      testHooks.toolCommand?.(
+        tempRepo({
+          "package.json": "{}",
+          "pnpm-lock.yaml": "",
+        }),
+        "oxlint",
+        ["-c", ".oxlintrc.json", "src/index.ts"],
+      ),
+    ).toEqual(["pnpm", "exec", "oxlint", "-c", ".oxlintrc.json", "src/index.ts"]);
+  });
+});

package/dist/data/scripts/sync-subagents.mjs

@@ -52,7 +52,7 @@ const cursorManagedComment =
 const opencodeManagedComment =
   "<!-- Generated by scripts/sync-subagents.mjs. Edit .agents/subagents/manifest.mjs instead. -->";
 
-function buildCodexAgentConfig({ hasFormatHook, hasTestHook }) {
+function buildCodexAgentConfig({ hasFormatHook }) {
   const lines = [
     "[agents]",
     "max_threads = 6",
@@ -74,16 +74,6 @@ function buildCodexAgentConfig({ hasFormatHook, hasTestHook }) {
     );
   }
 
-  if (hasTestHook) {
-    lines.push(
-      "PreToolUse = [",
-      '  { matcher = "Bash|.*[Pp]ull.?[Rr]equest.*|.*[Pp][Rr].?[Cc]reate.*|.*create[_-]?pull[_-]?request.*", hooks = [',
-      '    { type = "command", command = "node \\"$(git rev-parse --show-toplevel)/.codex/hooks/require-tests-for-pr.mjs\\" codex", statusMessage = "Checking tests before PR creation", timeout = 600 },',
-      "  ] },",
-      "]",
-    );
-  }
-
   if (hasFormatHook) {
     lines.push(
       "PostToolUse = [",
@@ -98,35 +88,9 @@ function buildCodexAgentConfig({ hasFormatHook, hasTestHook }) {
   return lines.join("\n");
 }
 
-function buildClaudeSettingsConfig({ hasFormatHook, hasTestHook }) {
+function buildClaudeSettingsConfig({ hasFormatHook }) {
   return {
     hooks: {
-      ...(hasTestHook
-        ? {
-            PreToolUse: [
-              {
-                matcher: "mcp__github__create_pull_request",
-                hooks: [
-                  {
-                    type: "command",
-                    command: 'node "$CLAUDE_PROJECT_DIR"/.claude/hooks/require-tests-for-pr.mjs claude',
-                    timeout: 600,
-                  },
-                ],
-              },
-              {
-                matcher: "Bash",
-                hooks: [
-                  {
-                    type: "command",
-                    command: 'node "$CLAUDE_PROJECT_DIR"/.claude/hooks/require-tests-for-pr.mjs claude',
-                    timeout: 600,
-                  },
-                ],
-              },
-            ],
-          }
-        : {}),
       ...(hasFormatHook
         ? {
             PostToolUse: [
@@ -147,24 +111,10 @@ function buildClaudeSettingsConfig({ hasFormatHook, hasTestHook }) {
   };
 }
 
-function buildCursorHooksConfig({ hasFormatHook, hasTestHook }) {
+function buildCursorHooksConfig({ hasFormatHook }) {
   return {
     version: 1,
     hooks: {
-      ...(hasTestHook
-        ? {
-            beforeMCPExecution: [
-              {
-                command: "node .cursor/hooks/require-tests-for-pr.mjs cursor",
-              },
-            ],
-            beforeShellExecution: [
-              {
-                command: "node .cursor/hooks/require-tests-for-pr.mjs cursor",
-              },
-            ],
-          }
-        : {}),
       ...(hasFormatHook
         ? {
             afterFileEdit: [
@@ -391,7 +341,7 @@ async function syncHookSurface() {
   await mkdir(cursorHooksDir, { recursive: true });
   await mkdir(opencodePluginsDir, { recursive: true });
 
-  for (const hookName of ["format-edited-file.mjs", "require-tests-for-pr.mjs"]) {
+  for (const hookName of ["format-edited-file.mjs"]) {
     const sourcePath = path.join(sharedHooksPath, hookName);
     const targetPaths = [
       path.join(codexHooksDir, hookName),
@@ -445,7 +395,6 @@ async function main() {
   await mkdir(path.dirname(cursorHooksJsonPath), { recursive: true });
   const availableHooks = {
     hasFormatHook: await pathExists(path.join(sharedHooksPath, "format-edited-file.mjs")),
-    hasTestHook: await pathExists(path.join(sharedHooksPath, "require-tests-for-pr.mjs")),
   };
   await writeFile(codexConfigPath, buildCodexAgentConfig(availableHooks), "utf8");
   await rm(path.join(codexDir, "hooks.json"), { force: true });

package/dist/index.js

@@ -10884,8 +10884,15 @@ var require_public_api = __commonJS((exports) => {
 });
 
 // src/index.ts
-import { spawnSync as spawnSync2 } from "child_process";
-import { createInterface as createInterface3 } from "readline/promises";
+import { spawn as spawn2 } from "child_process";
+import {
+  existsSync as existsSync7,
+  mkdirSync as mkdirSync6,
+  readFileSync as readFileSync7,
+  writeFileSync as writeFileSync5
+} from "fs";
+import { homedir as homedir2 } from "os";
+import path14 from "path";
 
 // node_modules/.pnpm/effect@3.19.19/node_modules/effect/dist/esm/Array.js
 var exports_Array = {};
@@ -41903,13 +41910,6 @@ var hookCatalog = [
     outputPath: ".agents/hooks/format-edited-file.mjs",
     description: "Shared hook that auto-formats edited JS/TS/JSON files and lint-checks product files after tool use.",
     sourcePath: "hooks/format-edited-file.mjs"
-  },
-  {
-    id: "require-tests-for-pr",
-    harness: "shared",
-    outputPath: ".agents/hooks/require-tests-for-pr.mjs",
-    description: "Shared hook that blocks PR creation while tests are failing.",
-    sourcePath: "hooks/require-tests-for-pr.mjs"
   }
 ];
 
@@ -42208,7 +42208,7 @@ var packCatalog = [
   { id: "trpc", category: "detected", triggerPackages: ["@trpc/"], description: "tRPC guidance pack.", skills: [], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared contract-first baseline", "workspace client/server boundaries"] },
   { id: "turborepo", category: "detected", triggerPackages: ["turbo"], description: "Turborepo guidance pack.", skills: ["turborepo"], lintAssets: [], hooks: [], promptSurfaces: ["shared-agents", "root-prompt-spec", "workspace-prompt-spec"], promptDetails: ["shared monorepo baseline", "workspace task boundary rules"] },
   { id: "python", category: "language", triggerPackages: [], description: "Shared Python language pack for async, style, structure, testing, and design guidance.", skills: ["async-python-patterns", "python-code-style", "python-design-patterns", "python-project-structure", "python-testing-patterns"], lintAssets: [], hooks: [], promptSurfaces: [], promptDetails: [] },
-  { id: "typescript", category: "language", triggerPackages: ["typescript"], description: "Shared JavaScript / TypeScript language pack for hook and language-level scaffold assets.", skills: ["quality-types"], lintAssets: [], hooks: ["format-edited-file", "require-tests-for-pr"], promptSurfaces: [], promptDetails: [] }
+  { id: "typescript", category: "language", triggerPackages: ["typescript"], description: "Shared JavaScript / TypeScript language pack for hook and language-level scaffold assets.", skills: ["quality-types"], lintAssets: [], hooks: ["format-edited-file"], promptSurfaces: [], promptDetails: [] }
 ];
 
 // src/data/catalog/skills.ts
@@ -42289,7 +42289,7 @@ var toolCatalog = [
 
 // package.json
 var name = "@punks/cli";
-var version = "1.0.5";
+var version = "1.0.7";
 // src/baseline/bundled.ts
 var bundledBaseline = {
   summary: {
@@ -46687,6 +46687,9 @@ var runUpdate = ({
         relativePath: change.path
       });
     }
+    for (const staleFile of staleFiles) {
+      rmSync3(path12.join(rootDirectory, staleFile), { recursive: true, force: true });
+    }
   }
   if (check2 && needsAttention) {
     process.exitCode = 1;
@@ -46967,7 +46970,6 @@ var listSkills = (scope5) => {
   }
   return parseSkillList(result.stdout);
 };
-var skillUpdateCommand = (scope5) => scope5 === "global" ? ["skills", "update", "dp-cli", "--global", "--yes"] : ["skills", "update", "dp-cli", "--project", "--yes"];
 var skillInstallCommand = () => [
   "skills",
   "add",
@@ -46977,18 +46979,6 @@ var skillInstallCommand = () => [
   "dp-cli",
   "--yes"
 ];
-var runSkillsCommand = (command) => {
-  const result = spawnSync(command[0], command.slice(1), {
-    stdio: "ignore",
-    shell: false,
-    timeout: 30000
-  });
-  return result.status === 0;
-};
-var updateDpCliSkill = (scope5) => runSkillsCommand(skillUpdateCommand(scope5));
-var installDpCliSkillGlobal = () => {
-  return runSkillsCommand(skillInstallCommand());
-};
 var checkDpCliSkillPresence = () => {
   if (!commandExists2("skills")) {
     return {
@@ -47009,37 +46999,13 @@ var checkDpCliSkillPresence = () => {
     global
   };
 };
-var maintainDpCliSkill = () => {
-  const presence = checkDpCliSkillPresence();
-  if (!presence.skillsCliAvailable) {
-    return {
-      ...presence,
-      installedGlobal: false,
-      updatedProject: false,
-      updatedGlobal: false
-    };
-  }
-  if (!presence.detected) {
-    const installedGlobal = installDpCliSkillGlobal();
-    return {
-      skillsCliAvailable: true,
-      detected: installedGlobal,
-      project: false,
-      global: installedGlobal,
-      installedGlobal,
-      updatedProject: false,
-      updatedGlobal: installedGlobal ? updateDpCliSkill("global") : false
-    };
-  }
-  return {
-    ...presence,
-    installedGlobal: false,
-    updatedProject: presence.project ? updateDpCliSkill("project") : false,
-    updatedGlobal: presence.global ? updateDpCliSkill("global") : false
-  };
-};
 
 // src/index.ts
+var startupCheckWorkerEnv = "DP_STARTUP_CHECK_WORKER";
+var startupCheckCliEnv = "DP_STARTUP_CHECK_CLI";
+var startupCheckSkillEnv = "DP_STARTUP_CHECK_SKILL";
+var startupCheckIntervalMs = Number.parseInt(process.env.DP_STARTUP_CHECK_INTERVAL_MS ?? String(12 * 60 * 60 * 1000), 10);
+var startupCheckCacheFile = path14.join(homedir2(), ".cache", "punks", "startup-check.json");
 var app = exports_Command.make("punks", {}, () => exports_Effect.sync(() => console.log(renderCommandGuide()))).pipe(exports_Command.withDescription("Devpunks AI scaffolding CLI."), exports_Command.withSubcommands([scaffoldCommand, updateCommand]));
 var cli = exports_Command.run(app, {
   name: "punks",
@@ -47061,54 +47027,76 @@ var runCliUpdateCheck = async () => {
       command: result.command
     }));
   }
-  if (result.status !== "available" || process.stdin.isTTY !== true) {
-    return;
-  }
-  const prompt4 = createInterface3({
-    input: process.stdin,
-    output: process.stderr
-  });
-  try {
-    const answer = await prompt4.question("Update punks CLI now? [y/N]: ");
-    if (!["y", "yes"].includes(answer.trim().toLowerCase())) {
-      return;
-    }
-    console.error(`punks startup checks: running \`${result.command.join(" ")}\``);
-    const update5 = spawnSync2(result.command[0], result.command.slice(1), {
-      stdio: "inherit",
-      shell: false
-    });
-    if (update5.status !== 0) {
-      console.error("punks startup checks: CLI update failed.");
-    }
-  } finally {
-    prompt4.close();
-  }
 };
 var runDpCliSkillCheck = () => {
-  const skillResult = maintainDpCliSkill();
+  const skillResult = checkDpCliSkillPresence();
   if (!skillResult.skillsCliAvailable) {
     return;
   }
-  if (skillResult.installedGlobal) {
-    console.error("punks startup checks: installed `dp-cli` skill globally.");
+  if (!skillResult.detected) {
+    console.error(`punks startup checks: \`dp-cli\` skill not found. Install it with \`${skillInstallCommand().join(" ")}\`.`);
+  }
+};
+var runStartupChecks = async ({
+  checkCli,
+  checkSkill
+}) => {
+  if (checkCli) {
+    await runCliUpdateCheck();
+  }
+  if (checkSkill) {
+    runDpCliSkillCheck();
   }
-  if (skillResult.updatedProject || skillResult.updatedGlobal) {
-    console.error("punks startup checks: updated `dp-cli` skill.");
+};
+var hasFreshStartupCheck = () => {
+  if (!Number.isFinite(startupCheckIntervalMs) || startupCheckIntervalMs <= 0) {
+    return false;
+  }
+  try {
+    const parsed = JSON.parse(readFileSync7(startupCheckCacheFile, "utf8"));
+    return typeof parsed.checkedAt === "number" && Date.now() - parsed.checkedAt < startupCheckIntervalMs;
+  } catch {
+    return false;
   }
 };
-var runStartupChecks = async () => {
+var markStartupCheckStarted = () => {
+  mkdirSync6(path14.dirname(startupCheckCacheFile), { recursive: true });
+  writeFileSync5(startupCheckCacheFile, JSON.stringify({ checkedAt: Date.now() }, null, 2));
+};
+var startBackgroundStartupChecks = () => {
   const checkCli = shouldCheckSelfUpdate();
   const checkSkill = shouldCheckDpCliSkillUpdate();
-  if (!checkCli && !checkSkill) {
+  if (!checkCli && !checkSkill || hasFreshStartupCheck()) {
     return;
   }
-  if (checkSkill) {
-    setTimeout(runDpCliSkillCheck, 0);
-  }
-  if (checkCli) {
-    await runCliUpdateCheck();
+  const entrypoint = process.argv[1];
+  if (entrypoint === undefined || !existsSync7(entrypoint)) {
+    return;
   }
-};
-runStartupChecks().catch(() => {});
-cli(process.argv).pipe(exports_Effect.provide(exports_Layer.mergeAll(exports_BunContext.layer)), exports_BunRuntime.runMain);
+  markStartupCheckStarted();
+  const worker = spawn2(process.execPath, [entrypoint], {
+    cwd: process.cwd(),
+    detached: true,
+    env: {
+      ...process.env,
+      [startupCheckWorkerEnv]: "1",
+      [startupCheckCliEnv]: checkCli ? "1" : "0",
+      [startupCheckSkillEnv]: checkSkill ? "1" : "0"
+    },
+    stdio: ["ignore", "ignore", "inherit"]
+  });
+  worker.unref();
+};
+if (process.env[startupCheckWorkerEnv] === "1") {
+  runStartupChecks({
+    checkCli: process.env[startupCheckCliEnv] === "1",
+    checkSkill: process.env[startupCheckSkillEnv] === "1"
+  }).finally(() => {
+    process.exit(0);
+  });
+} else {
+  try {
+    startBackgroundStartupChecks();
+  } catch {}
+  cli(process.argv).pipe(exports_Effect.provide(exports_Layer.mergeAll(exports_BunContext.layer)), exports_BunRuntime.runMain);
+}

package/dist/skills/agnostic/docs/docs-maintenance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docs-maintenance
-description: Ingest a spec folder into the wiki domain layer by extracting and writing flow pages first, then concept pages, then syncing ingest metadata. Secondary: update docs/ when code changes alter architecture, setup, contracts, or operator workflow. Use when a spec is ready to be captured as domain knowledge after review or implementation, or when a code task changes non-obvious behavior that docs/ should reflect.
+description: "Ingest a spec folder into the wiki domain layer by extracting and writing flow pages first, then concept pages, then syncing ingest metadata. Secondary: update docs/ when code changes alter architecture, setup, contracts, or operator workflow. Use when a spec is ready to be captured as domain knowledge after review or implementation, or when a code task changes non-obvious behavior that docs/ should reflect."
 ---
 
 # Docs Maintenance

package/dist/skills/agnostic/planning/create-plan/REFERENCE.md

@@ -33,5 +33,5 @@
 - Derive repo ownership and hosting from git state instead of hardcoding assumptions.
 - If a required tool is unavailable, stop clearly and report the missing dependency.
 - Keep the canonical backlog model aligned with [../write-backlog/assets/concepts/backlog-model.md](../write-backlog/assets/concepts/backlog-model.md).
-- For every planned task, locate the relevant scoped `AGENTS.md` chain and assign the existing skills that the executor must load before editing.
+- For every planned task, locate the relevant scoped `AGENTS.md` chain, load the relevant skill guidance during planning, and assign the existing skills that the executor must load again before editing.
 - Never start implementation from this skill.

package/dist/skills/agnostic/planning/create-plan/SKILL.md

@@ -31,7 +31,7 @@ Create a plan first. Never implement code in this skill.
 4. Update a running decision ledger after every answer so the user never has to reconstruct state from memory.
 5. Insert a synthesis checkpoint before the thread gets noisy, then continue only if more ambiguity reduction is still needed.
 6. Research with `opensrc path <package>` or `opensrc path <owner>/<repo>` plus primary-source web docs when current behavior matters.
-7. Locate scoped `AGENTS.md` files for every planned task path and extract `Primary skills here` lists.
+7. Locate scoped `AGENTS.md` files for every planned task path, extract `Primary skills here` lists, and load the relevant skill guidance before finalizing task design.
 8. Read `references/planner-phase.md` and run `$swarm-planner` as an explicit inner phase.
 9. Read `references/tdd-phase.md` and run `$tdd` as an explicit inner phase.
 10. Read `references/backlog-sync.md` and sync backlog at epic/story level, not one item per plan task.
@@ -46,10 +46,11 @@ Create a plan first. Never implement code in this skill.
 3. Every plan-shaping question must use the exact block: `Decision`, `Recommendation`, `Question`, `Why it matters`.
 4. Keep `$grill-me`, `$swarm-planner`, and `$tdd` as visible required inner phases of one planning run.
 5. Resolve each task's scoped guidance from root `AGENTS.md` down to the nearest `AGENTS.md` for its `location`.
-6. Assign each task the exact existing skills required by those scoped `Primary skills here` lists, merging all scopes for cross-directory tasks.
-7. Normalize every task with stable ids, `depends_on`, `location`, `description`, `validation`, `status`, `log`, `files edited/created`, owning-story backlog references, `assigned_skills`, `tdd_target`, and `review_mode`.
-8. Keep the saved plan standalone: include situation, issue, solution shape, assumptions, findings, research, dependency graph, testing strategy, skill-routing notes, risks, validation gates, unresolved questions, and a resolved decision ledger.
-9. Stop after plan creation and backlog sync. Do not implement code or spawn implementation workers.
+6. Use each task's required skill guidance while shaping its scope, dependencies, validation, RED target, and review mode; do not merely list skills after the plan is written.
+7. Assign each task the exact existing skills required by those scoped `Primary skills here` lists, merging all scopes for cross-directory tasks.
+8. Normalize every task with stable ids, `depends_on`, `location`, `description`, `validation`, `status`, `log`, `files edited/created`, owning-story backlog references, `assigned_skills`, `tdd_target`, and `review_mode`.
+9. Keep the saved plan standalone: include situation, issue, solution shape, assumptions, findings, research, dependency graph, testing strategy, skill-routing notes, risks, validation gates, unresolved questions, and a resolved decision ledger.
+10. Stop after plan creation and backlog sync. Do not implement code or spawn implementation workers.
 
 ### Review modes
 

package/dist/skills/agnostic/planning/create-plan/references/grill-phase.md

@@ -57,7 +57,8 @@ Preserve `$grill-me` behavior:
 - provide a recommended answer with each question
 - if a question can be answered from the codebase, answer it by inspecting instead
 - keep grilling until every plan-shaping branch is resolved enough to plan safely
-- when the user leaves a branch open, record the assumption explicitly in the plan
+- before recording an unresolved question in the plan, ask the user whether to resolve it now or defer it
+- when the user defers a branch, record the assumption or unresolved question explicitly in the plan with its planning impact
 
 ## Decision ledger
 

package/dist/skills/agnostic/planning/create-plan/references/plan-schema.md

@@ -22,6 +22,8 @@ Include:
 - validation gates per phase when phases exist
 - unresolved questions
 
+`unresolved questions` is not a hiding place for skipped planning. Before saving a plan with unresolved questions, prompt the user to resolve each plan-shaping question that they can reasonably answer now. Keep only deferred, externally blocked, or non-blocking questions, and state why each remains open.
+
 ## Task contract
 
 Every task must include:
@@ -47,6 +49,8 @@ Multiple tasks may point to the same story when one story needs several executio
 
 Do not create a new backlog item only because a task boundary exists in the plan.
 
+`assigned_skills` must list the skills used to shape the task during planning, not only skills expected during implementation. Skill guidance should be reflected in the task's boundary, validation, `tdd_target`, and `review_mode`.
+
 ```md
 ### T3: Example task
 

package/dist/skills/agnostic/planning/create-plan/references/planner-phase.md

@@ -18,10 +18,13 @@ Before finalizing task boundaries:
 2. For each location, inspect the `AGENTS.md` chain from repo root to the nearest scoped file.
 3. Extract every `Primary skills here` entry from applicable scoped files.
 4. Verify each named skill exists in `.agents/skills/` or an installed skill source visible to the agent.
-5. Add the merged, deduplicated list to the task as `assigned_skills`.
+5. Load the relevant skill instructions before finalizing the task's boundary, validation, RED target, and review mode.
+6. Add the merged, deduplicated list to the task as `assigned_skills`.
 
 If a task spans multiple scopes, include all required skills from all touched scopes. If a scope names a missing skill, keep the task planned but record the missing skill in risks and unresolved questions.
 
+`assigned_skills` is both planning input and executor handoff. Do not design the task first and attach skills afterward. Use the skill guidance to decide what a correct task slice, dependency, validation, and test target should look like.
+
 ## Planner behavior
 
 Produce exactly one named `PLAN.md` in the target spec folder.
@@ -33,7 +36,7 @@ Preserve `$swarm-planner` behavior:
 - validations per task
 - parallel execution waves
 - risks and mitigations
-- explicit `assigned_skills` per task from scoped `AGENTS.md`
+- explicit `assigned_skills` per task from scoped `AGENTS.md`, with task design shaped by those skills
 - a final subagent review for missing deps, ordering issues, edge cases, and holes before yielding
 
 Do not stop between the grill and planner phases unless a true blocking ambiguity remains.

package/dist/skills/agnostic/planning/create-spec/SKILL.md

@@ -10,7 +10,7 @@ description: Create a SPEC.md file for a new feature, product, or system using t
 - **Role:** higher-order spec authoring skill
 - **Entrypoint type:** public entrypoint
 - **Upstream:** new idea, feature request, epic/capability issue, or problem statement
-- **Delegates to:** none
+- **Delegates to:** `$requirements-grill` when discovery leaves meaningful spec-affecting unknowns; `$write-backlog` when grill outcomes change epic/story scope
 - **Downstream:** reviewed `SPEC.md`, then usually `create-plan` or `implement-spec`
 - **Entry conditions:** wiki domain can be resolved, or the user creates one first with `create-wiki-domain`
 - **Stop conditions:** `SPEC.md`, wiki index, and wiki log are updated, then wait for user review
@@ -27,12 +27,14 @@ The output lives at `apps/wiki/specs/<domain>/<folder-name>/SPEC.md`.
 2. Read `references/discovery.md` and orient yourself in the right wiki domain before asking questions.
 3. If backlog context exists, read the parent epic and every child story before asking questions.
 4. If the user did not provide a concrete request, ask for a rough description first.
-5. Read `references/questioning.md` and ask only the clarifying questions needed to write a trustworthy spec.
-6. Read `references/folder-naming.md` to resolve the domain and spec folder path.
-7. Read `assets/SPEC-TEMPLATE.md` and write the spec.
-8. Read `references/spec-quality-bar.md` before saving.
-9. Read `references/wiki-bookkeeping.md` to update `index.md`, `<domain>-specs.md`, and `log.md`.
-10. Read `references/handoff.md` to choose the next-step recommendation and stop after user review.
+5. Read `references/questioning.md` and ask only the lightweight clarifying questions needed to identify whether a grill phase is required.
+6. If draft `Open Questions` would affect spec trust, read `references/grill-phase.md` and run a bounded `$requirements-grill` phase before writing.
+7. If the grill changes accepted scope, child stories, deferred scope, or story order, read `references/backlog-sync.md` and run `$write-backlog` to sync the backlog automatically.
+8. Read `references/folder-naming.md` to resolve the domain and spec folder path.
+9. Read `assets/SPEC-TEMPLATE.md` and write the spec.
+10. Read `references/spec-quality-bar.md` before saving.
+11. Read `references/wiki-bookkeeping.md` to update `index.md`, `<domain>-specs.md`, and `log.md`.
+12. Read `references/handoff.md` to choose the next-step recommendation and stop after user review.
 
 ## Workflow
 
@@ -41,15 +43,19 @@ The output lives at `apps/wiki/specs/<domain>/<folder-name>/SPEC.md`.
 1. Build orientation first; do not jump straight into writing.
 2. Ask only enough to make the spec crisp, testable, and bounded.
 3. When an epic has child stories, harvest and preserve each story's requirements before drafting.
-4. Keep the spec free of implementation detail.
-5. Use the template structure exactly, then remove all template scaffolding.
-6. Update wiki bookkeeping in the same run.
-7. Stop after presenting the spec and the recommended next step.
+4. Use `$requirements-grill` for meaningful spec-affecting unknowns; do not replace that phase with ad hoc `Open Questions` prompts.
+5. After a grill phase, use `$write-backlog` automatically when accepted decisions imply backlog changes.
+6. Keep the spec free of implementation detail.
+7. Use the template structure exactly, then remove all template scaffolding.
+8. Update wiki bookkeeping in the same run.
+9. Stop after presenting the spec and the recommended next step.
 
 ## Advanced features
 
 - Discovery and repo orientation: see [references/discovery.md](references/discovery.md)
 - Clarifying-question strategy: see [references/questioning.md](references/questioning.md)
+- Requirements grill phase: see [references/grill-phase.md](references/grill-phase.md)
+- Backlog sync after grilling: see [references/backlog-sync.md](references/backlog-sync.md)
 - Domain and folder naming rules: see [references/folder-naming.md](references/folder-naming.md)
 - Acceptance-criteria and quality bar: see [references/spec-quality-bar.md](references/spec-quality-bar.md)
 - Wiki index and log updates: see [references/wiki-bookkeeping.md](references/wiki-bookkeeping.md)

package/dist/skills/agnostic/planning/create-spec/assets/SPEC-TEMPLATE.md

@@ -74,7 +74,7 @@ _Optional. Technical discoveries, known system constraints, or early implementat
 
 ## Open Questions
 
-_Unresolved questions that could affect implementation._
+_Unresolved questions that could affect implementation. Before saving, route meaningful spec-affecting unknowns through the requirements-grill phase. Only keep questions here when the user explicitly defers them, the answer requires external validation, or the issue is non-blocking for spec review._
 
 | # | Question | Affects | Owner | Status |
 |---|----------|---------|-------|--------|

package/dist/skills/agnostic/planning/create-spec/references/backlog-sync.md

@@ -0,0 +1,46 @@
+# Backlog Sync
+
+Use after `$requirements-grill` and before final spec drafting.
+
+## Trigger
+
+Run `$write-backlog` automatically when grill outcomes change:
+
+- the epic/capability boundary
+- child-story acceptance signals, scope, or canonical terms
+- missing, parked, moved, or future-scope stories
+- story ordering, blockers, or parent/child relationships
+
+Skip only for wording clarifications that do not change backlog scope, story meaning, or ordering.
+
+## Load
+
+Follow:
+
+- `../../../requirements/write-backlog/SKILL.md`
+- `../../../requirements/write-backlog/REFERENCE.md`
+- `../../../requirements/write-backlog/assets/concepts/backlog-model.md`
+
+If grill artifacts exist, read:
+
+1. `docs/<topic>-grill-status.md`
+2. `docs/<topic>-grill-log.md`
+
+## Rules
+
+- The parent epic remains the spec anchor.
+- Child stories remain product-facing slices beneath that epic.
+- Derive backlog changes only from accepted decisions and locked direction.
+- Preserve parked branches as deferred scope, follow-up epic/story candidates, or backlog notes.
+- Keep unresolved still-open items out of committed story scope unless explicitly marked.
+- Use native parent/child and `blockedBy` / `blocks` relations when the provider supports them.
+- Do not add implementation details, file paths, TDD targets, validation commands, or worker handoffs to backlog bodies.
+
+## Handoff
+
+- reread the updated epic and child stories before drafting
+- incorporate all child-story requirements into the spec
+- add backlog item ids/URLs to spec links when available
+- mention deferred backlog items only as non-goals, future scope, or `Open Questions`
+
+Do not finalize a backlog-backed spec from stale pre-grill story text.

package/dist/skills/agnostic/planning/create-spec/references/grill-phase.md

@@ -0,0 +1,47 @@
+# Grill Phase
+
+Use after discovery/questioning when unresolved spec questions would affect review trust.
+
+## Trigger
+
+Run bounded `$requirements-grill` when:
+
+- multiple child stories conflict or leave cross-story behavior unclear
+- the target actor, outcome, boundary, non-goal, or acceptance signal is ambiguous
+- candidate `Open Questions` would materially change scope, trust, or acceptance criteria
+
+Use lightweight direct clarification instead when only one small naming or wording detail is missing.
+
+## Load
+
+Follow:
+
+- `../../../requirements/requirements-grill/references/grilling-flow.md`
+- `../../../requirements/requirements-grill/references/artifact-output.md` for serious grilling sessions
+
+## Rules
+
+- Ask one question at a time by default.
+- Include a recommended answer and why it is preferred.
+- Inspect repo/docs/backlog first when the answer can be found locally.
+- Force precise choices when multiple interpretations exist.
+- Close, park, or explicitly defer each branch.
+
+## Artifacts
+
+For serious sessions, create or reuse:
+
+- `docs/<topic>-grill-log.md`
+- `docs/<topic>-grill-status.md`
+
+Tiny clarification-only runs do not need durable grill artifacts.
+
+## Handoff
+
+- accepted answers become requirements, constraints, non-goals, acceptance criteria, or decisions
+- parked branches outside the epic become non-goals or future scope
+- explicitly deferred branches become `Open Questions`
+- external-validation branches become `Open Questions` with owner/status
+- accepted scope changes must flow through `backlog-sync.md` before final spec drafting
+
+Do not write the spec until each discovered branch is closed, parked, or explicitly deferred.

package/dist/skills/agnostic/planning/create-spec/references/questioning.md

@@ -4,7 +4,9 @@ Use this reference after discovery and before writing.
 
 ## Goal
 
-Ask only enough to produce a useful, bounded spec. A vague spec creates false confidence.
+Ask only enough to decide whether the spec is ready to draft or needs a bounded `$requirements-grill` phase. A vague spec creates false confidence.
+
+Before writing `Open Questions`, route meaningful spec-affecting unknowns through `grill-phase.md`. Do not silently invent an open-question table as a substitute for requirements work.
 
 ## Priority topics
 
@@ -27,6 +29,8 @@ Surface these as needed:
 - If a fact is ambiguous and matters to the spec, ask directly.
 - Prefer concrete examples over abstract wording.
 - When backlog context exists, ask about cross-story interactions only after reading all child stories first.
+- If multiple or material unknowns remain, stop lightweight questioning and run the grill phase.
+- If a tiny unknown would become an `Open Question`, ask whether the user can resolve it now or wants to defer it.
 
 ## Stop asking when
 
@@ -38,4 +42,10 @@ Surface these as needed:
 - major functional requirements are identifiable
 - key non-goals are explicit
 
-If a branch remains open, capture it as an open question or assumption inside the spec rather than pretending certainty.
+Only leave `Open Questions` in the spec when one of these is true:
+
+- the user explicitly chose to defer the question
+- the answer requires external validation outside the current spec session
+- the question is non-blocking and the spec can still be reviewed honestly
+
+If a branch remains open after the grill phase or lightweight prompt, capture it as an open question or assumption inside the spec rather than pretending certainty. Include the prompt/grill outcome so reviewers know why it remains unresolved.

package/docs/README.md

@@ -3,6 +3,12 @@
 - [Requirements](./reference/dp-requirements.md)
 - [Scaffolding runbook](./runbooks/dp-cli-scaffolding.md)
 
+Domain knowledge:
+
+- [Wiki index](../wiki/index.md)
+
+The wiki is the durable domain layer for specs, raw inputs, flows, and concepts. Keep operator runbooks and implementation reference in `docs/`; keep stable product/domain knowledge in `wiki/`.
+
 Implementation notes:
 
 - canonical bundled scaffold metadata and shared assets live in `src/data/`
@@ -11,12 +17,12 @@ Implementation notes:
 - distributed skill assets live in `skills/`
 - runtime projection/writing logic lives in `src/scaffold/`
 - `punks update` refreshes scaffold-managed assets from `.devpunks/scaffold-manifest.json`
-- CLI startup checks npm's `latest` dist-tag and prompts before CLI package updates; it auto-installs/updates only the named `dp-cli` skill through targeted `skills add ... --skill dp-cli` / `skills update dp-cli ...` commands. Set `DP_NO_UPDATE_CHECK=1` or `DP_NO_SKILL_UPDATE_CHECK=1` to skip those checks, and `DP_UPDATE_TAG=next` to compare against another dist-tag.
+- CLI startup checks run in a detached advisory worker at most once per 12 hours by default. They check npm's `latest` dist-tag and whether the named `dp-cli` skill is present, but startup never installs or updates packages/skills while another CLI command is starting. Set `DP_NO_UPDATE_CHECK=1` or `DP_NO_SKILL_UPDATE_CHECK=1` to skip those checks, `DP_UPDATE_TAG=next` to compare against another dist-tag, and `DP_STARTUP_CHECK_INTERVAL_MS=0` to force the worker during local testing.
 - baseline releases use `baseline/stable/*` GitHub release tags, separate from npm executable tags such as `v1.0.1`
-- shared neutral hook and sync assets live in `src/data/hooks/` and `src/data/scripts/`
+- shared neutral hook and sync assets live in `src/data/hooks/` and `src/data/scripts/`; hook commands infer the target repo package manager from `packageManager` and lockfiles
 - scaffolded required tools always include `portless` and `skills` so generated guidance can standardize local dev origins and keep skill entrypoints up to date
 - `punks scaffold setup` checks the base required tools (`portless`, `skills`) before repo detection and checks selected-pack tools after pack confirmation.
-- Oxlint specs/starter config are scaffolded only when scanned manifests already declare `oxlint`; the auto format/lint hook is scaffolded only when manifests declare `oxfmt`. Other lint/format stacks are intentionally left untouched for now.
+- Oxlint specs/starter config are scaffolded only when scanned manifests already declare `oxlint`; the auto format/lint hook is scaffolded only when manifests declare `oxfmt`. PR creation is not gated by a scaffolded test-suite hook. Other lint/format stacks are intentionally left untouched for now.
 - the default debug pack scaffolds the local `debug-agent` skill and installs/verifies the `debug-agent` CLI without running its agent-install wizard
 - scaffolded repos keep project-local skills in `.agents/skills/`; only `.claude/skills` is a compatibility symlink mirror
 - React scaffold surfaces include `async-react-patterns` alongside the existing React composition, structure, and Vercel guidance so agents avoid outdated manual async state patterns.

package/docs/harness-intelligence-grill-log.md

@@ -0,0 +1,39 @@
+# Harness Intelligence Grill Log
+
+This log records locked requirements decisions for rethinking this repo as the Harness Intelligence project.
+
+## Initial Situation
+
+The repo currently provides real value as the `punks`/`dp` scaffolding CLI plus canonical scaffold baseline data. It has battle-tested workflow assets, repo-aware setup behavior, baseline publishing, and a local wiki-shaped knowledge tree.
+
+The repo does not yet provide the full product/distribution surface needed for wider colleague adoption or public company communication:
+
+- no Turborepo application layout
+- no public Fumadocs wiki/docs app
+- no public landing page
+- no Effect backend for scaffold distribution, validation, or future orchestration
+- no settled CLI-vs-backend boundary
+- no durable explanation of harness theory, criteria, trust model, and sales/marketing narrative
+
+## Branches
+
+### Branch A: Product Boundary
+
+Purpose: define what "Harness Intelligence" is as a product/system, and what this repo must own.
+
+### Branch B: Distribution Architecture
+
+Purpose: define Turborepo shape, app/package boundaries, backend role, CLI role, baseline/data flow, and public surfaces.
+
+### Branch C: Wiki and Theory
+
+Purpose: define the docs knowledge model, Fumadocs information architecture, and the harness engineering criteria currently living in the user's head.
+
+### Branch D: Trust and Adoption
+
+Purpose: define what colleagues need to trust the AI harness setup, how validation works, and what proof material must exist.
+
+### Branch E: Company Communication
+
+Purpose: define landing-page and sales narrative for how Devpunks engineers are AI-superpowered without becoming vague marketing copy.
+

package/docs/harness-intelligence-grill-status.md

@@ -0,0 +1,25 @@
+# Harness Intelligence Grill Status
+
+Current grill artifacts:
+
+- Log: `docs/harness-intelligence-grill-log.md`
+- Status: `docs/harness-intelligence-grill-status.md`
+
+## Branch Dashboard
+
+| Branch | Completion | Locked direction | Still open |
+| --- | ---: | --- | --- |
+| Product Boundary | 10% | Repo is being reconsidered as the Harness Intelligence project, not only a CLI package. | Canonical product definition, audience split, repo ownership boundary. |
+| Distribution Architecture | 10% | Target mentions Turborepo, public docs app, landing page, Effect backend, and CLI. | App/package boundaries, backend-vs-CLI responsibilities, data/source-of-truth flow. |
+| Wiki and Theory | 10% | Existing wiki shape exists locally; missing public Fumadocs app and full theory/criteria content. | IA, criteria taxonomy, private vs public knowledge split, docs ownership. |
+| Trust and Adoption | 10% | Colleague recognition/validation is a primary requirement. | Trust evidence, onboarding path, validation gates, adoption metrics. |
+| Company Communication | 10% | Public explanation must support sales/marketing around AI-superpowered developers. | Landing page promise, proof points, tone, relationship to devpunks.com. |
+
+## Parked Branches
+
+- None yet.
+
+## Current Question
+
+Q1: Product Boundary.
+

package/docs/runbooks/dp-cli-scaffolding.md

@@ -95,6 +95,7 @@ Current scope:
 - check the base required tools (`portless`, `skills`) at the start of setup before repo detection, then check selected-pack tools after pack confirmation
 - include `debug-agent` through the default debug pack and install/verify the `debug-agent` CLI without running `debug-agent init`, because the CLI already scaffolds the project-local skill
 - scaffold Oxlint specs/starter config only when scanned package manifests declare `oxlint`, and scaffold the `format-edited-file` Oxfmt/Oxlint hook only when manifests declare `oxfmt`; repos without those tools keep their existing lint/format setup untouched
+- scaffolded hooks infer the target repo package manager from `packageManager` first, then lockfiles, so Oxfmt/Oxlint execution does not hardcode the CLI repo's package manager
 - select language packs separately from framework packs; TypeScript is selected from a `typescript` package dependency or nested `.ts` / `.tsx` files, and Python is selected from nested `.py` files, while ignoring root config files plus vendor, virtualenv, scaffold, docs, examples, scripts, `opensrc`, cache, and build output
 - seed Python subagent templates that combine the Python language skills into `python-app`, `python-async`, and `python-testing` specialists
 - seed a read-only `code-review` subagent template that uses `simplify` for changed-code cleanup review and `improve-codebase-architecture` for grounded architecture-friction findings
@@ -217,14 +218,15 @@ The npm account must have publish access to `@punks/cli`; otherwise npm may repo
 
 ## CLI Self-Update Detection
 
-The CLI also starts best-effort startup checks on normal command startup. It checks the npm package version for `@punks/cli`, and it checks the `dp-cli` skill through the `skills` CLI. CLI package updates require an interactive `y/N` confirmation before running the inferred package-manager command. The `dp-cli` skill is auto-installed when missing and auto-updated when present, but only through targeted `skills add ... --skill dp-cli` / `skills update dp-cli ...` commands. Startup must never run or suggest plain root `skills update`. These checks are separate from `punks update`, which updates scaffold-managed repo assets.
+The CLI may start best-effort startup checks on normal command startup. The requested command must render immediately; checks run in a detached worker and are rate-limited by a local cache marker to at most once per 12 hours by default. The worker checks the npm package version for `@punks/cli`, and it checks the `dp-cli` skill through the `skills` CLI. It only prints advisory install/update commands. Startup must never install or update packages/skills while another CLI command is starting, and it must never run or suggest plain root `skills update`. These checks are separate from `punks update`, which updates scaffold-managed repo assets.
 
 - checks `https://registry.npmjs.org/%40punks%2Fcli/latest`
 - compares that dist-tag version with the bundled CLI version
-- prompts to run the inferred package-manager command only when the registry version is newer
+- prints the inferred package-manager update command only when the registry version is newer
 - silently skips the notice when npm is unreachable, the registry response is invalid, or the command is `--help` / `--version`
 - skips in CI and when `DP_NO_UPDATE_CHECK=1`
 - supports `DP_UPDATE_TAG=next` for canary/operator testing against another dist-tag
+- supports `DP_STARTUP_CHECK_INTERVAL_MS=0` to force the detached worker during local testing
 
 To test the built command locally without preparing another repo first, use the committed fixtures:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punks/cli",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "description": "Devpunks AI scaffolding CLI",
   "type": "module",
   "bin": {

package/dist/data/hooks/format-edited-file.py

@@ -1,157 +0,0 @@
-#!/usr/bin/env python3
-
-from __future__ import annotations
-
-import hashlib
-import json
-import os
-import subprocess
-import sys
-from pathlib import Path
-
-SUPPORTED_SUFFIXES = (".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json")
-IGNORED_PARTS = {".git", "node_modules", ".next", "dist"}
-
-
-def read_input() -> dict[str, object]:
-    try:
-        return json.load(sys.stdin)
-    except json.JSONDecodeError:
-        return {}
-
-
-def run_git(args: list[str], cwd: str) -> str:
-    result = subprocess.run(
-        ["git", "-C", cwd, *args],
-        check=True,
-        capture_output=True,
-        text=True,
-    )
-    return result.stdout
-
-
-def repo_root(cwd: str) -> str:
-    try:
-        return run_git(["rev-parse", "--show-toplevel"], cwd).strip()
-    except subprocess.CalledProcessError:
-        return ""
-
-
-def dirty_files(root: str) -> list[str]:
-    try:
-        output = run_git(["ls-files", "-m", "-o", "--exclude-standard"], root)
-    except subprocess.CalledProcessError:
-        return []
-
-    files: list[str] = []
-    for raw_path in output.splitlines():
-        path = raw_path.strip()
-        if not path:
-            continue
-        if not path.endswith(SUPPORTED_SUFFIXES):
-            continue
-        if any(part in IGNORED_PARTS for part in Path(path).parts):
-            continue
-        files.append(path)
-
-    return sorted(set(files))
-
-
-def file_hash(path: Path) -> str:
-    digest = hashlib.sha256()
-    with path.open("rb") as handle:
-        for chunk in iter(lambda: handle.read(65536), b""):
-            digest.update(chunk)
-    return digest.hexdigest()
-
-
-def snapshot_path(root: str, session_id: str, tool_use_id: str) -> Path:
-    repo_name = Path(root).name or "repo"
-    safe_session_id = session_id.replace("/", "_")
-    safe_tool_use_id = tool_use_id.replace("/", "_")
-    state_dir = Path(os.environ.get("TMPDIR", "/tmp")) / "codex-hooks" / repo_name / safe_session_id
-    state_dir.mkdir(parents=True, exist_ok=True)
-    return state_dir / f"{safe_tool_use_id}.json"
-
-
-def load_snapshot(path: Path) -> dict[str, str]:
-    if not path.exists():
-        return {}
-    try:
-        return json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return {}
-
-
-def fingerprints(root: str) -> dict[str, str]:
-    snapshot: dict[str, str] = {}
-    for relative_path in dirty_files(root):
-        absolute_path = Path(root) / relative_path
-        if absolute_path.exists():
-            snapshot[relative_path] = file_hash(absolute_path)
-    return snapshot
-
-
-def format_files(root: str, files: list[str]) -> list[str]:
-    failed: list[str] = []
-    for relative_path in files:
-        absolute_path = Path(root) / relative_path
-        result = subprocess.run(
-            ["npx", "oxfmt", "--write", str(absolute_path)],
-            cwd=root,
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-            check=False,
-        )
-        if result.returncode != 0:
-            failed.append(relative_path)
-    return failed
-
-
-def emit_failure(files: list[str]) -> None:
-    message = "Auto-format failed for " + ", ".join(files) + ". Review the file and format it manually if needed."
-    print(json.dumps({"systemMessage": message}))
-
-
-def main() -> int:
-    mode = sys.argv[1] if len(sys.argv) > 1 else ""
-    payload = read_input()
-
-    cwd = str(payload.get("cwd") or os.getcwd())
-    session_id = str(payload.get("session_id") or "")
-    tool_use_id = str(payload.get("tool_use_id") or "")
-    root = repo_root(cwd)
-
-    if not root or not session_id or not tool_use_id:
-        return 0
-
-    state_file = snapshot_path(root, session_id, tool_use_id)
-
-    if mode == "pre":
-        state_file.write_text(json.dumps(fingerprints(root), sort_keys=True), encoding="utf-8")
-        return 0
-
-    if mode != "post":
-        return 0
-
-    previous = load_snapshot(state_file)
-    current = fingerprints(root)
-
-    try:
-        state_file.unlink()
-    except OSError:
-        pass
-
-    touched = [path for path, digest in current.items() if previous.get(path) != digest]
-    if not touched:
-        return 0
-
-    failed = format_files(root, touched)
-    if failed:
-        emit_failure(failed)
-
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/dist/data/hooks/require-tests-for-pr.mjs

@@ -1,144 +0,0 @@
-#!/usr/bin/env node
-
-import { spawnSync } from "node:child_process";
-import { readFileSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const denyMessage = "Tests are failing. Fix all test failures before creating a PR.";
-const prCommandPattern = /\bgh\s+pr\s+create\b/i;
-const prToolPattern = /(^|[._-])create[_-]?pull[_-]?request([._-]|$)/i;
-
-function readStdinJson() {
-  try {
-    return JSON.parse(readFileSync(0, "utf8"));
-  } catch {
-    return {};
-  }
-}
-
-function runGit(args, cwd) {
-  const result = spawnSync("git", ["-C", cwd, ...args], {
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "ignore"],
-  });
-
-  return result.status === 0 ? result.stdout : null;
-}
-
-function repoRoot(cwd) {
-  return runGit(["rev-parse", "--show-toplevel"], cwd)?.trim() ?? "";
-}
-
-function collectStrings(value, values = []) {
-  if (typeof value === "string") {
-    const trimmed = value.trim();
-    if (trimmed) {
-      values.push(trimmed);
-    }
-    return values;
-  }
-
-  if (Array.isArray(value)) {
-    for (const entry of value) {
-      collectStrings(entry, values);
-    }
-    return values;
-  }
-
-  if (!value || typeof value !== "object") {
-    return values;
-  }
-
-  for (const entry of Object.values(value)) {
-    collectStrings(entry, values);
-  }
-
-  return values;
-}
-
-function matchesPrAction(...values) {
-  const strings = [...new Set(values.flatMap((value) => collectStrings(value)))];
-
-  return strings.some((value) => prCommandPattern.test(value) || prToolPattern.test(value));
-}
-
-function runTests(root) {
-  const result = spawnSync("pnpm", ["--silent", "test"], {
-    cwd: root,
-    stdio: "ignore",
-  });
-
-  return result.status === 0;
-}
-
-function emitCodexOrClaudeBlock(message) {
-  process.stdout.write(
-    JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: "PreToolUse",
-        permissionDecision: "deny",
-        permissionDecisionReason: message,
-      },
-      systemMessage: message,
-    }),
-  );
-}
-
-function emitCursorBlock(message) {
-  process.stdout.write(
-    JSON.stringify({
-      continue: false,
-      permission: "deny",
-      agent_message: message,
-      user_message: message,
-    }),
-  );
-}
-
-function runCommandHook(style) {
-  const payload = readStdinJson();
-  const root = repoRoot(String(payload.cwd ?? process.cwd()));
-
-  if (!root || !matchesPrAction(payload) || runTests(root)) {
-    return;
-  }
-
-  if (style === "cursor") {
-    emitCursorBlock(denyMessage);
-    return;
-  }
-
-  emitCodexOrClaudeBlock(denyMessage);
-}
-
-export const RequireTestsForPrPlugin = async ({ worktree }) => {
-  return {
-    "tool.execute.before": async (input, output) => {
-      if (!matchesPrAction(input?.tool, output?.args?.command)) {
-        return;
-      }
-
-      if (runTests(worktree)) {
-        return;
-      }
-
-      throw new Error(denyMessage);
-    },
-  };
-};
-
-function main() {
-  const mode = process.argv[2] ?? "";
-
-  if (mode === "claude" || mode === "codex" || mode === "cursor") {
-    runCommandHook(mode);
-  }
-}
-
-const invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : "";
-const modulePath = fileURLToPath(import.meta.url);
-
-if (invokedPath && path.basename(invokedPath) === path.basename(modulePath)) {
-  main();
-}