dw-kit 1.2.0 → 1.3.0

package/src/lib/copy.mjs

@@ -1,110 +1,118 @@
-import {
-  existsSync, mkdirSync, copyFileSync, readdirSync, readFileSync,
-} from 'node:fs';
-import { join, dirname } from 'node:path';
-
-export function ensureDir(dir) {
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-}
-
-export function copyFile(src, dst, { dryRun = false } = {}) {
-  if (dryRun) return { action: 'copy', src, dst, applied: false };
-  ensureDir(dirname(dst));
-  copyFileSync(src, dst);
-  return { action: 'copy', src, dst, applied: true };
-}
-
-export function copyDir(srcDir, dstDir, { dryRun = false, overwrite = false } = {}) {
-  const results = [];
-  if (!existsSync(srcDir)) return results;
-
-  const entries = readdirSync(srcDir, { withFileTypes: true });
-  for (const entry of entries) {
-    const srcPath = join(srcDir, entry.name);
-    const dstPath = join(dstDir, entry.name);
-
-    if (entry.isDirectory()) {
-      results.push(...copyDir(srcPath, dstPath, { dryRun, overwrite }));
-    } else if (entry.isFile()) {
-      if (!overwrite && existsSync(dstPath)) {
-        results.push({ action: 'skip', src: srcPath, dst: dstPath, reason: 'exists' });
-        continue;
-      }
-      results.push(copyFile(srcPath, dstPath, { dryRun }));
-    }
-  }
-  return results;
-}
-
-/**
- * Copy files from srcDir to dstDir, respecting an overrides directory.
- * Files present in overridesDir take precedence over srcDir.
- */
-export function copyWithOverrides(srcDir, dstDir, overridesDir, { dryRun = false } = {}) {
-  const results = [];
-  if (!existsSync(srcDir)) return results;
-
-  const entries = readdirSync(srcDir, { withFileTypes: true });
-  for (const entry of entries) {
-    const srcPath = join(srcDir, entry.name);
-    const dstPath = join(dstDir, entry.name);
-    const overridePath = overridesDir ? join(overridesDir, entry.name) : null;
-
-    if (entry.isDirectory()) {
-      const subOverride = overridePath && existsSync(overridePath) ? overridePath : null;
-      results.push(...copyWithOverrides(srcPath, dstPath, subOverride, { dryRun }));
-    } else if (entry.isFile()) {
-      if (overridePath && existsSync(overridePath)) {
-        results.push({
-          action: 'override',
-          src: overridePath,
-          dst: dstPath,
-          ...(dryRun ? { applied: false } : (() => { ensureDir(dirname(dstPath)); copyFileSync(overridePath, dstPath); return { applied: true }; })()),
-        });
-      } else {
-        results.push(copyFile(srcPath, dstPath, { dryRun }));
-      }
-    }
-  }
-  return results;
-}
-
-/**
- * Compute file differences between two directories.
- * Returns { added, modified, unchanged } arrays of relative paths.
- */
-export function diffDirs(sourceDir, targetDir) {
-  const added = [];
-  const modified = [];
-  const unchanged = [];
-
-  if (!existsSync(sourceDir)) return { added, modified, unchanged };
-
-  function walk(dir, base) {
-    const entries = readdirSync(dir, { withFileTypes: true });
-    for (const entry of entries) {
-      const srcPath = join(dir, entry.name);
-      const relPath = base ? join(base, entry.name) : entry.name;
-
-      if (entry.isDirectory()) {
-        walk(srcPath, relPath);
-      } else if (entry.isFile()) {
-        const targetPath = join(targetDir, relPath);
-        if (!existsSync(targetPath)) {
-          added.push(relPath);
-        } else {
-          const srcContent = readFileSync(srcPath);
-          const tgtContent = readFileSync(targetPath);
-          if (srcContent.equals(tgtContent)) {
-            unchanged.push(relPath);
-          } else {
-            modified.push(relPath);
-          }
-        }
-      }
-    }
-  }
-
-  walk(sourceDir, '');
-  return { added, modified, unchanged };
-}
+import {
+  existsSync, mkdirSync, copyFileSync, readdirSync, readFileSync, writeFileSync,
+} from 'node:fs';
+import { join, dirname } from 'node:path';
+
+export function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+export function copyFile(src, dst, { dryRun = false } = {}) {
+  if (dryRun) return { action: 'copy', src, dst, applied: false };
+  ensureDir(dirname(dst));
+  if (src.endsWith('.sh')) {
+    // Always write shell scripts with LF endings.
+    // Prevents CRLF contamination when git later checks out these files on Windows
+    // (core.autocrlf=true overrides .gitattributes in the *user's* repo, which dw-kit cannot control).
+    const content = readFileSync(src, 'utf-8').replace(/\r\n/g, '\n');
+    writeFileSync(dst, content, 'utf-8');
+  } else {
+    copyFileSync(src, dst);
+  }
+  return { action: 'copy', src, dst, applied: true };
+}
+
+export function copyDir(srcDir, dstDir, { dryRun = false, overwrite = false } = {}) {
+  const results = [];
+  if (!existsSync(srcDir)) return results;
+
+  const entries = readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = join(srcDir, entry.name);
+    const dstPath = join(dstDir, entry.name);
+
+    if (entry.isDirectory()) {
+      results.push(...copyDir(srcPath, dstPath, { dryRun, overwrite }));
+    } else if (entry.isFile()) {
+      if (!overwrite && existsSync(dstPath)) {
+        results.push({ action: 'skip', src: srcPath, dst: dstPath, reason: 'exists' });
+        continue;
+      }
+      results.push(copyFile(srcPath, dstPath, { dryRun }));
+    }
+  }
+  return results;
+}
+
+/**
+ * Copy files from srcDir to dstDir, respecting an overrides directory.
+ * Files present in overridesDir take precedence over srcDir.
+ */
+export function copyWithOverrides(srcDir, dstDir, overridesDir, { dryRun = false } = {}) {
+  const results = [];
+  if (!existsSync(srcDir)) return results;
+
+  const entries = readdirSync(srcDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = join(srcDir, entry.name);
+    const dstPath = join(dstDir, entry.name);
+    const overridePath = overridesDir ? join(overridesDir, entry.name) : null;
+
+    if (entry.isDirectory()) {
+      const subOverride = overridePath && existsSync(overridePath) ? overridePath : null;
+      results.push(...copyWithOverrides(srcPath, dstPath, subOverride, { dryRun }));
+    } else if (entry.isFile()) {
+      if (overridePath && existsSync(overridePath)) {
+        results.push({
+          action: 'override',
+          src: overridePath,
+          dst: dstPath,
+          ...(dryRun ? { applied: false } : (() => { ensureDir(dirname(dstPath)); copyFileSync(overridePath, dstPath); return { applied: true }; })()),
+        });
+      } else {
+        results.push(copyFile(srcPath, dstPath, { dryRun }));
+      }
+    }
+  }
+  return results;
+}
+
+/**
+ * Compute file differences between two directories.
+ * Returns { added, modified, unchanged } arrays of relative paths.
+ */
+export function diffDirs(sourceDir, targetDir) {
+  const added = [];
+  const modified = [];
+  const unchanged = [];
+
+  if (!existsSync(sourceDir)) return { added, modified, unchanged };
+
+  function walk(dir, base) {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const srcPath = join(dir, entry.name);
+      const relPath = base ? join(base, entry.name) : entry.name;
+
+      if (entry.isDirectory()) {
+        walk(srcPath, relPath);
+      } else if (entry.isFile()) {
+        const targetPath = join(targetDir, relPath);
+        if (!existsSync(targetPath)) {
+          added.push(relPath);
+        } else {
+          const srcContent = readFileSync(srcPath);
+          const tgtContent = readFileSync(targetPath);
+          if (srcContent.equals(tgtContent)) {
+            unchanged.push(relPath);
+          } else {
+            modified.push(relPath);
+          }
+        }
+      }
+    }
+  }
+
+  walk(sourceDir, '');
+  return { added, modified, unchanged };
+}

package/src/lib/cut-analysis.mjs

@@ -0,0 +1,161 @@
+// Cut Criteria Matrix — implements ADR-0001 v1.4 decision gate.
+// Consumes telemetry events, emits cut candidates with evidence.
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+// Never-cut: skills that are the workflow's load-bearing verbs.
+export const CRITICAL_SKILLS = new Set([
+  'dw:flow', 'dw:task-init', 'dw:commit', 'dw:handoff',
+  'dw:execute', 'dw:plan', 'dw:research', 'dw:thinking',
+  'dw:review', 'dw:debug', 'dw:decision',
+]);
+
+// Per-project skills — evaluated separately (low cadence is expected).
+export const PER_PROJECT_SKILLS = new Set([
+  'dw:onboard', 'dw:retroactive', 'dw:config-init', 'dw:upgrade', 'dw:rollback',
+]);
+
+// Cut thresholds (ADR-0001 Cut Criteria Matrix)
+export const THRESHOLDS = {
+  skill: {
+    minUsesPerWeekPerDev: 5,
+    minDevs: 5,
+    minCoverageDays: 21,
+  },
+  hook: {
+    maxAvgLatencyMs: 500,
+    maxFiresPerSession: 10,
+  },
+};
+
+function coverageDays(events) {
+  if (events.length === 0) return 0;
+  const first = new Date(events[0].ts).getTime();
+  const last = new Date(events[events.length - 1].ts).getTime();
+  return Math.max(1, Math.round((last - first) / MS_PER_DAY));
+}
+
+function uniqueSessions(events) {
+  return new Set(events.map((e) => e.session).filter(Boolean)).size;
+}
+
+// Group events by (event type, name)
+function groupByNameAndType(events) {
+  const groups = { skill: {}, hook: {} };
+  for (const e of events) {
+    if (e.event !== 'skill' && e.event !== 'hook') continue;
+    const bucket = groups[e.event];
+    if (!bucket[e.name]) bucket[e.name] = [];
+    bucket[e.name].push(e);
+  }
+  return groups;
+}
+
+function skillStats(events, totalSessions, totalDays) {
+  const count = events.length;
+  const weeks = Math.max(1, totalDays / 7);
+  const devs = Math.max(1, totalSessions); // session-hash as dev proxy (undercounts real devs)
+  const usesPerWeekPerDev = count / weeks / devs;
+  return { count, usesPerWeekPerDev, weeks, devs };
+}
+
+function hookStats(events, totalSessions) {
+  const count = events.length;
+  const sessions = Math.max(1, totalSessions);
+  const firesPerSession = count / sessions;
+  const latencies = events.map((e) => e.latency_ms).filter((n) => typeof n === 'number');
+  const avgLatency =
+    latencies.length > 0 ? latencies.reduce((a, b) => a + b, 0) / latencies.length : null;
+  return { count, firesPerSession, avgLatency };
+}
+
+function evaluateSkill(name, events, totalSessions, totalDays) {
+  const s = skillStats(events, totalSessions, totalDays);
+  const reasons = [];
+  let critical = false;
+  let perProject = false;
+
+  if (CRITICAL_SKILLS.has(name)) {
+    critical = true;
+    reasons.push('critical path — protected');
+  }
+  if (PER_PROJECT_SKILLS.has(name)) {
+    perProject = true;
+    reasons.push('per-project cadence — evaluated separately');
+  }
+
+  const usesBelow = s.usesPerWeekPerDev < THRESHOLDS.skill.minUsesPerWeekPerDev;
+  const devsOk = totalSessions >= THRESHOLDS.skill.minDevs;
+  const coverageOk = totalDays >= THRESHOLDS.skill.minCoverageDays;
+
+  let qualify = false;
+  if (!critical && !perProject) {
+    if (usesBelow && devsOk && coverageOk) {
+      qualify = true;
+      reasons.push(
+        `uses/week/dev=${s.usesPerWeekPerDev.toFixed(2)} < ${THRESHOLDS.skill.minUsesPerWeekPerDev}`
+      );
+    } else {
+      if (!usesBelow) reasons.push(`uses/week/dev=${s.usesPerWeekPerDev.toFixed(2)} (above threshold)`);
+      if (!devsOk) reasons.push(`devs=${totalSessions} < ${THRESHOLDS.skill.minDevs}`);
+      if (!coverageOk) reasons.push(`coverage=${totalDays}d < ${THRESHOLDS.skill.minCoverageDays}d`);
+    }
+  }
+
+  return { name, type: 'skill', qualify, stats: s, reasons, critical, perProject };
+}
+
+function evaluateHook(name, events, totalSessions) {
+  const s = hookStats(events, totalSessions);
+  const reasons = [];
+  let qualify = false;
+
+  const latencyExceed =
+    s.avgLatency !== null && s.avgLatency > THRESHOLDS.hook.maxAvgLatencyMs;
+  const firesExceed = s.firesPerSession > THRESHOLDS.hook.maxFiresPerSession;
+
+  if (latencyExceed) {
+    qualify = true;
+    reasons.push(`avg_latency=${s.avgLatency.toFixed(0)}ms > ${THRESHOLDS.hook.maxAvgLatencyMs}ms`);
+  }
+  if (firesExceed) {
+    qualify = true;
+    reasons.push(
+      `fires/session=${s.firesPerSession.toFixed(1)} > ${THRESHOLDS.hook.maxFiresPerSession}`
+    );
+  }
+  if (!latencyExceed && !firesExceed) {
+    reasons.push(
+      `fires/session=${s.firesPerSession.toFixed(1)}, avg_latency=${s.avgLatency !== null ? s.avgLatency.toFixed(0) + 'ms' : 'n/a'} (within limits)`
+    );
+  }
+
+  return { name, type: 'hook', qualify, stats: s, reasons };
+}
+
+export function analyze(events) {
+  const totalSessions = uniqueSessions(events);
+  const totalDays = coverageDays(events);
+  const coverageOk = totalDays >= THRESHOLDS.skill.minCoverageDays;
+  const devsOk = totalSessions >= THRESHOLDS.skill.minDevs;
+
+  const groups = groupByNameAndType(events);
+
+  const skillResults = Object.entries(groups.skill)
+    .map(([name, evts]) => evaluateSkill(name, evts, totalSessions, totalDays))
+    .sort((a, b) => a.stats.usesPerWeekPerDev - b.stats.usesPerWeekPerDev);
+
+  const hookResults = Object.entries(groups.hook)
+    .map(([name, evts]) => evaluateHook(name, evts, totalSessions))
+    .sort((a, b) => b.stats.firesPerSession - a.stats.firesPerSession);
+
+  return {
+    coverage: { days: totalDays, sessions: totalSessions, coverageOk, devsOk },
+    skills: skillResults,
+    hooks: hookResults,
+    candidates: {
+      skills: skillResults.filter((r) => r.qualify),
+      hooks: hookResults.filter((r) => r.qualify),
+    },
+  };
+}

package/src/lib/telemetry.mjs

@@ -0,0 +1,80 @@
+import { appendFileSync, existsSync, readFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+
+const METRICS_DIR = '.dw/metrics';
+const EVENTS_FILE = 'events.jsonl';
+
+function isDisabled() {
+  return process.env.DW_NO_TELEMETRY === '1' || process.env.DW_NO_TELEMETRY === 'true';
+}
+
+function sessionHash() {
+  const pid = process.pid;
+  const start = process.env.DW_SESSION_START || Date.now();
+  return createHash('sha256').update(`${pid}:${start}`).digest('hex').slice(0, 8);
+}
+
+function ensureMetricsDir(rootDir) {
+  const dir = join(rootDir, METRICS_DIR);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return join(dir, EVENTS_FILE);
+}
+
+export function logEvent(event, rootDir = process.cwd()) {
+  if (isDisabled()) return false;
+
+  try {
+    const enriched = {
+      ts: new Date().toISOString(),
+      session: sessionHash(),
+      ...event,
+    };
+    const target = ensureMetricsDir(rootDir);
+    appendFileSync(target, JSON.stringify(enriched) + '\n', 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readEvents(rootDir = process.cwd(), { since, filterName, eventType } = {}) {
+  const target = join(rootDir, METRICS_DIR, EVENTS_FILE);
+  if (!existsSync(target)) return [];
+
+  const lines = readFileSync(target, 'utf8').split('\n').filter(Boolean);
+  const events = [];
+  for (const line of lines) {
+    try {
+      const evt = JSON.parse(line);
+      if (since && evt.ts < since) continue;
+      if (filterName && evt.name !== filterName) continue;
+      if (eventType && evt.event !== eventType) continue;
+      events.push(evt);
+    } catch {
+      // skip malformed
+    }
+  }
+  return events;
+}
+
+export function summarize(events) {
+  const bySkill = {};
+  const byHook = {};
+  const byTask = {};
+
+  for (const e of events) {
+    if (e.event === 'skill') bySkill[e.name] = (bySkill[e.name] || 0) + 1;
+    else if (e.event === 'hook') byHook[e.name] = (byHook[e.name] || 0) + 1;
+    else if (e.event === 'task') byTask[e.action || 'unknown'] = (byTask[e.action || 'unknown'] || 0) + 1;
+  }
+
+  return {
+    totalEvents: events.length,
+    bySkill,
+    byHook,
+    byTask,
+    dateRange:
+      events.length > 0 ? { from: events[0].ts, to: events[events.length - 1].ts } : null,
+  };
+}

package/.claude/rules/dw-core.md

@@ -1,100 +0,0 @@
-<!-- dw-kit | core: 1.2 -->
-# dw Workflow
-
-Config: `.dw/config/dw.config.yml`
-Full methodology: `.dw/core/WORKFLOW.md` · `.dw/core/THINKING.md` · `.dw/core/QUALITY.md` · `.dw/core/ROLES.md`
-
----
-
-## Override
-
-If the prompt contains `--no-dw`: ignore all dw instructions, work as plain Claude Code. Applies only to that request.
-
----
-
-## Depth Routing
-
-Read `workflow.default_depth` from config. Assess per task based on facts (file count, API changes, git blame) — not assumptions:
-
-| Scope | Depth | Approach |
-|-------|-------|----------|
-| ≤2 files, hotfix, familiar module | quick | Understand → Execute → Close |
-| 3–5 files, new module | standard | Full 6-phase |
-| 6+ files, API/DB/security changes | thorough | Full + arch-review + test-plan |
-
-When unsure → default to `standard`.
-
----
-
-## Session Start
-
-1. Read `.dw/config/dw.config.yml` — depth, roles, quality commands
-2. Check `.dw/tasks/` for active tasks; if one is in progress, resume from its `[task]-progress.md`
-
-> `session-init` hook auto-injects active task context — no manual action needed.
-
----
-
-## Task Docs
-
-For tasks spanning 3+ files, research → plan → approve → execute gives better outcomes.
-
-```
-.dw/tasks/[task-name]/
-├── [name]-context.md    # Research findings
-├── [name]-plan.md       # Implementation plan
-└── [name]-progress.md   # Progress + handoff notes
-```
-
----
-
-## Commit Format
-
-```
-<type>(<scope>): <description ≤72 chars>
-```
-
-Types: `feat` `fix` `refactor` `test` `docs` `chore` `style` `perf`
-
----
-
-## Hooks (v1.2)
-
-Auto-run — no user action needed:
-
-| Hook | Trigger | Effect |
-|------|---------|--------|
-| `session-init` | Session start | Inject active task context |
-| `scout-block` | Read/Glob | Block node_modules/, dist/, .git/ etc. |
-| `privacy-block` | Read | Block .env*, *.pem, credentials* |
-| `pre-commit-gate` | Bash (git commit) | Quality check + sensitive data scan |
-| `safety-guard` | Bash | Block destructive commands |
-| `post-write` | Write/Edit | Lint reminder |
-| `stop-check` | Stop | Warn on uncommitted changes + in-progress tasks |
-
----
-
-## Agent Reports (v1.2)
-
-For multi-phase tasks (standard/thorough), create reports for audit trail:
-
-```
-.dw/tasks/[task-name]/reports/[YYMMDD-HHMM]-from-[role]-to-[role]-[desc].md
-```
-
-Status: `DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT`
-Template: `.claude/templates/agent-report.md` · Guide: `.dw/core/AGENTS.md`
-
----
-
-## Config Local Override (v1.2)
-
-`.dw/config/dw.config.local.yml` (gitignored) for machine-specific settings:
-
-```yaml
-claude:
-  models:
-    plan: "claude-opus-4-6"
-quality:
-  test_command: "npm test"
-```

package/.claude/rules/dw-skills.md

@@ -1,53 +0,0 @@
-<!-- dw-kit | core: 1.2 -->
-# dw Skills
-
-Invoke via Claude Code slash commands. Availability governed by config flags and `workflow.default_depth`.
-
-## Core Workflow
-
-| Skill | Description | Depth |
-|-------|-------------|-------|
-| `/dw-flow [task]` | Full workflow shortcut | all |
-| `/dw-task-init [name]` | Init task docs | all |
-| `/dw-research [name]` | Survey codebase | all |
-| `/dw-plan [name]` | Design plan (waits for approval) | standard+ |
-| `/dw-execute [name]` | Implement per plan (TDD) | all |
-| `/dw-commit [msg]` | Smart commit + quality gates | all |
-| `/dw-handoff` | Session handoff | all |
-
-## Dev
-
-| Skill | Description |
-|-------|-------------|
-| `/dw-debug [issue]` | Investigate → diagnose → fix |
-| `/dw-review` | Code review with checklist |
-| `/dw-thinking [question]` | Apply thinking framework |
-| `/dw-prompt [desc]` | Build structured prompt |
-| `/dw-docs-update` | Update living docs |
-
-## Role-Specific
-
-| Skill | Role | Description |
-|-------|------|-------------|
-| `/dw-requirements` | BA | Requirements + user stories |
-| `/dw-test-plan` | QC | Test plan + regression |
-| `/dw-arch-review` | TechLead | Architecture review |
-| `/dw-dashboard` | PM | Metrics report |
-| `/dw-sprint-review` | All | Retrospective |
-| `/dw-estimate [name]` | if enabled | Effort estimation |
-| `/dw-log-work [name]` | if enabled | Log actual effort |
-
-## Setup & Maintenance
-
-| Skill | Description |
-|-------|-------------|
-| `/dw-onboard` | Onboard dw to existing project (breadth-first scan) |
-| `/dw-retroactive [name]` | Document existing feature (depth-first) |
-| `/dw-config-init` | Initialize new config |
-| `/dw-config-validate` | Validate config file |
-| `/dw-upgrade` | Upgrade toolkit |
-| `/dw-rollback [name]` | Rollback task docs |
-| `/dw-archive [name]` | Archive completed task |
-| `/dw-kit-report [desc]` | Submit feedback/bug to GitHub |
-
-> **Maintainer-only** (TechLead, dw-kit repo): `/dw-kit-evolve [issue#]` · `/dw-kit-audit [days]`