jhste-skills 0.1.1 → 0.1.3

package/README.ja.md

@@ -158,7 +158,6 @@ Normal install では、Matt Pocock の [`mattpocock/skills`](https://github.com
 
 | Skill | いつ使うか |
 |---|---|
-| [`diagnose`](skills/diagnose/SKILL.md)<br>reproduce、minimize、hypothesize、instrument、fix、regression-check を強制する診断ループ skill | hard bug や performance regression を体系的に診断するとき |
 | [`diagnosing-bugs`](skills/diagnosing-bugs/SKILL.md)<br>高速な pass/fail feedback loop を中心に root cause を絞り込む debugging skill | reproduce → minimise → hypothesise → instrument → fix ループが必要なとき |
 | [`grill-me`](skills/grill-me/SKILL.md)<br>計画や設計の穴がなくなるまで粘り強く質問する skill | agent に計画や設計を明確になるまで質問させたいとき |
 | [`grill-with-docs`](skills/grill-with-docs/SKILL.md)<br>質問しながら domain terms と decisions を文書化する design validation skill | 質問プロセスで project vocabulary や docs/ADR も更新したいとき |

package/README.ko.md

@@ -158,7 +158,6 @@ Normal install은 Matt Pocock의 [`mattpocock/skills`](https://github.com/mattpo
 
 | Skill | 언제 쓰나 |
 |---|---|
-| [`diagnose`](skills/diagnose/SKILL.md)<br>재현, 축소, 가설, 계측, 수정, 회귀 확인을 강제하는 진단 루프 스킬 | hard bug 또는 performance regression을 체계적으로 진단할 때 |
 | [`diagnosing-bugs`](skills/diagnosing-bugs/SKILL.md)<br>빠른 pass/fail feedback loop를 중심으로 원인을 좁혀가는 debugging 스킬 | reproduce → minimise → hypothesise → instrument → fix 루프가 필요할 때 |
 | [`grill-me`](skills/grill-me/SKILL.md)<br>계획이나 설계의 빈틈이 사라질 때까지 집요하게 질문하는 스킬 | agent가 계획이나 설계를 명확해질 때까지 질문하게 하고 싶을 때 |
 | [`grill-with-docs`](skills/grill-with-docs/SKILL.md)<br>질문 과정에서 도메인 용어와 의사결정을 문서화하는 설계 검증 스킬 | 질문 과정에서 project vocabulary와 docs/ADR까지 함께 정리하고 싶을 때 |

package/README.md

@@ -154,11 +154,10 @@ These are the jhste-authored guardrail skills. They are installed by default as
 
 ## Bundled workflow skills
 
-Normal install also includes 14 workflow skills vendored from Matt Pocock's [`mattpocock/skills`](https://github.com/mattpocock/skills). These are useful for debugging, planning, architecture, issue workflows, prototyping, and handoffs. Use `--skill-set core` if you do not want them installed.
+Normal install also includes 13 workflow skills vendored from Matt Pocock's [`mattpocock/skills`](https://github.com/mattpocock/skills). These are useful for debugging, planning, architecture, issue workflows, prototyping, and handoffs. Use `--skill-set core` if you do not want them installed.
 
 | Skill | Use it when |
 |---|---|
-| [`diagnose`](skills/diagnose/SKILL.md)<br>A diagnosis-loop skill that forces reproduce, minimize, hypothesize, instrument, fix, and regression-check steps | Diagnosing a hard bug or performance regression systematically |
 | [`diagnosing-bugs`](skills/diagnosing-bugs/SKILL.md)<br>A debugging skill that narrows root cause around a fast pass/fail feedback loop | You need a reproduce → minimise → hypothesise → instrument → fix loop |
 | [`grill-me`](skills/grill-me/SKILL.md)<br>A skill that asks persistent questions until a plan or design has no obvious gaps | You want the agent to question your plan or design until it becomes clear |
 | [`grill-with-docs`](skills/grill-with-docs/SKILL.md)<br>A design-challenge skill that documents domain terms and decisions while questioning the plan | You want project vocabulary and docs/ADRs updated during the questioning process |
@@ -175,7 +174,7 @@ Normal install also includes 14 workflow skills vendored from Matt Pocock's [`ma
 
 ## Attribution: Matt Pocock skills
 
-This repository vendors the 14 skills listed above from Matt Pocock's [`mattpocock/skills`](https://github.com/mattpocock/skills).
+This repository vendors the 13 skills listed above from Matt Pocock's [`mattpocock/skills`](https://github.com/mattpocock/skills).
 
 Those skills are vendored under the upstream MIT License. This repository preserves the required copyright/license notice and records the imported sources.
 
@@ -253,4 +252,4 @@ See [`docs/ACCEPTANCE_CHECK.md`](docs/ACCEPTANCE_CHECK.md) for release acceptanc
 
 Fast agents need guardrails. `jhste-skills` gives them a repo-respecting engineering workflow.
 
-Installed skill directories are tracked with `.jhste-skills-manifest.json`. `--force` refreshes manifest-managed skill copies; overwriting unmanaged differing skill directories still requires the separate `--allow-unmanaged-skill-overwrite` flag after review. `sync` and `update` can also adopt additional known jhste skills into an already managed skills directory so older mixed installs can be reconciled without a manual overwrite flag.
+Installed skill directories are tracked with `.jhste-skills-manifest.json`. `--force` refreshes manifest-managed skill copies; overwriting unmanaged differing skill directories still requires the separate `--allow-unmanaged-skill-overwrite` flag after review. `sync` and `update` can also adopt additional known jhste skills into an already managed skills directory so older mixed installs can be reconciled without a manual overwrite flag. Legacy vendored renames are also reconciled during `sync` and `update`, so older managed installs that still have `diagnose` are migrated to `diagnosing-bugs` without leaving duplicate skill directories.

package/README.zh.md

@@ -158,7 +158,6 @@ Normal install 还会安装 14 个从 Matt Pocock 的 [`mattpocock/skills`](http
 
 | Skill | 何时使用 |
 |---|---|
-| [`diagnose`](skills/diagnose/SKILL.md)<br>强制执行 reproduce、minimize、hypothesize、instrument、fix、regression-check 的诊断循环 skill | 系统性诊断 hard bug 或 performance regression 时 |
 | [`diagnosing-bugs`](skills/diagnosing-bugs/SKILL.md)<br>围绕快速 pass/fail feedback loop 缩小 root cause 的 debugging skill | 需要 reproduce → minimise → hypothesise → instrument → fix 循环时 |
 | [`grill-me`](skills/grill-me/SKILL.md)<br>持续提问，直到计划或设计没有明显空洞的 skill | 希望 agent 持续追问计划或设计直到清晰时 |
 | [`grill-with-docs`](skills/grill-with-docs/SKILL.md)<br>在提问过程中记录 domain terms 和 decisions 的设计验证 skill | 希望在提问过程中更新 project vocabulary 和 docs/ADR 时 |

package/cli/deep-scan/analyze.mjs

@@ -70,63 +70,6 @@ function addSharedScannerCandidates(file, text, findings, thresholds) {
   }
 }
 
-function hasUseClientDirective(text) {
-  return /^\s*(?:"use client"|'use client')\s*;?/u.test(text);
-}
-
-function isScriptPipeline(file) {
-  return /(^|\/)scripts\/(data|ops|import|imports|backfill|repair|migrate|migration)\//.test(file.rel)
-    && /\.(ts|tsx|js|jsx|mjs|cjs|py)$/.test(file.rel);
-}
-
-function matchedResponsibilityHints(text, hintGroups) {
-  return hintGroups
-    .filter((group) => group.patterns.some((pattern) => pattern.test(text)))
-    .map((group) => group.label);
-}
-
-function scanMixedResponsibilities(file, text, findings) {
-  if (hasUseClientDirective(text)) {
-    const hints = matchedResponsibilityHints(text, [
-      { label: 'browser storage', patterns: [/\b(localStorage|sessionStorage)\b/] },
-      { label: 'network/API', patterns: [/\bfetch\s*\(/, /\baxios\./, /\buse(Query|Mutation)\s*\(/] },
-      { label: 'toast/notification', patterns: [/\btoast\b/, /\bnotify\b/] },
-      { label: 'modal/dialog state', patterns: [/\b(Dialog|Modal|Sheet)\b/, /\bopen[A-Z]\w*\b/, /\bis[A-Z]\w*Open\b/] },
-      { label: 'route navigation', patterns: [/\buseRouter\s*\(/, /\brouter\.(push|replace|refresh)\b/] },
-      { label: 'heavy mapping', patterns: [/\.(map|filter|reduce)\s*\(/] },
-    ]);
-    if (hints.length >= 3) {
-      candidate(findings.responsibilityBudget, 'mixed client responsibility candidate', file, 1, `client module mixes ${hints.slice(0, 4).join(', ')}; review hook/adapter/presentation split`, 'warning');
-    }
-  }
-
-  const routeLike = /(^|\/)(api|routes?|controllers?|pages\/api)\//i.test(file.rel) || /route\.(ts|js)$/.test(file.rel);
-  if (routeLike) {
-    const hints = matchedResponsibilityHints(text, [
-      { label: 'auth/session', patterns: [/\b(auth|session|permission|currentUser|getUser)\b/i] },
-      { label: 'validation', patterns: [/\b(z\.object|safeParse|parseAsync|validate|schema)\b/] },
-      { label: 'database', patterns: [/\b(prisma|pool\.query|client\.query|SELECT|INSERT|UPDATE|DELETE|db\.)\b/i] },
-      { label: 'response formatting', patterns: [/\b(Response\.json|NextResponse\.json|res\.json)\b/] },
-    ]);
-    if (hints.length >= 3) {
-      candidate(findings.responsibilityBudget, 'mixed route responsibility candidate', file, 1, `route/controller mixes ${hints.join(', ')}; review route/service/repository/response split`, 'warning');
-    }
-  }
-
-  if (isScriptPipeline(file)) {
-    const hints = matchedResponsibilityHints(text, [
-      { label: 'CLI parsing', patterns: [/\b(process\.argv|argparse|ArgumentParser|commander)\b/] },
-      { label: 'file IO', patterns: [/\b(readFile|writeFile|open\(|Path\(|fs\.)\b/] },
-      { label: 'data transform', patterns: [/\.(map|filter|reduce)\s*\(/, /\bjson\.loads\b/i, /\bJSON\.parse\b/] },
-      { label: 'persistence/network', patterns: [/\b(fetch|pool\.query|client\.query|INSERT|UPDATE|DELETE|requests\.)\b/i] },
-      { label: 'reporting', patterns: [/\b(console\.|print\(|logger\.)\b/] },
-    ]);
-    if (hints.length >= 4) {
-      candidate(findings.responsibilityBudget, 'mixed script responsibility candidate', file, 1, `script mixes ${hints.join(', ')}; review CLI/loader/transform/persist/report seams`, 'warning');
-    }
-  }
-}
-
 function newFindingsBag() {
   return {
     largeFiles: [],
@@ -157,7 +100,6 @@ export function scanFiles(files, thresholds) {
     try {
       const text = fs.readFileSync(file.full, 'utf8');
       addSharedScannerCandidates(file, text, findings, thresholds);
-      scanMixedResponsibilities(file, text, findings);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       candidate(findings.scanWarnings, 'scan warning', file, 1, `file could not be scanned and was omitted from rule candidates: ${message}`, 'warning');

package/cli/guard/registry.mjs

@@ -18,6 +18,9 @@ export const FINDING_METADATA = {
   'responsibility.route.budget': { family: 'responsibility_budget', pack: 'core', scanner: 'scanResponsibilityBudget' },
   'responsibility.script.budget': { family: 'responsibility_budget', pack: 'core', scanner: 'scanResponsibilityBudget' },
   'responsibility.python_orchestrator.budget': { family: 'responsibility_budget', pack: 'core', scanner: 'scanResponsibilityBudget' },
+  'responsibility.client.mixed': { family: 'responsibility_budget', pack: 'core', scanner: 'scanResponsibilityBudget' },
+  'responsibility.route.mixed': { family: 'responsibility_budget', pack: 'core', scanner: 'scanResponsibilityBudget' },
+  'responsibility.script.mixed': { family: 'responsibility_budget', pack: 'core', scanner: 'scanResponsibilityBudget' },
   'srp.function.length': { family: 'single_responsibility_advisory', pack: 'core', scanner: 'scanSingleResponsibility' },
   'srp.function.mixed_responsibility': { family: 'single_responsibility_advisory', pack: 'core', scanner: 'scanSingleResponsibility' },
   'srp.module.mixed_exports': { family: 'single_responsibility_advisory', pack: 'core', scanner: 'scanSingleResponsibility' },

package/cli/guard/reporting.mjs

@@ -66,7 +66,7 @@ function guidanceForFinding(item) {
   if (family === 'single_responsibility_advisory') {
     return {
       means: 'This class, module, or function may have more than one reason to change. The finding is heuristic and should be reviewed, not treated as proof.',
-      next: 'Name the one main responsibility, then move only independently changing work behind a real seam; avoid extracting shallow pass-through wrappers.',
+      next: 'Name the one main responsibility, then move only independently changing work behind a real seam; keep always-cochanging contract pieces together and avoid shallow pass-through wrappers.',
     };
   }
   if (family === 'external_input_validation') {

package/cli/guard/scanners/code-health.mjs

@@ -1,6 +1,8 @@
 import path from 'node:path';
 import {
   hasUseClientDirective,
+  isRouteLikePath,
+  isScriptPipelinePath,
   isSourceCodePath,
   lineAt,
   violation,
@@ -119,6 +121,42 @@ export function scanFileSizeAdvisory(relPath, text, settings) {
   return [];
 }
 
+function matchedResponsibilityHints(text, hintGroups) {
+  return hintGroups
+    .filter((group) => group.patterns.some((pattern) => pattern.test(text)))
+    .map((group) => group.label);
+}
+
+function mixedClientResponsibilityHints(text) {
+  return matchedResponsibilityHints(text, [
+    { label: 'browser storage', patterns: [/\b(localStorage|sessionStorage)\b/] },
+    { label: 'network/API', patterns: [/\bfetch\s*\(/, /\baxios\./, /\buse(Query|Mutation)\s*\(/] },
+    { label: 'toast/notification', patterns: [/\btoast\b/, /\bnotify\b/] },
+    { label: 'modal/dialog state', patterns: [/\b(Dialog|Modal|Sheet)\b/, /\bopen[A-Z]\w*\b/, /\bis[A-Z]\w*Open\b/] },
+    { label: 'route navigation', patterns: [/\buseRouter\s*\(/, /\brouter\.(push|replace|refresh)\b/] },
+    { label: 'heavy mapping', patterns: [/\.(map|filter|reduce)\s*\(/] },
+  ]);
+}
+
+function mixedRouteResponsibilityHints(text) {
+  return matchedResponsibilityHints(text, [
+    { label: 'auth/session', patterns: [/\b(auth|session|permission|currentUser|getUser)\b/i] },
+    { label: 'validation', patterns: [/\b(z\.object|safeParse|parseAsync|validate|schema)\b/] },
+    { label: 'database', patterns: [/\b(prisma|pool\.query|client\.query|SELECT|INSERT|UPDATE|DELETE|db\.)\b/i] },
+    { label: 'response formatting', patterns: [/\b(Response\.json|NextResponse\.json|res\.json)\b/] },
+  ]);
+}
+
+function mixedScriptResponsibilityHints(text) {
+  return matchedResponsibilityHints(text, [
+    { label: 'CLI parsing', patterns: [/\b(process\.argv|argparse|ArgumentParser|commander)\b/] },
+    { label: 'file IO', patterns: [/\b(readFile|writeFile|open\(|Path\(|fs\.)\b/] },
+    { label: 'data transform', patterns: [/\.(map|filter|reduce)\s*\(/, /\bjson\.loads\b/i, /\bJSON\.parse\b/] },
+    { label: 'persistence/network', patterns: [/\b(fetch|pool\.query|client\.query|INSERT|UPDATE|DELETE|requests\.)\b/i] },
+    { label: 'reporting', patterns: [/\b(console\.|print\(|logger\.)\b/] },
+  ]);
+}
+
 export function scanResponsibilityBudget(relPath, text, settings) {
   const ext = path.extname(relPath).toLowerCase();
   if (!['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.py'].includes(ext)) return [];
@@ -131,17 +169,35 @@ export function scanResponsibilityBudget(relPath, text, settings) {
   if (hasUseClientDirective(text) && lineCount > settings.client_module_review_lines) {
     out.push(violation({ ruleId: 'responsibility.client.budget', severity: 'warning', relPath, symbol: 'use-client', message: `${lineCount} lines in client module; review hook/adapter/presentation split.`, confidence: 'medium' }));
   }
-  const routeLike = /(^|\/)(api|routes?|controllers?|pages\/api)\//i.test(relPath) || /route\.(ts|js)$/.test(relPath);
+  const routeLike = isRouteLikePath(relPath);
   if (routeLike && lineCount >= settings.route_review_lines) {
     out.push(violation({ ruleId: 'responsibility.route.budget', severity: 'warning', relPath, symbol: 'route', message: `${lineCount} lines in route/controller-like file; review auth/validation/service/response seams.`, confidence: 'medium' }));
   }
-  const scriptPipeline = /(^|\/)scripts\/(data|ops|import|imports|backfill|repair|migrate|migration)\//.test(relPath);
+  const scriptPipeline = isScriptPipelinePath(relPath);
   if (scriptPipeline && lineCount >= settings.import_ops_script_review_lines) {
     out.push(violation({ ruleId: 'responsibility.script.budget', severity: 'warning', relPath, symbol: 'script-pipeline', message: `${lineCount} lines in import/ops-style script; review CLI/loader/transform/persist/report seams.`, confidence: 'medium' }));
   }
   if (ext === '.py' && /(^|\/)(main|.*orchestrator|.*runner|stage_runner)\.py$/.test(relPath) && lineCount >= settings.python_orchestrator_review_lines) {
     out.push(violation({ ruleId: 'responsibility.python_orchestrator.budget', severity: 'warning', relPath, symbol: 'python-orchestrator', message: `${lineCount} lines in Python orchestrator/runner; review policy/IO/runtime/notification/result seams.`, confidence: 'medium' }));
   }
+  if (hasUseClientDirective(text)) {
+    const hints = mixedClientResponsibilityHints(text);
+    if (hints.length >= 3) {
+      out.push(violation({ ruleId: 'responsibility.client.mixed', severity: 'warning', relPath, symbol: 'use-client-mixed', message: `client module mixes ${hints.slice(0, 4).join(', ')}; review hook/adapter/presentation split.`, confidence: 'low' }));
+    }
+  }
+  if (routeLike) {
+    const hints = mixedRouteResponsibilityHints(text);
+    if (hints.length >= 3) {
+      out.push(violation({ ruleId: 'responsibility.route.mixed', severity: 'warning', relPath, symbol: 'route-mixed', message: `route/controller mixes ${hints.join(', ')}; review route/service/repository/response split.`, confidence: 'low' }));
+    }
+  }
+  if (scriptPipeline) {
+    const hints = mixedScriptResponsibilityHints(text);
+    if (hints.length >= 4) {
+      out.push(violation({ ruleId: 'responsibility.script.mixed', severity: 'warning', relPath, symbol: 'script-pipeline-mixed', message: `script mixes ${hints.join(', ')}; review CLI/loader/transform/persist/report seams.`, confidence: 'low' }));
+    }
+  }
   return out;
 }
 

package/cli/guard/scanners/single-responsibility.mjs

@@ -12,11 +12,14 @@ const RESPONSIBILITY_HINTS = [
   { label: 'validation', patterns: [/\b(validate|validator|safeParse|parseAsync|schema|assert|parseEnv|errors\.push)\b/i] },
   { label: 'filesystem IO', patterns: [/\b(fs\.|readFile|writeFile|mkdir|rmSync|cpSync|readdirSync)\b/i] },
   { label: 'process/git/network IO', patterns: [/\b(spawnSync|execFileSync|fetch\(|axios\.|git\(|git\s+-C)\b/i] },
-  { label: 'persistence', patterns: [/\b(prisma|pool\.query|client\.query|db\.|INSERT\s+INTO|UPDATE\s+\w|DELETE\s+FROM|SELECT\s+.+\s+FROM)\b/i] },
+  { label: 'persistence', patterns: [/\b(prisma|pool\.query|client\.query|db\.|INSERT\s+INTO|UPDATE\s+\w|DELETE\s+FROM|SELECT\s+.+\s+FROM)\b/i, /\b\w*(Repository|Repo|Store)\.(find|findMany|save|create|insert|update|delete|upsert|query|persist)\w*\s*\(/i] },
   { label: 'rendering/reporting', patterns: [/\b(console\.|Response\.json|NextResponse\.json|res\.json|render|markdown|tableRows|print|logger\.)\b/i] },
   { label: 'prompting', patterns: [/\b(ask\(|readline|question\(|prompt)\b/i] },
   { label: 'data transformation', patterns: [/\btransform|serialize|deserialize\b/i] },
   { label: 'time/crypto policy', patterns: [/\b(Date\.now|new Date\(|crypto\.|randomUUID|createHash)\b/i] },
+  { label: 'notification/email side effect', patterns: [/\b\w*(Email|Mail|Notification|Notifier)\w*\.(send|deliver|notify|enqueue|publish)\w*\s*\(/i, /\b(sendEmail|sendMail|sendWelcome|notifyUser)\w*\s*\(/i] },
+  { label: 'billing/payment side effect', patterns: [/\b\w*(Payment|Billing|Invoice|Subscription|Stripe)\w*\.(create|charge|capture|refund|update|cancel)\w*\s*\(/i] },
+  { label: 'event/queue side effect', patterns: [/\b(eventBus|queue|publisher|producer)\.(publish|send|enqueue|emit)\w*\s*\(/i] },
 ];
 
 const EXPORT_NAME_FAMILIES = [
@@ -56,6 +59,45 @@ function functionDeclarations(text) {
   return out;
 }
 
+const CONTROL_FLOW_NAMES = new Set(['if', 'for', 'while', 'switch', 'catch', 'function']);
+
+function braceDepthBetween(text, start, end) {
+  let depth = 0;
+  for (let index = start; index < end; index += 1) {
+    if (text[index] === '{') depth += 1;
+    if (text[index] === '}') depth -= 1;
+  }
+  return depth;
+}
+
+function classMethodDeclarations(text) {
+  const classPattern = /(?:^|\n)[ \t]*(?:export\s+)?(?:default\s+)?(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)[^{]*\{/gu;
+  const methodPattern = /(?:^|\n)([ \t]*(?:(?:public|private|protected|static|override|abstract|async|get|set)\s+)*([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*(?::[^{;\n]+)?\s*\{)/gu;
+  const out = [];
+  for (const classMatch of text.matchAll(classPattern)) {
+    const className = classMatch[1] || 'AnonymousClass';
+    const classStart = (classMatch.index || 0) + (classMatch[0].startsWith('\n') ? 1 : 0);
+    const classOpen = text.indexOf('{', classStart);
+    if (classOpen === -1) continue;
+    const classEnd = matchingBraceIndex(text, classOpen);
+    if (classEnd === -1) continue;
+    const classBodyStart = classOpen + 1;
+    const classBody = text.slice(classBodyStart, classEnd);
+    for (const methodMatch of classBody.matchAll(methodPattern)) {
+      const methodName = methodMatch[2] || 'anonymous';
+      if (CONTROL_FLOW_NAMES.has(methodName)) continue;
+      const relativeStart = (methodMatch.index || 0) + (methodMatch[0].startsWith('\n') ? 1 : 0);
+      const start = classBodyStart + relativeStart;
+      if (braceDepthBetween(text, classOpen, start) !== 1) continue;
+      const openBrace = classBodyStart + (methodMatch.index || 0) + methodMatch[0].lastIndexOf('{');
+      const end = matchingBraceIndex(text, openBrace);
+      if (end === -1 || end > classEnd) continue;
+      out.push({ name: `${className}.${methodName}`, start, end, body: text.slice(start, end + 1) });
+    }
+  }
+  return out;
+}
+
 function matchingBraceIndex(text, openBrace) {
   let depth = 0;
   let quote = '';
@@ -111,7 +153,8 @@ function pythonFunctionDeclarations(text) {
 }
 
 function declarationsForPath(relPath, text) {
-  return relPath.endsWith('.py') ? pythonFunctionDeclarations(text) : functionDeclarations(text);
+  if (relPath.endsWith('.py')) return pythonFunctionDeclarations(text);
+  return [...functionDeclarations(text), ...classMethodDeclarations(text)].sort((left, right) => left.start - right.start);
 }
 
 function exportedCallableNames(text) {

package/cli/install-actions/skills.mjs

@@ -5,6 +5,13 @@ import { readJsonFile, validateJsonObject, validateStringArray } from '../json-f
 
 export const SKILLS_MANIFEST_NAME = '.jhste-skills-manifest.json';
 export const MANIFEST_MANAGED_BY = 'jhste-skills';
+export const LEGACY_SKILL_RENAMES = Object.freeze({
+  diagnose: 'diagnosing-bugs',
+});
+
+export function canonicalSkillName(name) {
+  return LEGACY_SKILL_RENAMES[name] || name;
+}
 
 function vendoredSkillNames() {
   const allowlistPath = path.join(KIT_ROOT, 'vendor', 'matt-pocock', 'allowlist.json');
@@ -16,7 +23,7 @@ function vendoredSkillNames() {
 
 export function skillNamesForSet(skillSet) {
   const sourceRoot = path.join(KIT_ROOT, 'skills');
-  const all = listDirectories(sourceRoot);
+  const all = listDirectories(sourceRoot).filter((name) => !Object.prototype.hasOwnProperty.call(LEGACY_SKILL_RENAMES, name));
   const vendored = vendoredSkillNames();
   if (skillSet === 'all') return all;
   if (skillSet === 'vendor') return all.filter((name) => vendored.has(name));
@@ -72,6 +79,27 @@ function canAdoptKnownSkill({ manifest = null, adoptKnownSkills = false } = {})
   return Boolean(adoptKnownSkills && manifest && !manifest.invalid);
 }
 
+function canMigrateLegacySkill({ currentManifest, legacyName, allowUnmanagedOverwrite = false, adoptKnownSkills = false }) {
+  if (allowUnmanagedOverwrite) return true;
+  if (currentManifest?.skills?.[legacyName]) return true;
+  return canAdoptKnownSkill({ manifest: currentManifest, adoptKnownSkills });
+}
+
+function removeLegacySkillDirectories(skillsDir, selected, currentManifest, nextManifest, { allowUnmanagedOverwrite = false, adoptKnownSkills = false } = {}) {
+  const selectedSet = new Set(selected.map((name) => canonicalSkillName(name)));
+  const results = [];
+  for (const [legacyName, canonicalName] of Object.entries(LEGACY_SKILL_RENAMES)) {
+    delete nextManifest.skills[legacyName];
+    if (!selectedSet.has(canonicalName)) continue;
+    const legacyPath = path.join(skillsDir, legacyName);
+    if (!fs.existsSync(legacyPath)) continue;
+    if (!canMigrateLegacySkill({ currentManifest, legacyName, allowUnmanagedOverwrite, adoptKnownSkills })) continue;
+    fs.rmSync(legacyPath, { recursive: true, force: true });
+    results.push({ status: 'removed-legacy-renamed-skill', source: legacyPath, destination: path.join(skillsDir, canonicalName), legacyName, canonicalName });
+  }
+  return results;
+}
+
 function copyManagedSkill(source, destination, name, {
   force = false,
   allowUnmanagedOverwrite = false,
@@ -124,9 +152,7 @@ function unmanagedSkillConflicts(selected, sourceRoot, skillsDir, currentManifes
   for (const name of selected) {
     const source = path.join(sourceRoot, name);
     const destination = path.join(skillsDir, name);
-    if (!fs.existsSync(source) || !fs.existsSync(destination)) continue;
-    if (directoryDigest(source) === directoryDigest(destination)) continue;
-    if (!currentManifest?.skills?.[name] && !canAdopt) {
+    if (fs.existsSync(source) && fs.existsSync(destination) && directoryDigest(source) !== directoryDigest(destination) && !currentManifest?.skills?.[name] && !canAdopt) {
       out.push({
         status: 'skipped-unmanaged-different',
         source,
@@ -135,6 +161,18 @@ function unmanagedSkillConflicts(selected, sourceRoot, skillsDir, currentManifes
       });
     }
   }
+  for (const [legacyName, canonicalName] of Object.entries(LEGACY_SKILL_RENAMES)) {
+    if (!selected.includes(canonicalName)) continue;
+    const legacyPath = path.join(skillsDir, legacyName);
+    if (!fs.existsSync(legacyPath)) continue;
+    if (canMigrateLegacySkill({ currentManifest, legacyName, adoptKnownSkills })) continue;
+    out.push({
+      status: 'skipped-unmanaged-different',
+      source: legacyPath,
+      destination: path.join(skillsDir, canonicalName),
+      reason: `${legacyName} is an older skill name that is not recorded as managed by ${MANIFEST_MANAGED_BY}; pass --allow-unmanaged-skill-overwrite only after review`,
+    });
+  }
   return out;
 }
 
@@ -146,7 +184,7 @@ export function installSkills(skillsDir, {
 } = {}) {
   const sourceRoot = path.join(KIT_ROOT, 'skills');
   ensureDir(skillsDir);
-  const selected = Array.isArray(skillSet) ? skillSet : skillNamesForSet(skillSet);
+  const selected = (Array.isArray(skillSet) ? skillSet : skillNamesForSet(skillSet)).map((name) => canonicalSkillName(name));
   const currentManifest = loadSkillsManifest(skillsDir);
   if (currentManifest?.invalid) return [{ status: 'invalid-manifest', source: '', destination: manifestPath(skillsDir), reason: currentManifest.reason }];
   const nextManifest = currentManifest || { managed_by: MANIFEST_MANAGED_BY, version: packageVersion(), installed_at: nowIso(), skills: {} };
@@ -158,6 +196,10 @@ export function installSkills(skillsDir, {
     ? unmanagedSkillConflicts(selected, sourceRoot, skillsDir, currentManifest, { adoptKnownSkills })
     : [];
   if (conflicts.length) return conflicts;
+  const legacyResults = removeLegacySkillDirectories(skillsDir, selected, currentManifest, nextManifest, {
+    allowUnmanagedOverwrite,
+    adoptKnownSkills,
+  });
   const results = selected.map((name) => copyManagedSkill(path.join(sourceRoot, name), path.join(skillsDir, name), name, {
     force,
     allowUnmanagedOverwrite,
@@ -166,5 +208,5 @@ export function installSkills(skillsDir, {
     nextManifest,
   }));
   writeSkillsManifest(skillsDir, nextManifest);
-  return results;
+  return [...legacyResults, ...results];
 }

package/cli/sync-core.mjs

@@ -12,6 +12,7 @@ import {
   readIfExists,
 } from './shared.mjs';
 import { applyPlan, preflightPlan, printApplyResult } from './install-actions.mjs';
+import { LEGACY_SKILL_RENAMES, canonicalSkillName } from './install-actions/skills.mjs';
 import { gitHooksDir, HOOKS, isManagedHook } from './hook-utils.mjs';
 import { printConfigErrors, printPlanSummary } from './install-flow/output.mjs';
 import { readJsonFile, validateStringArray } from './json-file.mjs';
@@ -91,7 +92,14 @@ function sourceSkillNames() {
 
 function detectInstalledSkillNames(skillsDir) {
   const known = new Set(sourceSkillNames());
-  return listDirectories(skillsDir).filter((name) => known.has(name));
+  const detected = new Set();
+  for (const name of listDirectories(skillsDir)) {
+    const canonicalName = canonicalSkillName(name);
+    if (known.has(canonicalName) || Object.prototype.hasOwnProperty.call(LEGACY_SKILL_RENAMES, name)) {
+      detected.add(canonicalName);
+    }
+  }
+  return [...detected];
 }
 
 function skillNamesForSet(skillSet) {

package/docs/ACCEPTANCE_CHECK.md

@@ -52,3 +52,11 @@ npm pack --dry-run
 Record actual command output in release notes before publishing a release.
 
 Release gates include dependency-free syntax checking, a first-run `install -> deep-scan -> tune --yes -> guard` smoke flow, `npm pack --dry-run` contents checks, and packed-tarball bin execution in a fresh temp consumer. These gates are not part of commit-time hooks.
+
+- Verify `sync`/`update` migrates older managed vendored renames without leaving duplicate directories, including `diagnose` → `diagnosing-bugs`.
+
+## npm trusted publishing
+
+Package publishing is handled by `.github/workflows/publish-npm.yml` on `v*.*.*` tags using GitHub Actions OIDC trusted publishing. The workflow grants `id-token: write`, runs `npm test`, and publishes with provenance, so it does not require a long-lived npm token, local `npm adduser`, or OAuth login in the release shell.
+
+Before cutting a tag, confirm the npm package's trusted publisher settings match this repository and workflow file exactly: GitHub owner/repo `jhste102lab/jhste-skills`, workflow `publish-npm.yml`, and no environment unless one is added to the workflow.

package/docs/CONFLICT_RESOLUTION.md

@@ -56,3 +56,5 @@ If a similar section exists, the installer prints the snippet instead of editing
 ## Existing hooks
 
 Managed hooks are identified by the jhste-skills hook markers. Existing non-managed hooks are never overwritten, including in `Full` mode and with `--force`. Full may install multiple hook targets, but each target is reported separately as installed, refreshed, skipped because non-managed, or failed.
+
+Legacy vendored renames are treated differently from unmanaged conflicts. During `sync` and `update`, an older managed `diagnose` install is migrated to `diagnosing-bugs` automatically so the skills directory does not keep both names.

package/docs/RULES.md

@@ -89,6 +89,8 @@ The rule should be used with `advisory`, `changed-files`, or `baseline-new-only`
 
 `single_responsibility_advisory` is a heuristic review signal for changed classes, modules, and functions. It looks for long functions, functions that appear to mix several concern categories, and modules whose exports look like unrelated helper families. Treat findings as prompts to name one main responsibility and one reason to change; do not extract pass-through wrappers just to silence the warning. The rule remains advisory by default, but repositories can opt into changed-file blocking by setting the rule mode and `guard.fail_on: warning`.
 
+SRP is not a "one function per file" or "smallest possible file" rule. A split is useful when the separated code has an independent reason to change, an understandable file-level responsibility, and a natural behavior or side-effect seam to test. If type definitions, select aliases, mappers, constants, or tiny wrappers always change together and force readers to chase several files to understand one contract, prefer a cohesive contract module instead. The built-in scanner only emits low-confidence static candidates; co-change history, call graphs, and reader navigation cost still require human review.
+
 ## Restricted profile format
 
 `.jhste/profile.yaml` uses a documented restricted YAML-like contract rather than arbitrary YAML. Supported operational sections are `mode`, `packs.<id>.mode`, `rules.<id>.mode`, file-size/responsibility/single-responsibility threshold keys, `baseline.enabled`, `baseline.path`, `guard.default_scope`, `guard.default_format`, `guard.fail_on`, `guard.exit_codes`, and `commands` with `cmd`/`args` or legacy `run`. Unknown pack ids, rule ids, guard keys, baseline keys, command keys, duplicate operational sections, and invalid numeric thresholds are config failures with exit `3`. Documentation-only metadata sections such as `recommendations`, `adapters`, `deep_scan`, `workflow`, and `strict` do not affect guard runtime settings.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jhste-skills",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Installable engineering guardrails and workflow skills for AI coding agents.",
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "npm run syntax:check && npm run docs:check && npm run vendor:check && npm run public-safety:check && npm run public-safety-fixtures:test && npm run profile-fixtures:test && npm run guard-fixtures:test && npm run single-responsibility-fixtures:test && npm run smoke:test && npm run release:gates",
+    "test": "npm run syntax:check && npm run docs:check && npm run vendor:check && npm run public-safety:check && npm run public-safety-fixtures:test && npm run profile-fixtures:test && npm run guard-fixtures:test && npm run responsibility-budget-fixtures:test && npm run single-responsibility-fixtures:test && npm run smoke:test && npm run release:gates",
     "syntax:check": "node scripts/syntax-check.mjs",
     "docs:check": "node scripts/docs-check.mjs",
     "vendor:check": "node scripts/vendor-check.mjs",
@@ -41,6 +41,7 @@
     "public-safety-fixtures:test": "node scripts/public-safety-fixtures-test.mjs",
     "profile-fixtures:test": "node scripts/profile-fixtures-test.mjs",
     "guard-fixtures:test": "node scripts/guard-fixtures-test.mjs",
+    "responsibility-budget-fixtures:test": "node scripts/responsibility-budget-fixtures-test.mjs",
     "single-responsibility-fixtures:test": "node scripts/single-responsibility-fixtures-test.mjs",
     "smoke:test": "node scripts/smoke-test.mjs",
     "release:gates": "node scripts/release-gates-test.mjs"

package/rules/core/responsibility_budget.yaml

@@ -35,6 +35,9 @@ implementation:
       - responsibility.route.budget
       - responsibility.script.budget
       - responsibility.python_orchestrator.budget
+      - responsibility.client.mixed
+      - responsibility.route.mixed
+      - responsibility.script.mixed
 recommendation:
   changed_files: true
   baseline_supported: true

package/rules/core/single_responsibility_advisory.yaml

@@ -31,5 +31,5 @@ recommendation:
   baseline_supported: true
   default_enforcement: review_only
 public_safe_examples:
-  bad: Keep adding parsing, validation, filesystem IO, prompting, transformation, persistence, and reporting to one function or shared utility bucket.
-  good: Name the changed module or function's one responsibility, keep cohesive implementation inside deep modules, and extract only when a real seam improves locality.
+  bad: Keep adding parsing, validation, filesystem IO, prompting, transformation, persistence, and reporting to one function or split every type, select alias, mapper, and tiny wrapper into separate files that always change together.
+  good: Name the changed module or function's one responsibility and one independent reason to change; keep cohesive contracts together inside deep modules, and extract only when a real tested seam improves locality.

package/scripts/responsibility-budget-fixtures-test.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import {
+  fail,
+  guardJson,
+  hasRule,
+  makeRepo,
+  write,
+} from './guard-fixtures/helpers.mjs';
+
+{
+  const repo = makeRepo('responsibility-mixed');
+  write(path.join(repo, 'src/components/EventPanel.tsx'), `"use client";
+export function EventPanel() {
+  const cached = localStorage.getItem('event');
+  fetch('/api/events');
+  toast.success(cached);
+  return <Dialog open={true} />;
+}
+`);
+  write(path.join(repo, 'src/app/api/events/route.ts'), `const schema = { safeParse(value) { return { success: true, data: value }; } };
+export async function POST(request) {
+  const user = await requireUser();
+  const body = schema.safeParse(await request.json());
+  const rows = await prisma.event.findMany({ where: { userId: user.id } });
+  return Response.json({ body, rows });
+}
+`);
+  write(path.join(repo, 'scripts/import/events.ts'), `import fs from 'node:fs';
+export async function main() {
+  const file = process.argv[2];
+  const rows = JSON.parse(fs.readFileSync(file, 'utf8')).map((row) => row.id);
+  await fetch('https://example.test/events');
+  console.log(rows.length);
+}
+`);
+  const result = guardJson(repo);
+  if (!hasRule(result, 'responsibility.client.mixed', 'EventPanel.tsx')) fail('mixed client responsibility was not reported by guard');
+  if (!hasRule(result, 'responsibility.route.mixed', 'events/route.ts')) fail('mixed route responsibility was not reported by guard');
+  if (!hasRule(result, 'responsibility.script.mixed', 'scripts/import/events.ts')) fail('mixed script responsibility was not reported by guard');
+  for (const ruleId of ['responsibility.client.mixed', 'responsibility.route.mixed', 'responsibility.script.mixed']) {
+    const item = result.violations.find((violation) => violation.rule_id === ruleId);
+    if (item.confidence !== 'low' || item.severity !== 'warning') fail(`${ruleId} should be low-confidence warning`);
+  }
+}
+
+console.log('responsibility-budget-fixtures-test passed: mixed responsibility candidates verified.');

package/scripts/single-responsibility-fixtures-test.mjs

@@ -61,6 +61,23 @@ export function importRows(argv) {
   if (item.confidence !== 'low' || item.severity !== 'warning') fail('mixed function SRP candidate should be low-confidence warning');
 }
 
+{
+  const repo = makeRepo('class-method-mixed');
+  write(path.join(repo, 'src/UserService.ts'), `export class UserService {
+  async register(input) {
+    const user = await userRepository.save(input);
+    await emailService.sendWelcome(user.email);
+    await paymentClient.createCustomer(user.id);
+    return user;
+  }
+}
+`);
+  const result = guardJson(repo);
+  const item = result.violations.find((violation) => violation.rule_id === 'srp.function.mixed_responsibility' && violation.symbol === 'UserService.register');
+  if (!item) fail('mixed class method SRP candidate was not reported');
+  if (item.confidence !== 'low' || item.severity !== 'warning') fail('mixed class method SRP candidate should be low-confidence warning');
+}
+
 {
   const repo = makeRepo('module-exports');
   write(path.join(repo, 'src/shared.ts'), `export function parseArgs() { return {}; }

package/scripts/smoke/connect-scenarios.mjs

@@ -13,7 +13,7 @@ export function runConnectScenarios({ root, tmp, skillsDir }) {
   fs.mkdirSync(nonGitCwd, { recursive: true });
   run(process.execPath, [path.join(root, 'cli/install.mjs'), '--yes', '--skills-dir', nonGitCwdSkills, '--skip-deep-scan'], { cwd: nonGitCwd });
   if (fs.existsSync(path.join(nonGitCwd, '.jhste'))) fail('install outside git repo created .jhste');
-  if (skillDirs(nonGitCwdSkills).length !== 21) fail('install outside git repo did not install bundled skills');
+  if (skillDirs(nonGitCwdSkills).length !== 20) fail('install outside git repo did not install 20 bundled skills');
 
   const explicitNonGitRepo = path.join(tmp, 'explicit-non-git-repo');
   const explicitNonGitSkills = path.join(tmp, 'explicit-non-git-skills');
@@ -42,6 +42,6 @@ export function runConnectScenarios({ root, tmp, skillsDir }) {
   if (connectMissing.status !== 3) fail(`connect missing skills should exit 3, got ${connectMissing.status}`);
   if (fs.existsSync(path.join(connectMissingRepo, '.jhste'))) fail('connect missing skills created .jhste');
   run(process.execPath, [path.join(root, 'cli/connect.mjs'), '--mode', 'normal', '--yes', '--repo', connectMissingRepo, '--skills-dir', connectMissingSkills, '--skip-deep-scan', '--install-missing'], { cwd: connectMissingRepo });
-  if (skillDirs(connectMissingSkills).length !== 21) fail('connect --install-missing did not install bundled skills');
+  if (skillDirs(connectMissingSkills).length !== 20) fail('connect --install-missing did not install 20 bundled skills');
   if (!fs.existsSync(path.join(connectMissingRepo, '.jhste', 'profile.yaml'))) fail('connect --install-missing did not create profile');
 }

package/scripts/smoke/install-scenarios.mjs

@@ -28,6 +28,15 @@ function initRepo(repo) {
   run('git', ['init'], { cwd: repo });
 }
 
+function readManagedSkillsManifest(skillsDir) {
+  const manifestPath = path.join(skillsDir, '.jhste-skills-manifest.json');
+  const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) fail('skills manifest is not an object');
+  if (parsed.managed_by !== 'jhste-skills') fail('skills manifest managed_by is invalid');
+  if (!parsed.skills || typeof parsed.skills !== 'object' || Array.isArray(parsed.skills)) fail('skills manifest skills map is invalid');
+  return parsed;
+}
+
 function runRefusalScenarios({ root, tmp }) {
   const nonInteractiveRepo = path.join(tmp, 'noninteractive-repo');
   const nonInteractiveSkills = path.join(tmp, 'noninteractive-skills');
@@ -103,10 +112,10 @@ function runDefaultInstall(ctx) {
   if (!fs.readFileSync(defaultPreCommit, 'utf8').includes(`# jhste-skills version=${version}`)) fail('default pre-commit hook missing version comment');
   if (!fs.existsSync(path.join(skillsDir, 'jhste-red-team-review', 'SKILL.md'))) fail('install did not copy jhste-red-team-review skill');
   if (!fs.existsSync(path.join(skillsDir, '.jhste-skills-manifest.json'))) fail('install did not write skills manifest');
-  const manifest = JSON.parse(fs.readFileSync(path.join(skillsDir, '.jhste-skills-manifest.json'), 'utf8'));
+  const manifest = readManagedSkillsManifest(skillsDir);
   if (manifest.managed_by !== 'jhste-skills' || !manifest.skills?.['jhste-red-team-review']?.digest) fail('skills manifest missing managed skill digest');
   const defaultSkillDirs = skillDirs(skillsDir);
-  if (defaultSkillDirs.length !== 21) fail(`default install should copy 21 bundled skills, got ${defaultSkillDirs.length}`);
+  if (defaultSkillDirs.length !== 20) fail(`default install should copy 20 bundled skills, got ${defaultSkillDirs.length}`);
   if (!defaultSkillDirs.includes('improve-codebase-architecture')) fail('default install should copy vendored workflow skills');
 }
 
@@ -162,9 +171,28 @@ run_jhste_skills guard --scope staged --format text --fail-on warning
   if (!updatedPreCommit.includes(`# jhste-skills version=${version}`)) fail('update did not refresh hook version comment');
   if (updatedPreCommit.includes('stale hook')) fail('update did not replace stale managed hook content');
 
-  const managedManifest = JSON.parse(fs.readFileSync(path.join(skillsDir, '.jhste-skills-manifest.json'), 'utf8'));
+  const managedManifest = readManagedSkillsManifest(skillsDir);
   if (!managedManifest.skills?.[adoptedSkillName]?.digest) fail('update did not record adopted known skill in manifest');
 
+  const legacySkillName = 'diagnose';
+  const canonicalSkillName = 'diagnosing-bugs';
+  const legacySkillDir = path.join(skillsDir, legacySkillName);
+  fs.mkdirSync(legacySkillDir, { recursive: true });
+  fs.writeFileSync(path.join(legacySkillDir, 'SKILL.md'), '# stale legacy diagnose copy\n');
+  managedManifest.skills[legacySkillName] = { digest: 'legacy-digest' };
+  fs.writeFileSync(path.join(skillsDir, '.jhste-skills-manifest.json'), `${JSON.stringify(managedManifest, null, 2)}\n`);
+
+  run(process.execPath, [path.join(root, 'cli/update.mjs'), '--yes', '--repo', repo, '--skills-dir', skillsDir], { cwd: repo });
+
+  if (fs.existsSync(legacySkillDir)) fail('update did not remove legacy diagnose skill directory');
+  const canonicalSkillPath = path.join(skillsDir, canonicalSkillName, 'SKILL.md');
+  if (fs.readFileSync(canonicalSkillPath, 'utf8') !== fs.readFileSync(path.join(root, 'skills', canonicalSkillName, 'SKILL.md'), 'utf8')) {
+    fail('update did not keep canonical diagnosing-bugs skill content after legacy migration');
+  }
+  const migratedManifest = readManagedSkillsManifest(skillsDir);
+  if (migratedManifest.skills?.[legacySkillName]) fail('update left legacy diagnose entry in manifest after migration');
+  if (!migratedManifest.skills?.[canonicalSkillName]?.digest) fail('update did not keep canonical diagnosing-bugs entry in manifest after migration');
+
   const unmanagedSkills = path.join(path.dirname(skillsDir), 'unmanaged-skills');
   fs.mkdirSync(path.join(unmanagedSkills, 'jhste-code-quality'), { recursive: true });
   fs.writeFileSync(path.join(unmanagedSkills, 'jhste-code-quality', 'SKILL.md'), '# unmanaged local copy\n');
@@ -218,7 +246,7 @@ function runSkillSetScenarios({ root, tmp }) {
   fs.writeFileSync(path.join(vendorRepo, 'AGENTS.md'), '# Vendor skill repo\n');
   run(process.execPath, [path.join(root, 'cli/install.mjs'), '--yes', '--repo', vendorRepo, '--skills-dir', vendorSkillsDir, '--skip-deep-scan', '--skip-hooks', '--skill-set', 'vendor'], { cwd: vendorRepo });
   const vendorSkillDirs = skillDirs(vendorSkillsDir);
-  if (vendorSkillDirs.length !== 14) fail(`--skill-set vendor should copy 14 skills, got ${vendorSkillDirs.length}`);
+  if (vendorSkillDirs.length !== 13) fail(`--skill-set vendor should copy 13 skills, got ${vendorSkillDirs.length}`);
   if (!vendorSkillDirs.includes('improve-codebase-architecture')) fail('--skill-set vendor did not copy expected vendored skill');
   if (vendorSkillDirs.includes('jhste-red-team-review')) fail('--skill-set vendor copied core skill');
 
@@ -228,7 +256,7 @@ function runSkillSetScenarios({ root, tmp }) {
   fs.writeFileSync(path.join(allRepo, 'AGENTS.md'), '# All skill repo\n');
   run(process.execPath, [path.join(root, 'cli/install.mjs'), '--yes', '--repo', allRepo, '--skills-dir', allSkillsDir, '--skip-deep-scan', '--skip-hooks', '--skill-set', 'all'], { cwd: allRepo });
   const allSkillDirs = skillDirs(allSkillsDir);
-  if (allSkillDirs.length !== 21) fail(`--skill-set all should copy 21 skills, got ${allSkillDirs.length}`);
+  if (allSkillDirs.length !== 20) fail(`--skill-set all should copy 20 skills, got ${allSkillDirs.length}`);
   if (!allSkillDirs.includes('jhste-red-team-review') || !allSkillDirs.includes('improve-codebase-architecture')) fail('--skill-set all missing core or vendored skill');
 }
 

package/scripts/smoke/mode-scenarios.mjs

@@ -47,7 +47,7 @@ function runFullModeScenarios({ root, tmp }) {
   fs.writeFileSync(path.join(fullModeRepo, 'AGENTS.md'), '# Full mode repo\n');
   run(process.execPath, [path.join(root, 'cli/install.mjs'), '--mode', 'full', '--yes', '--repo', fullModeRepo, '--skills-dir', fullModeSkillsDir, '--skip-deep-scan'], { cwd: fullModeRepo });
   const fullModeSkillDirs = skillDirs(fullModeSkillsDir);
-  if (fullModeSkillDirs.length !== 21) fail(`--mode full should copy 21 skills, got ${fullModeSkillDirs.length}`);
+  if (fullModeSkillDirs.length !== 20) fail(`--mode full should copy 20 skills, got ${fullModeSkillDirs.length}`);
   const fullPreCommit = path.join(fullModeRepo, '.git', 'hooks', 'pre-commit');
   const fullPrePush = path.join(fullModeRepo, '.git', 'hooks', 'pre-push');
   if (!fs.existsSync(fullPreCommit) || !fs.existsSync(fullPrePush)) fail('--mode full did not install pre-commit and pre-push');

package/scripts/vendor-check.mjs

@@ -6,7 +6,6 @@ import { readJsonFile, validateJsonObject, validateStringArray } from '../cli/js
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const expected = [
-  'diagnose',
   'grill-with-docs',
   'triage',
   'improve-codebase-architecture',
@@ -39,12 +38,12 @@ function readJson(file) {
 
 const allowlist = readJson('vendor/matt-pocock/allowlist.json');
 if (JSON.stringify(allowlist) !== JSON.stringify(expected)) {
-  fail('allowlist does not match the exact 14 selected skills');
+  fail('allowlist does not match the exact 13 selected skills');
 }
 
 const sourceLock = readJson('vendor/matt-pocock/source-lock.json');
 if (!Array.isArray(sourceLock.skills) || sourceLock.skills.length !== expected.length) {
-  fail('source-lock must contain exactly 14 skills');
+  fail('source-lock must contain exactly 13 skills');
 }
 
 const seen = new Set();

package/skills/jhste-architecture-review/references/architecture-review.md

@@ -9,6 +9,8 @@ When reviewing a proposed change, ask:
 - Does this module hide complexity or merely pass it through?
 - Are repo-local docs using a more specific term or rule?
 - Where do caller contracts, mutation safety, or hot-path performance assumptions belong so they stay visible instead of leaking across seams?
+- Do the proposed files change independently, or do they always move together as one cohesive contract?
+- Would the split reduce the number of files touched for a typical change, or merely make readers chase more files?
 
 ## Bad / better / why skeletons
 
@@ -34,6 +36,12 @@ Change adjacent code only when it sits on the changed execution path and leaving
 - Better: each module owns one responsibility such as argument parsing, repository discovery, filesystem operations, prompting, or rendering; keep a compatibility facade only when it contains no policy and prevents churn.
 - Why: maintainers can name one reason to change the module, while callers do not learn unrelated helpers.
 
+### Over-fragmented contract split
+
+- Bad: a cohesive feature contract is split into separate `*-types`, `*-select`, `*-mapper`, `*-aliases`, and tiny wrapper files that are hard to understand alone and usually change in the same commit.
+- Better: keep type, select/shape alias, mapper, and small constants together when they describe one caller-facing contract; split only the independently changing query, policy, side effect, or behavior seam.
+- Why: SRP is about independent reasons to change, not maximizing file count; good splits reduce change surface and test scope without increasing reader navigation cost.
+
 ### Function responsibility split
 
 - Bad: one function parses input, validates it, reads files, transforms data, writes output, prints a report, and decides exit behavior.

package/vendor/matt-pocock/allowlist.json

@@ -1,5 +1,4 @@
 [
-  "diagnose",
   "grill-with-docs",
   "triage",
   "improve-codebase-architecture",

package/vendor/matt-pocock/source-lock.json

@@ -3,14 +3,6 @@
   "imported_at": "2026-06-18T10:53:47Z",
   "license": "MIT",
   "skills": [
-    {
-      "name": "diagnose",
-      "source": "https://github.com/mattpocock/skills/tree/main/skills/engineering/diagnose",
-      "commit": "694fa30311e02c2639942308513555e61ee84a6f",
-      "license": "MIT; see vendor/matt-pocock/LICENSE",
-      "vendored_path": "skills/diagnose",
-      "imported_at": "2026-06-17T10:11:18Z"
-    },
     {
       "name": "grill-with-docs",
       "source": "https://github.com/mattpocock/skills/tree/main/skills/engineering/grill-with-docs",

package/skills/diagnose/SKILL.md

@@ -1,125 +0,0 @@
----
-name: diagnose
-description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
----
-
-## jhste compatibility
-
-- Repo-local instructions remain authoritative.
-- Use `jhste-engineering-judgment` for scope, seams, assumptions, and failure paths when it applies.
-- Vocabulary in this vendored skill is advisory unless adopted by repo-local docs; do not rename established repo concepts only to match this skill.
-- File, repo, command, issue, PR, or other external side effects require explicit approval unless the user already requested that exact side effect.
-
-
-# Diagnose
-
-A discipline for hard bugs. Skip phases only when explicitly justified.
-
-When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
-
-## Phase 1 — Build a feedback loop
-
-**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation all just consume that signal. If you don't have one, no amount of staring at code will save you.
-
-Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
-
-### Ways to construct one — try them in roughly this order
-
-1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
-2. **Curl / HTTP script** against a running dev server.
-3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
-4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
-5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
-6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
-7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
-8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
-9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
-10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
-
-Build the right feedback loop, and the bug is 90% fixed.
-
-### Iterate on the loop itself
-
-Treat the loop as a product. Once you have _a_ loop, ask:
-
-- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
-- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
-- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
-
-A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.
-
-### Non-deterministic bugs
-
-The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
-
-### When you genuinely cannot build a loop
-
-Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
-
-Do not proceed to Phase 2 until you have a loop you believe in.
-
-## Phase 2 — Reproduce
-
-Run the loop. Watch the bug appear.
-
-Confirm:
-
-- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
-- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
-- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
-
-Do not proceed until you reproduce the bug.
-
-## Phase 3 — Hypothesise
-
-Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
-
-Each hypothesis must be **falsifiable**: state the prediction it makes.
-
-> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
-
-If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
-
-**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
-
-## Phase 4 — Instrument
-
-Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
-
-Tool preference:
-
-1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
-2. **Targeted logs** at the boundaries that distinguish hypotheses.
-3. Never "log everything and grep".
-
-**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
-
-**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
-
-## Phase 5 — Fix + regression test
-
-Write the regression test **before the fix** — but only if there is a **correct seam** for it.
-
-A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
-
-**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
-
-If a correct seam exists:
-
-1. Turn the minimised repro into a failing test at that seam.
-2. Watch it fail.
-3. Apply the fix.
-4. Watch it pass.
-5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
-
-## Phase 6 — Cleanup + post-mortem
-
-Required before declaring done:
-
-- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
-- [ ] Regression test passes (or absence of seam is documented)
-- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
-- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
-- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
-
-**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.

package/skills/diagnose/scripts/hitl-loop.template.sh

@@ -1,41 +0,0 @@
-#!/usr/bin/env bash
-# Human-in-the-loop reproduction loop.
-# Copy this file, edit the steps below, and run it.
-# The agent runs the script; the user follows prompts in their terminal.
-#
-# Usage:
-#   bash hitl-loop.template.sh
-#
-# Two helpers:
-#   step "<instruction>"          → show instruction, wait for Enter
-#   capture VAR "<question>"      → show question, read response into VAR
-#
-# At the end, captured values are printed as KEY=VALUE for the agent to parse.
-
-set -euo pipefail
-
-step() {
-  printf '\n>>> %s\n' "$1"
-  read -r -p "    [Enter when done] " _
-}
-
-capture() {
-  local var="$1" question="$2" answer
-  printf '\n>>> %s\n' "$question"
-  read -r -p "    > " answer
-  printf -v "$var" '%s' "$answer"
-}
-
-# --- edit below ---------------------------------------------------------
-
-step "Open the app at http://localhost:3000 and sign in."
-
-capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
-
-capture ERROR_MSG "Paste the error message (or 'none'):"
-
-# --- edit above ---------------------------------------------------------
-
-printf '\n--- Captured ---\n'
-printf 'ERRORED=%s\n' "$ERRORED"
-printf 'ERROR_MSG=%s\n' "$ERROR_MSG"