@punks/cli 1.0.4 → 1.0.6

package/README.md

@@ -67,7 +67,7 @@ Current scaffold-managed global tools:
 - `portless`
 - `skills`
 
-On startup, `punks` checks npm for a newer CLI version. When it can infer whether the installed binary came from Bun, pnpm, or npm, it updates itself with the same global package manager; otherwise it prints a manual update hint. If the `dp-cli` operator skill is installed in the current project or globally, startup also asks the `skills` CLI to update that skill. 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/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/require-tests-for-pr.mjs

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 
 import { spawnSync } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { existsSync, 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;
+const packageManagers = new Set(["bun", "pnpm", "npm", "yarn"]);
 
 function readStdinJson() {
   try {
@@ -63,8 +64,65 @@ function matchesPrAction(...values) {
   return strings.some((value) => prCommandPattern.test(value) || prToolPattern.test(value));
 }
 
+function readPackageJson(root) {
+  try {
+    return JSON.parse(readFileSync(path.join(root, "package.json"), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function packageManagerFromPackageJson(root) {
+  const packageManager = readPackageJson(root)?.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 testCommand(root) {
+  switch (packageManagerFromPackageJson(root) ?? packageManagerFromLockfile(root) ?? "npm") {
+    case "bun":
+      return ["bun", "run", "test"];
+    case "pnpm":
+      return ["pnpm", "--silent", "test"];
+    case "yarn":
+      return ["yarn", "--silent", "test"];
+    case "npm":
+    default:
+      return ["npm", "--silent", "test"];
+  }
+}
+
 function runTests(root) {
-  const result = spawnSync("pnpm", ["--silent", "test"], {
+  const command = testCommand(root);
+  const result = spawnSync(command[0], command.slice(1), {
     cwd: root,
     stdio: "ignore",
   });
@@ -128,6 +186,10 @@ export const RequireTestsForPrPlugin = async ({ worktree }) => {
   };
 };
 
+export const testHooks = {
+  testCommand,
+};
+
 function main() {
   const mode = process.argv[2] ?? "";
 

package/dist/data/hooks.test.ts

@@ -0,0 +1,87 @@
+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("runs the PR test gate with the repo package manager", async () => {
+    const { testHooks } = await loadHookModule("require-tests-for-pr.mjs");
+
+    expect(
+      testHooks.testCommand?.(
+        tempRepo({
+          "package.json": JSON.stringify({ packageManager: "bun@1.3.5" }),
+        }),
+      ),
+    ).toEqual(["bun", "run", "test"]);
+
+    expect(
+      testHooks.testCommand?.(
+        tempRepo({
+          "package.json": JSON.stringify({ packageManager: "pnpm@10.0.0" }),
+        }),
+      ),
+    ).toEqual(["pnpm", "--silent", "test"]);
+
+    expect(
+      testHooks.testCommand?.(
+        tempRepo({
+          "package.json": "{}",
+          "package-lock.json": "",
+        }),
+      ),
+    ).toEqual(["npm", "--silent", "test"]);
+  });
+
+  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/index.js

@@ -10883,6 +10883,17 @@ var require_public_api = __commonJS((exports) => {
   exports.stringify = stringify;
 });
 
+// src/index.ts
+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 = {};
 __export(exports_Array, {
@@ -42283,16 +42294,15 @@ var toolCatalog = [
   }
 ];
 
-// src/version.ts
-var cliPackageName = "@punks/cli";
-var cliVersion = "1.0.4";
-
+// package.json
+var name = "@punks/cli";
+var version = "1.0.6";
 // src/baseline/bundled.ts
 var bundledBaseline = {
   summary: {
     source: "bundled",
     channel: "bundled",
-    version: cliVersion,
+    version,
     tag: null,
     commit: null,
     sha256: null
@@ -42778,8 +42788,8 @@ var collectPackageNames = (pkg) => {
     if (!record2) {
       return;
     }
-    for (const name of Object.keys(record2)) {
-      names.add(name);
+    for (const name2 of Object.keys(record2)) {
+      names.add(name2);
     }
   };
   addEntries(pkg.dependencies);
@@ -43570,12 +43580,13 @@ var renderHint = (value5) => paint(brandPalette.muted, value5);
 var renderSelfUpdateNotice = ({
   currentVersion,
   latestVersion,
-  packageName
+  packageName,
+  command
 }) => renderPanel("CLI update available", [
   `${packageName} ${currentVersion} is behind ${latestVersion}.`,
   "",
   "usage:",
-  `  \u2022 run \`npm install -g ${packageName}@latest\` to update this CLI`
+  `  \u2022 run \`${command?.join(" ") ?? `npm install -g ${packageName}@latest`}\` to update this CLI`
 ].join(`
 `));
 var renderQuestion = (value5) => [
@@ -44075,8 +44086,8 @@ var packsForWorkspace = ({
   const dependencyNames = manifest?.dependencies ?? [];
   const dependencies = new Set(dependencyNames);
   const selectedPacks = new Set(finalPacks);
-  const hasDependency = (name) => dependencies.has(name);
-  const hasDependencyPrefix = (prefix) => dependencyNames.some((name) => name.startsWith(prefix));
+  const hasDependency = (name2) => dependencies.has(name2);
+  const hasDependencyPrefix = (prefix) => dependencyNames.some((name2) => name2.startsWith(prefix));
   const hasBackendDependency = () => hasDependency("better-auth") || hasDependency("drizzle-orm") || hasDependency("drizzle-kit") || hasDependency("elysia") || hasDependencyPrefix("@trpc/");
   const hasFrontendDependency = () => hasDependency("next") || hasDependency("react") || hasDependency("react-dom") || hasDependency("@tanstack/react-query");
   const hasFrontendWorkspaceName = () => relativeWorkspacePath.split(path8.sep).some((segment) => segment === "frontend" || segment === "ui" || segment === "web") || (manifest?.packageName?.replace(/^@[^/]+\//u, "").split(/[^a-zA-Z0-9]+/u).filter((segment) => segment.length > 0).map((segment) => segment.toLowerCase()).some((segment) => segment === "frontend" || segment === "ui" || segment === "web") ?? false);
@@ -44682,7 +44693,7 @@ var writeScaffoldOutput = ({
       lintAssets,
       subagentManifestSpec,
       baseline: baseline.summary,
-      cliVersion,
+      version,
       managedFiles,
       generatedFiles: manifestGeneratedFiles
     })
@@ -46418,7 +46429,7 @@ var managedFileSchema = Struct({
 });
 var scaffoldManifestSchema = parseJson(Struct({
   repoShapeMode: optional(String$),
-  cliVersion: optional(String$),
+  version: optional(String$),
   finalPacks: Array$(String$),
   baseline: optional(Unknown),
   generatedFiles: optional(Array$(String$)),
@@ -46835,7 +46846,7 @@ var checkSelfUpdate = async ({
     updateAvailable: isNewerVersion(latestVersion, currentVersion)
   };
 };
-var commandExists2 = (command) => spawnSync("which", [command], { stdio: "ignore" }).status === 0;
+var commandExists2 = (command) => spawnSync("which", [command], { stdio: "ignore", timeout: 750 }).status === 0;
 var detectCliInstallPackageManager = ({
   entrypoint = process.argv[1] ?? "",
   userAgent = process.env.npm_config_user_agent
@@ -46907,39 +46918,47 @@ var autoUpdateCliIfStale = async ({
     packageName,
     tag: tag4
   });
-  const result = spawnSync(command[0], command.slice(1), {
-    stdio: "inherit",
-    shell: false
-  });
-  if (result.status !== 0) {
-    return {
-      status: "failed",
-      check: check2,
-      packageManager,
-      command
-    };
-  }
   return {
-    status: "updated",
+    status: "available",
     check: check2,
     packageManager,
     command
   };
 };
 var parseSkillList = (value5) => {
-  const parsed = JSON.parse(value5);
-  if (!Array.isArray(parsed)) {
-    return [];
+  try {
+    const parsed = JSON.parse(value5);
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+    return parsed.flatMap((entry) => {
+      if (typeof entry === "object" && entry !== null && "name" in entry && "path" in entry && "scope" in entry && typeof entry.name === "string" && typeof entry.path === "string" && typeof entry.scope === "string") {
+        return [{
+          name: entry.name,
+          path: entry.path,
+          scope: entry.scope
+        }];
+      }
+      return [];
+    });
+  } catch {
+    return parseTextSkillList(value5);
   }
-  return parsed.flatMap((entry) => {
-    if (typeof entry === "object" && entry !== null && "name" in entry && "path" in entry && "scope" in entry && typeof entry.name === "string" && typeof entry.path === "string" && typeof entry.scope === "string") {
-      return [{
-        name: entry.name,
-        path: entry.path,
-        scope: entry.scope
-      }];
+};
+var stripAnsi = (value5) => value5.replace(/\x1B\[[0-?]*[ -/]*[@-~]/gu, "");
+var parseTextSkillList = (value5) => {
+  const scope5 = value5.includes("Global Skills") ? "global" : "project";
+  return stripAnsi(value5).split(`
+`).flatMap((line4) => {
+    const match18 = line4.match(/^([^\s]+)\s+(.+)$/u);
+    if (match18 === null || match18[1] === "Project" || match18[1] === "Global") {
+      return [];
     }
-    return [];
+    return [{
+      name: match18[1],
+      path: match18[2].trim(),
+      scope: scope5
+    }];
   });
 };
 var listSkills = (scope5) => {
@@ -46948,98 +46967,140 @@ var listSkills = (scope5) => {
     encoding: "utf8",
     shell: false,
     stdio: ["ignore", "pipe", "ignore"],
-    timeout: 5000
+    timeout: 1500
   });
   if (result.status !== 0) {
     return [];
   }
-  try {
-    return parseSkillList(result.stdout);
-  } catch {
-    return [];
-  }
+  return parseSkillList(result.stdout);
 };
-var updateDpCliSkill = (scope5) => {
-  const args2 = scope5 === "global" ? ["update", "dp-cli", "--global", "--yes"] : ["update", "dp-cli", "--project", "--yes"];
-  const result = spawnSync("skills", args2, {
-    stdio: "ignore",
-    shell: false,
-    timeout: 30000
-  });
-  return result.status === 0;
-};
-var installDpCliSkillGlobal = () => {
-  const result = spawnSync("skills", [
-    "add",
-    "wearedevpunks/skills",
-    "--global",
-    "--skill",
-    "dp-cli",
-    "--yes"
-  ], {
-    stdio: "ignore",
-    shell: false,
-    timeout: 30000
-  });
-  return result.status === 0;
-};
-var ensureDpCliSkillPresent = () => {
+var skillInstallCommand = () => [
+  "skills",
+  "add",
+  "wearedevpunks/skills",
+  "--global",
+  "--skill",
+  "dp-cli",
+  "--yes"
+];
+var checkDpCliSkillPresence = () => {
   if (!commandExists2("skills")) {
     return {
       skillsCliAvailable: false,
       detected: false,
       project: false,
-      global: false,
-      installedGlobal: false,
-      updatedProject: false,
-      updatedGlobal: false
+      global: false
     };
   }
   const projectBeforeInstall = listSkills("project").some((skill) => skill.name === "dp-cli");
   const globalBeforeInstall = listSkills("global").some((skill) => skill.name === "dp-cli");
-  const installedGlobal = projectBeforeInstall || globalBeforeInstall ? false : installDpCliSkillGlobal();
   const project3 = projectBeforeInstall;
-  const global = globalBeforeInstall || installedGlobal || listSkills("global").some((skill) => skill.name === "dp-cli");
+  const global = globalBeforeInstall;
   return {
     skillsCliAvailable: true,
     detected: project3 || global,
     project: project3,
-    global,
-    installedGlobal,
-    updatedProject: project3 ? updateDpCliSkill("project") : false,
-    updatedGlobal: global ? updateDpCliSkill("global") : false
+    global
   };
 };
 
 // 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",
-  version: cliVersion
+  version
 });
 var shouldCheckSelfUpdate = () => process.env.DP_NO_UPDATE_CHECK !== "1" && process.env.CI === undefined && process.argv.includes("--help") === false && process.argv.includes("-h") === false && process.argv.includes("--version") === false && process.argv.includes("-v") === false;
-var selfUpdateNotice = exports_Effect.promise(async () => {
-  if (!shouldCheckSelfUpdate()) {
-    return;
-  }
+var shouldCheckDpCliSkillUpdate = () => process.env.DP_NO_SKILL_UPDATE_CHECK !== "1" && process.env.CI === undefined && process.argv.includes("--help") === false && process.argv.includes("-h") === false && process.argv.includes("--version") === false && process.argv.includes("-v") === false;
+var runCliUpdateCheck = async () => {
   const result = await autoUpdateCliIfStale({
-    currentVersion: cliVersion,
-    packageName: cliPackageName,
+    currentVersion: version,
+    packageName: name,
     tag: process.env.DP_UPDATE_TAG ?? "latest"
   });
-  if (result.status === "manager-not-detected" || result.status === "failed") {
+  if (result.status === "available" || result.status === "manager-not-detected" || result.status === "failed") {
     console.error(renderSelfUpdateNotice({
       currentVersion: result.check.currentVersion,
       latestVersion: result.check.latestVersion,
-      packageName: result.check.packageName
+      packageName: result.check.packageName,
+      command: result.command
     }));
   }
-});
-var shouldCheckDpCliSkillUpdate = () => process.env.DP_NO_SKILL_UPDATE_CHECK !== "1" && process.env.CI === undefined && process.argv.includes("--help") === false && process.argv.includes("-h") === false && process.argv.includes("--version") === false && process.argv.includes("-v") === false;
-var dpCliSkillUpdate = exports_Effect.sync(() => {
-  if (!shouldCheckDpCliSkillUpdate()) {
+};
+var runDpCliSkillCheck = () => {
+  const skillResult = checkDpCliSkillPresence();
+  if (!skillResult.skillsCliAvailable) {
     return;
   }
-  ensureDpCliSkillPresent();
-});
-exports_Effect.zipRight(exports_Effect.zipRight(selfUpdateNotice, dpCliSkillUpdate), cli(process.argv)).pipe(exports_Effect.provide(exports_Layer.mergeAll(exports_BunContext.layer)), exports_BunRuntime.runMain);
+  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();
+  }
+};
+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 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 || hasFreshStartupCheck()) {
+    return;
+  }
+  const entrypoint = process.argv[1];
+  if (entrypoint === undefined || !existsSync7(entrypoint)) {
+    return;
+  }
+  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/dist/skills/agnostic/planning/implement-spec/SKILL.md

@@ -41,11 +41,12 @@ That means `implement-spec` itself owns all of the following in parallel mode:
 3. Choose the execution mode explicitly:
    - Read `references/sequential.md` for one-thread execution.
    - Read `references/parallel.md` for wave-based worker execution.
-4. Record the chosen mode under **Execution mode** in `IMPLEMENTATION-NOTES.md` before coding.
-5. Execute only the chosen mode. Do not mix modes inside one run.
-6. After each completed task or wave, update `PLAN.md`, `IMPLEMENTATION-NOTES.md`, and spec-linked tech debt before advancing.
-7. If backlog sync is in scope, keep epic/story bodies product-facing and use native metadata or comments instead of execution handoff rewrites.
-8. Finish with the shared acceptance audit and spec finalization contract.
+4. In Codex parallel mode, read `references/parallel-reasoning.md` before spawning workers and apply the Codex-only worker reasoning policy.
+5. Record the chosen mode under **Execution mode** in `IMPLEMENTATION-NOTES.md` before coding.
+6. Execute only the chosen mode. Do not mix modes inside one run.
+7. After each completed task or wave, update `PLAN.md`, `IMPLEMENTATION-NOTES.md`, and spec-linked tech debt before advancing.
+8. If backlog sync is in scope, keep epic/story bodies product-facing and use native metadata or comments instead of execution handoff rewrites.
+9. Finish with the shared acceptance audit and spec finalization contract.
 
 ## Mode selection
 
@@ -70,3 +71,4 @@ If the user already chose a mode, honor it. If not, make the smallest safe choic
 - Parallel execution specifics: see [references/parallel.md](references/parallel.md)
 - Parallel plan parsing and wave construction: see [references/parallel-orchestration.md](references/parallel-orchestration.md)
 - Parallel worker brief contract: see [references/parallel-worker-brief.md](references/parallel-worker-brief.md)
+- Codex parallel worker reasoning policy: see [references/parallel-reasoning.md](references/parallel-reasoning.md)

package/dist/skills/agnostic/planning/implement-spec/references/parallel-orchestration.md

@@ -56,6 +56,7 @@ Launch all unblocked tasks in parallel.
 For each unblocked task:
 
 - choose the worker template from `.agents/subagents/manifest.mjs`
+- in Codex, apply the worker `reasoning_effort` policy from [parallel-reasoning.md](parallel-reasoning.md)
 - use the worker-brief contract from [parallel-worker-brief.md](parallel-worker-brief.md)
 - keep the task scope narrow
 - ensure the worker owns only the assigned task and its required validation

package/dist/skills/agnostic/planning/implement-spec/references/parallel-reasoning.md

@@ -0,0 +1,19 @@
+# Codex Parallel Reasoning
+
+Use this reference only when `implement-spec` runs in Codex parallel mode and calls Codex `spawn_agent`.
+
+Set worker `reasoning_effort` lower than the parent orchestrator:
+
+| Orchestrator reasoning | Worker reasoning |
+|------------------------|------------------|
+| `xhigh`                | `high`           |
+| `high`                 | `medium`         |
+| `medium`               | `low`            |
+| `low`                  | `low`            |
+
+Rules:
+
+- This policy is Codex-only. Do not apply it to other models or hosts.
+- Pass the mapped value as `reasoning_effort` in each Codex `spawn_agent` call.
+- Keep orchestration, retries, dependency decisions, and acceptance audit in the parent.
+- If a worker task needs equal or higher reasoning, keep that task in the parent instead of spawning it.

package/dist/skills/agnostic/planning/implement-spec/references/parallel-worker-brief.md

@@ -34,6 +34,8 @@ Each worker brief should require:
 9. running the exact task validation evidence before returning, plus extra plan validation when feasible
 10. updating the plan entry with status, log, touched files, and gotchas before handoff closes
 
+When spawning Codex workers, apply [parallel-reasoning.md](parallel-reasoning.md): `xhigh -> high`, `high -> medium`, `medium -> low`, `low -> low`.
+
 ## Worker output contract
 
 Require the worker to return:
@@ -63,3 +65,4 @@ The parent `implement-spec` run owns:
 - review of worker outputs
 - retry and escalation decisions
 - deciding when the wave is complete
+- the final acceptance audit

package/dist/skills/agnostic/planning/implement-spec/references/parallel.md

@@ -31,16 +31,18 @@ Do not treat worker spawning as the whole job. The orchestration loop is part of
 1. Load the shared lifecycle from `lifecycle.md`.
 2. Record `parallel` under **Execution mode** in `IMPLEMENTATION-NOTES.md`.
 3. Read `.agents/subagents/manifest.mjs` before the first spawn and choose explicit worker templates per task.
-4. Read [parallel-orchestration.md](parallel-orchestration.md) and parse `PLAN.md` into a task graph.
-5. Build the current wave from the unblocked tasks only.
-6. Read [parallel-worker-brief.md](parallel-worker-brief.md) and use that contract when spawning workers.
-7. Validate each wave before moving on. Fix failures before the next wave.
-8. Update the plan, notes, and tech debt after every wave.
+4. In Codex, read [parallel-reasoning.md](parallel-reasoning.md) and set each worker `reasoning_effort` lower than the parent orchestrator.
+5. Read [parallel-orchestration.md](parallel-orchestration.md) and parse `PLAN.md` into a task graph.
+6. Build the current wave from the unblocked tasks only.
+7. Read [parallel-worker-brief.md](parallel-worker-brief.md) and use that contract when spawning workers.
+8. Validate each wave before moving on. Fix failures before the next wave.
+9. Update the plan, notes, and tech debt after every wave.
 
 ## Required evidence
 
 - plan-derived wave selection
 - explicit worker briefs per task
+- explicit Codex worker `reasoning_effort` when running in Codex
 - post-wave review of worker outputs
 - acceptance-criteria coverage plus RED -> GREEN evidence, or explicit non-testable verification
 - task completion only after validation and plan/log updates

package/docs/README.md

@@ -11,10 +11,9 @@ 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 for `@punks/cli` and prints a self-update notice when the installed CLI is behind. Set `DP_NO_UPDATE_CHECK=1` to skip the check or `DP_UPDATE_TAG=next` to compare against another dist-tag.
-- CLI startup also checks for the `dp-cli` skill through the `skills` CLI, installing it globally when absent and updating it when present. Set `DP_NO_SKILL_UPDATE_CHECK=1` to skip this best-effort pass.
+- 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.

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 PR test gates and Oxfmt/Oxlint execution do 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 performs best-effort startup checks on normal command startup. It checks the npm package version for `@punks/cli`, and it checks for the `dp-cli` skill through the global `skills` CLI, installing it when absent and updating it when present. These 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
-- prints `npm install -g @punks/cli@latest` 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.4",
+  "version": "1.0.6",
   "description": "Devpunks AI scaffolding CLI",
   "type": "module",
   "bin": {