@punks/cli 1.0.2 → 1.0.4

package/dist/skills/agnostic/backend/logging-best-practices/rules/wide-events.md

@@ -0,0 +1,113 @@
+---
+title: Wide Events / Canonical Log Lines
+impact: CRITICAL
+tags: logging, wide-events, canonical-log-lines
+---
+
+## Wide Events / Canonical Log Lines
+
+**Impact: CRITICAL**
+
+Wide events (also called canonical log lines) are the foundation of effective logging. For each request, emit **a single context-rich event per service**. Instead of scattering 10-20 log lines throughout your request handler, consolidate everything into one comprehensive event emitted at the end of the request.
+
+### The Pattern
+
+Build the event throughout the request lifecycle, then emit once at completion in a `finally` block. This ensures the event is always emitted with complete context, even during failures.
+
+**Incorrect:**
+
+```typescript
+app.post('/articles', async (c) => {
+  console.log('Received POST /articles request');
+
+  const body = await c.req.json();
+  console.log('Request body parsed', { title: body.title });
+
+  const user = await getUser(c.get('userId'));
+  console.log('User fetched', { userId: user.id });
+
+  const article = await database.saveArticle({ ...body, ownerId: user.id });
+  console.log('Article saved', { articleId: article.id });
+
+  await cache.set(article.id, article);
+  console.log('Cache updated');
+
+  console.log('Request completed successfully');
+  return c.json({ article }, 201);
+});
+// 6 disconnected log lines with scattered context
+// Cannot query: "show me all article creates by free trial users"
+```
+
+**Correct:**
+
+```typescript
+app.post('/articles', async (c) => {
+  const startTime = Date.now();
+  const wideEvent: Record<string, unknown> = {
+    method: 'POST',
+    path: '/articles',
+    service: 'articles',
+    requestId: c.get('requestId'),
+  };
+
+  try {
+    const body = await c.req.json();
+    const user = await getUser(c.get('userId'));
+    wideEvent.user = {
+      id: user.id,
+      subscription: user.subscription,
+      trial: user.trial,
+    };
+
+    const article = await database.saveArticle({ ...body, ownerId: user.id });
+    wideEvent.article = {
+      id: article.id,
+      title: article.title,
+      published: article.published,
+    };
+
+    await cache.set(article.id, article);
+    wideEvent.cache = { operation: 'write', key: article.id };
+
+    wideEvent.status_code = 201;
+    wideEvent.outcome = 'success';
+    return c.json({ article }, 201);
+  } catch (error) {
+    wideEvent.status_code = 500;
+    wideEvent.outcome = 'error';
+    wideEvent.error = { message: error.message, type: error.name };
+    throw error;
+  } finally {
+    wideEvent.duration_ms = Date.now() - startTime;
+    wideEvent.timestamp = new Date().toISOString();
+    logger.info(JSON.stringify(wideEvent));
+  }
+});
+// Single event with all context - queryable by any field
+```
+
+### Connect Events with Request ID
+
+Every wide event must include a unique request ID that is propagated across all service hops. This is the only way to reconstruct the full journey of a request through a distributed system.
+
+```typescript
+// Service A - generate and propagate
+const requestId = c.get('requestId') || crypto.randomUUID();
+wideEvent.requestId = requestId;
+
+await fetch('http://downstream-service/endpoint', {
+  headers: { 'x-request-id': requestId },
+  body: JSON.stringify(data),
+});
+
+// Service B - extract and use
+const requestId = c.req.header('x-request-id');
+wideEvent.requestId = requestId;  // Same ID links events together
+```
+
+### Emit in Finally Block
+
+Always emit wide events in a `finally` block or equivalent. This ensures the event is emitted with complete context regardless of success or failure.
+
+Reference: [Stripe Blog - Canonical Log Lines](https://stripe.com/blog/canonical-log-lines)

package/dist/skills/agnostic/cli/dp-cli/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: dp-cli
-description: Operates the DevPunks `dp` CLI and follows its scaffold, stage, update, and post-command handoff artifacts through to completion. Use when a repo contains `.devpunks/` output, when the user mentions `dp scaffold`, `dp update`, DevPunks CLI setup, or asks what to do after running a `dp` command.
-metadata: {"devpunks":{"entrypoint":true}}
+description: Operates the Devpunks `dp` CLI and interactively follows scaffold, stage, update, and post-command handoff artifacts through to completion. Use when a repo contains `.devpunks/` output, when the user mentions `dp scaffold`, `dp update`, Devpunks CLI setup, or asks what to do after running a `dp` command.
+metadata: {"Devpunks":{"entrypoint":true}}
 ---
 
 # DP CLI
 
-The `dp` CLI scaffolds DevPunks agent assets and writes follow-up instructions for the next agent.
+The `dp` CLI scaffolds Devpunks agent assets and writes follow-up instructions for the next agent.
 
 ## Quick Start
 
 ```bash
 dp scaffold setup
-dp scaffold stage init
-dp scaffold stage backlog
+dp scaffold init
+dp scaffold backlog
 dp update --check
 dp update --write
 ```
@@ -26,6 +26,20 @@ After any command, read the command output and generated artifacts before acting
 
 Do not summarize the generated files and stop. Read the handoff, execute the specs, reconcile generated assets, and report only remaining unresolved items.
 
+## Interactive Rule
+
+Prompt the user frequently when post-scaffold choices affect project policy or shape.
+
+Ask before:
+
+- choosing which generated prompt scopes to collapse, split, or prioritize
+- replacing existing lint or format tooling with Oxlint/Oxfmt
+- deciding which core libraries to clone and inspect with `opensrc`
+- changing package scripts, task pipelines, CI, hooks, or docs
+- resolving conflicts between existing repo guidance and scaffold specs
+
+Do not ask for trivial file reads, validation commands, or direct execution of already-approved scaffold instructions.
+
 ## Command Workflows
 
 See [references/commands.md](references/commands.md) for command intent and when to use each command.
@@ -48,6 +62,10 @@ Read `.devpunks/AGENT-SYSTEM-PROMPT.md` first when present.
 
 Then author or reconcile the final repo files requested by the specs, including prompt files, harness mirrors, lint configuration, and subagent manifests.
 
+Before authoring prompts or plans, identify the detected core libraries whose source behavior matters. Ask the user which ones to prioritize if the choice is not obvious, then run `opensrc path <package>` or `opensrc path owner/repo` only for that focused set.
+
+When lint specs suggest Oxlint or hooks suggest Oxfmt, treat migration as a repo-policy change. Ask before replacing existing ESLint/Prettier/Biome scripts or CI, then update package scripts, task pipelines, editor/docs references, and hooks together.
+
 ## Update
 
 After `dp update`, inspect `.devpunks/scaffold-manifest.json` and the update summary.
@@ -63,3 +81,4 @@ After `dp update`, inspect `.devpunks/scaffold-manifest.json` and the update sum
 - required tools were checked when `.devpunks/required-tools.json` exists.
 - final prompt files and harness mirrors match the handoff contract.
 - subagent manifests were reconciled when specs exist.
+- user decisions were requested for policy-level choices instead of guessed silently.

package/dist/skills/agnostic/cli/dp-cli/references/commands.md

@@ -8,13 +8,13 @@ It detects package manifests, resolves packs, writes `.agents/`, harness files,
 
 It does not finish all repo-specific authoring. The next agent must use `.devpunks/AGENT-SYSTEM-PROMPT.md` and `.devpunks/specs/**` to generate final scoped guidance and reconcile assets.
 
-## `dp scaffold stage init`
+## `dp scaffold init`
 
 Use before boilerplate exists.
 
 It scaffolds requirements-stage assets and prints an operator prompt. Follow that prompt before moving to another stage.
 
-## `dp scaffold stage backlog`
+## `dp scaffold backlog`
 
 Use to inspect or enter the backlog stage.
 

package/dist/skills/agnostic/cli/dp-cli/references/post-command-flow.md

@@ -32,6 +32,8 @@ After `dp scaffold setup`:
 - Keep `.agents/skills/` as the main skill directory; only `.claude/skills` mirrors it.
 - Reconcile `.agents/subagents/manifest.mjs` with both `.agents/subagents/manifest.prompt.md` and `.devpunks/specs/subagents/manifest-spec.json`.
 - Use lint specs to produce or update the repo's real lint config when requested.
+- Ask before replacing existing lint/format tooling with Oxlint/Oxfmt. If approved, update scripts, CI/task pipelines, hooks, and docs together.
+- Ask which detected core libraries to inspect when source context is broad; then use `opensrc path <package>` or `opensrc path owner/repo` for only the chosen set.
 
 Do not stop after saying the files exist.
 

package/dist/skills/agnostic/requirements/write-backlog/REFERENCE.md

@@ -25,7 +25,7 @@ Downstream contract:
 
 - a raw requirements discussion
 - an existing messy backlog
-- `requirements-grill` artifacts from `/Users/stefan/Desktop/repos/wearedevpunks-multiplai/.agents/skills/requirements-grill`
+- `requirements-grill` artifacts from `/Users/stefan/Desktop/repos/weareDevpunks-multiplai/.agents/skills/requirements-grill`
 
 When grill artifacts exist, treat them as the highest-signal structured source for backlog derivation.
 

package/docs/README.md

@@ -12,13 +12,19 @@ Implementation notes:
 - 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.
 - 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/`
 - 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.
 - 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.
 - Next.js detection implies the React pack even when `react` / `react-dom` are not directly listed in scanned manifests.
 - Frontend surface detection scaffolds `frontend-domain-structure` with the frontend pack when React or Next.js is detected.
-- Backend surface detection scaffolds `backend-domain-structure` and `backend-recoverable-actions` when backend framework/data/auth packages are detected, or when workspace names/paths clearly identify API, backend, server, or service packages.
+- Backend surface detection scaffolds `backend-domain-structure`, `backend-recoverable-actions`, and `logging-best-practices` when backend framework/data/auth packages are detected, or when workspace names/paths clearly identify API, backend, server, or service packages. Workspace prompt specs apply backend packs only to backend-looking workspaces, not frontend workspaces that happen to share repo-level backend/data detections.
+- Drizzle detection selects the `drizzle` pack for data-layer prompt/lint metadata, but does not imply Effect skills or Effect opensrc references unless `effect` / `@effect/*` is also detected.
+- Scaffold no longer preselects concrete opensrc repositories. Post-scaffold agents must choose and clone the core detected libraries whose source behavior matters before authoring final prompts or plans.
+- The default subagent manifest includes a read-only `code-review` template that uses `simplify` and `improve-codebase-architecture`; root prompt guidance routes review requests to findings-first review before broad refactor planning.
 - Non-surface agnostic skill groups are mandatory scaffold packs (`debug`, `docs`, `planning`, `quality`, `research`, `requirements`, `subagents`); `frontend` and `backend` remain detection-driven.

package/docs/reference/dp-requirements.md

@@ -67,7 +67,7 @@ That wiki tree is not the same thing as `docs/`. It owns specs, raw inputs, and
 It should:
 
 - detect repo facts, not ask the agent to invent them
-- resolve those facts to predefined DevPunks packs
+- resolve those facts to predefined Devpunks packs
 - scaffold the shared AI setup
 - emit instructions/specs the next agent can use to generate repo-scoped prompts and subagent config
 
@@ -106,6 +106,8 @@ Initial technology mapping:
 - `turbo` -> `turborepo`
 - `effect`, `@effect/*` -> `effect`
 
+`drizzle` is data-layer detection only. It must not imply Effect skills or Effect source references unless the `effect` pack is selected independently.
+
 ## Pack Contract
 
 Pack resolution happens at pack level only during `punks scaffold setup`.
@@ -147,6 +149,11 @@ Framework/data packs may layer on top of that surface:
 - `tanstack-query`
   `tanstack-query`
 
+Backend-oriented agnostic skills should be grouped into a single detected backend surface pack:
+
+- `backend`
+  `backend-domain-structure`, `backend-recoverable-actions`, `logging-best-practices`
+
 ## Prompt Contract
 
 Pre-boilerplate commands use fixed stdout operator prompts.
@@ -188,6 +195,10 @@ Current examples:
 
 The scaffold output should also record the resolved tool requirements in a machine-readable manifest.
 
+`punks scaffold setup` should check base required tools before repo detection so missing `skills` or `portless` is surfaced immediately. Tools required only by selected packs can be checked after pack confirmation.
+
+Scaffold output should not preselect concrete opensrc repositories. The generated post-scaffold instructions should require the next agent to identify the core detected libraries whose source behavior matters, ask the user when that set is ambiguous, and run `opensrc path <package>` or `opensrc path owner/repo` for only that focused set.
+
 ## Lint Scaffold Contract
 
 The shipped starter/root lint baseline should exclude generated and non-source surfaces by default, including:
@@ -196,6 +207,10 @@ The shipped starter/root lint baseline should exclude generated and non-source s
 - all dot-directories
 - generated agent/harness folders unless a target repo explicitly opts them back into lint scope
 
+When scaffold guidance leads an agent to adopt Oxlint or Oxfmt, it must tell the agent to replace existing lint/format entrypoints deliberately: package scripts, task pipelines, CI, editor/docs references, and agent hooks should agree on the new tools.
+
+Until additional lint/format stacks are supported, repo-aware setup should emit Oxlint specs/starter config only when `oxlint` is declared in scanned package manifests and emit the Oxfmt/Oxlint format hook only when `oxfmt` is declared. Repos without those packages should get no lint/format scaffold surfaces.
+
 ## Dedicated CLI Repo Contract
 
 The standalone private `wearedevpunks/cli` repo remains the source of truth for:

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

@@ -72,6 +72,9 @@ Current scope:
 - treat React, Next.js, and TanStack Query as separate frontend capability layers; React is the plain framework pack triggered by `react` / `react-dom` or implied by `next`, and pulls in `async-react-patterns` to prevent outdated manual async state modeling
 - include the `frontend` agnostic surface pack only when React or Next.js is detected; it carries product UI, browser validation, and frontend domain-structure guidance
 - include the `backend` agnostic surface pack when backend framework/data/auth packages are detected (`elysia`, `@trpc/*`, `drizzle-orm`, `drizzle-kit`, `better-auth`) or when package names/manifest paths clearly mark an API/backend/server/service workspace
+- assign backend packs only to backend-looking workspace prompt specs; do not add backend skills to frontend-looking workspaces just because backend/data/auth packs exist elsewhere in the repo
+- include backend logging guidance through `logging-best-practices` anywhere the backend surface pack applies, so backend prompts cover wide events, request context, and production debugging signals alongside structure and recoverability
+- keep Drizzle as data-layer guidance only; do not scaffold Effect skills or Effect opensrc references from Drizzle unless `effect` / `@effect/*` is also detected
 - keep all non-surface agnostic skill packs mandatory (`debug`, `docs`, `planning`, `quality`, `research`, `requirements`, `subagents`)
 - detect monorepo signals from `pnpm-workspace.yaml`, `turbo.json`, root workspaces, and workspace package count
 - resolve predefined packs from those facts
@@ -89,9 +92,12 @@ Current scope:
 - write a paste-ready next-agent prompt file and try to copy it to the clipboard automatically
 - include `portless` in the required tools manifest so follow-up agents can standardize local dev URLs across worktrees and avoid raw port collisions
 - include `skills` in the required tools manifest so follow-up agents can install/update public skill entrypoints such as `dp-cli`
+- 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
 - 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
 
 If `-o, --output` points at a path that does not exist yet, `punks scaffold setup` creates it before writing the generated files.
 
@@ -107,10 +113,10 @@ After confirmation, `punks scaffold setup` writes:
 - `.devpunks/AGENT-HANDOFF.md`
 - `.devpunks/AGENT-SYSTEM-PROMPT.md`
 - `.devpunks/required-tools.json`
-- `.devpunks/specs/lint/assets.json`
-- `.devpunks/specs/lint/selection.json`
-- `.devpunks/specs/lint/README.md`
-- `.devpunks/specs/lint/oxlint-starter.json` when no root Oxlint config already exists
+- `.devpunks/specs/lint/assets.json` when `oxlint` is declared
+- `.devpunks/specs/lint/selection.json` when `oxlint` is declared
+- `.devpunks/specs/lint/README.md` when `oxlint` is declared
+- `.devpunks/specs/lint/oxlint-starter.json` when `oxlint` is declared and no root Oxlint config already exists
 - `.devpunks/specs/prompts/shared-agents.md`
 - `.devpunks/specs/prompts/root.md`
 - `.devpunks/specs/prompts/docs.md`
@@ -126,13 +132,17 @@ It does **not** write final root/docs/workspace `AGENTS.md` files yet. Those rem
 
 After scaffold completes, the CLI writes `.devpunks/AGENT-SYSTEM-PROMPT.md`, tries to copy that prompt to the clipboard, and ends with a short terminal section telling the operator to paste that generated prompt into the next agent.
 
-Scaffolded guidance treats `portless` as the local-development URL baseline. Generated prompt specs and handoff text tell follow-up agents to prefer stable `*.localhost` subdomains over raw `localhost:<port>` values in env examples, endpoint defaults, callback URLs, allowed origins, CORS, and app-to-app proxy targets. In linked git worktrees, portless prefixes hostnames with the branch name, so local URLs must be modeled as stable origins that may vary by worktree. When a local frontend proxy targets another portless app, configure the proxy to rewrite the host/origin so the request reaches the intended service instead of looping back to the caller.
+Scaffolded guidance treats `portless` as the local-development URL baseline. Root/handoff guidance tells follow-up agents to prefer stable `*.localhost` subdomains over raw `localhost:<port>` values in env examples, endpoint defaults, callback URLs, allowed origins, CORS, and app-to-app proxy targets. Scoped prompts should repeat portless guidance only when that workspace directly owns URL, origin, callback, CORS, or proxy configuration.
+
+Scaffolded guidance does not emit concrete opensrc repository refs. The post-scaffold agent must identify the detected core libraries whose source behavior matters for prompt, plan, lint, or implementation decisions, ask the user when the priority is ambiguous, then run `opensrc path <package>` or `opensrc path owner/repo` for that focused set.
+
+Root prompt guidance routes code review requests to findings-first review with precise file/line references. It tells review agents to use `simplify` for clarity, naming, duplication, derivable state, and unnecessary abstraction, and to use `improve-codebase-architecture` only when observed review friction justifies candidate refactors or follow-up RFCs.
 
 When the next agent authors those final prompt files, each root/docs/workspace `AGENTS.md` should be treated as the neutral source of truth and mirrored by a sibling `CLAUDE.md` symlink. `.agents/AGENTS.md` remains the shared global neutral source, and `.claude/CLAUDE.md` should mirror it.
 
 Keep `.agents/skills/` as the main skill directory. Only `.claude/skills` is generated as a compatibility symlink; Codex, Cursor, and OpenCode should read skills from `.agents/skills` instead of maintaining `.codex/skills`, `.cursor/skills`, or `.opencode/skills` mirrors.
 
-It also does **not** mutate the repo's final Oxlint config. Lint is scaffolded as selected pack-owned assets plus placement guidance so the follow-up agent can fit the final `.oxlintrc.json` shape to the real repo layout.
+It also does **not** mutate the repo's final Oxlint config. Lint is scaffolded as selected pack-owned assets plus placement guidance only when `oxlint` is already present in scanned package manifests, so the follow-up agent can fit the final `.oxlintrc.json` shape to the real repo layout. If the agent adopts Oxlint or Oxfmt, it must replace existing lint/format setup deliberately by updating package scripts, task pipelines, editor/docs references, CI, and agent hooks together instead of leaving stale ESLint/Prettier/Biome entrypoints behind.
 
 The scaffolded starter baseline excludes lock files and dot-directories by default so generated/vendor surfaces do not get linted as product code.
 
@@ -196,9 +206,18 @@ bun run baseline:publish
 
 `baseline:build` creates `dist/baseline/scaffold-baseline.json` and `dist/baseline/scaffold-baseline.tgz`. `baseline:publish` creates a GitHub release tag under `baseline/stable/*` and uploads both assets.
 
+Publish npm executable releases with `bun run release:publish` from a clean worktree after authenticating with npm:
+
+```bash
+npm login --registry=https://registry.npmjs.org/
+npm whoami
+```
+
+The npm account must have publish access to `@punks/cli`; otherwise npm may report a confusing scoped-package 404 during `npm publish`.
+
 ## CLI Self-Update Detection
 
-The CLI also performs a best-effort package self-update check on normal command startup. This is separate from `punks update`, which updates scaffold-managed repo assets.
+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.
 
 - checks `https://registry.npmjs.org/%40punks%2Fcli/latest`
 - compares that dist-tag version with the bundled CLI version

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@punks/cli",
-  "version": "1.0.2",
-  "description": "DevPunks AI scaffolding CLI",
+  "version": "1.0.4",
+  "description": "Devpunks AI scaffolding CLI",
   "type": "module",
   "bin": {
     "devpunks": "dist/index.js",