jhste-skills 0.1.0 → 0.1.2

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.
 
@@ -252,3 +251,5 @@ See [`docs/ACCEPTANCE_CHECK.md`](docs/ACCEPTANCE_CHECK.md) for release acceptanc
 - Run a red-team code review before calling non-trivial work complete.
 
 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. 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/install-actions/apply-plan.mjs

@@ -15,6 +15,7 @@ export function applyPlan(plan) {
     result.skillResults = installSkills(plan.skillsDir, {
       force: plan.forceSkills ?? plan.force,
       allowUnmanagedOverwrite: plan.allowUnmanagedSkillOverwrite,
+      adoptKnownSkills: Boolean(plan.adoptKnownSkills),
       skillSet: plan.skillNames ?? plan.skillSet,
     });
     if (result.skillResults.some((item) => ['skipped-unmanaged-different', 'invalid-manifest'].includes(item.status))) {

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));
@@ -68,7 +75,38 @@ function packageVersion() {
   }
 }
 
-function copyManagedSkill(source, destination, name, { force = false, allowUnmanagedOverwrite = false, manifest = null, nextManifest } = {}) {
+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,
+  adoptKnownSkills = false,
+  manifest = null,
+  nextManifest,
+} = {}) {
   if (!fs.existsSync(source)) return { status: 'missing-source', source, destination };
   const sourceHash = directoryDigest(source);
   const destinationExists = fs.existsSync(destination);
@@ -91,7 +129,8 @@ function copyManagedSkill(source, destination, name, { force = false, allowUnman
     return { status: 'unchanged', source, destination };
   }
   if (!force) return { status: 'skipped-existing-different', source, destination };
-  if (!manifestOwnsDestination && !allowUnmanagedOverwrite) {
+  const adoptKnownSkill = !manifestOwnsDestination && canAdoptKnownSkill({ manifest, adoptKnownSkills });
+  if (!manifestOwnsDestination && !allowUnmanagedOverwrite && !adoptKnownSkill) {
     return {
       status: 'skipped-unmanaged-different',
       source,
@@ -102,17 +141,18 @@ function copyManagedSkill(source, destination, name, { force = false, allowUnman
   fs.rmSync(destination, { recursive: true, force: true });
   fs.cpSync(source, destination, { recursive: true });
   recordManaged();
-  return { status: manifestOwnsDestination ? 'overwritten-managed' : 'overwritten-unmanaged', source, destination };
+  if (manifestOwnsDestination) return { status: 'overwritten-managed', source, destination };
+  if (adoptKnownSkill) return { status: 'adopted-managed', source, destination };
+  return { status: 'overwritten-unmanaged', source, destination };
 }
 
-function unmanagedSkillConflicts(selected, sourceRoot, skillsDir, currentManifest) {
+function unmanagedSkillConflicts(selected, sourceRoot, skillsDir, currentManifest, { adoptKnownSkills = false } = {}) {
+  const canAdopt = canAdoptKnownSkill({ manifest: currentManifest, adoptKnownSkills });
   const out = [];
   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]) {
+    if (fs.existsSync(source) && fs.existsSync(destination) && directoryDigest(source) !== directoryDigest(destination) && !currentManifest?.skills?.[name] && !canAdopt) {
       out.push({
         status: 'skipped-unmanaged-different',
         source,
@@ -121,13 +161,30 @@ 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;
 }
 
-export function installSkills(skillsDir, { force = false, skillSet = 'core', allowUnmanagedOverwrite = false } = {}) {
+export function installSkills(skillsDir, {
+  force = false,
+  skillSet = 'core',
+  allowUnmanagedOverwrite = false,
+  adoptKnownSkills = false,
+} = {}) {
   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: {} };
@@ -135,14 +192,21 @@ export function installSkills(skillsDir, { force = false, skillSet = 'core', all
   nextManifest.version = packageVersion() || String(nextManifest.version || '0.0.0');
   nextManifest.updated_at = nowIso();
   nextManifest.skills ||= {};
-  const conflicts = force && !allowUnmanagedOverwrite ? unmanagedSkillConflicts(selected, sourceRoot, skillsDir, currentManifest) : [];
+  const conflicts = force && !allowUnmanagedOverwrite
+    ? 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,
+    adoptKnownSkills,
     manifest: currentManifest,
     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) {
@@ -159,6 +167,7 @@ function buildSyncPlan(options, command) {
     mode: 'sync',
     yes: options.yes,
     force: options.force,
+    adoptKnownSkills: true,
     allowUnmanagedSkillOverwrite: options.allowUnmanagedSkillOverwrite,
     forceSkills: true,
     installMissing: false,

package/docs/ACCEPTANCE_CHECK.md

@@ -34,7 +34,7 @@ Rule modes are documented in `docs/RULES.md`, example profile defaults to adviso
 
 ## Conflict handling
 
-`docs/CONFLICT_RESOLUTION.md` and installer behavior preserve existing repo instructions, skip existing differing profiles/skills by default, make bridge insertion marker-managed and idempotent, and refuse to overwrite non-managed hooks even in Full mode or with `--force`, and refuse unmanaged skill-directory overwrites without `--allow-unmanaged-skill-overwrite`.
+`docs/CONFLICT_RESOLUTION.md` and installer behavior preserve existing repo instructions, skip existing differing profiles/skills by default, make bridge insertion marker-managed and idempotent, refuse to overwrite non-managed hooks even in Full mode or with `--force`, refuse unmanaged skill-directory overwrites without `--allow-unmanaged-skill-overwrite`, and let `sync`/`update` adopt additional known jhste skills into an already managed skills directory.
 
 ## Verification commands
 
@@ -52,3 +52,5 @@ 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`.

package/docs/CLI.md

@@ -95,7 +95,8 @@ Stable contract:
 - only refreshes repo outputs that already look managed by jhste-skills (`.jhste/profile.yaml`, managed bridge markers, or managed hooks);
 - does not bootstrap unmanaged repositories; use `install` or `connect` for first-time setup;
 - preserves non-managed hooks and does not touch source files, CI, `package.json`, or lockfiles;
-- `--force` still applies only to repo-managed outputs such as overwriting an existing managed profile; unmanaged differing skill directories require `--allow-unmanaged-skill-overwrite`.
+- `--force` still applies only to repo-managed outputs such as overwriting an existing managed profile; unmanaged differing skill directories require `--allow-unmanaged-skill-overwrite`;
+- `sync`/`update` may adopt additional known jhste skills into an already managed skills directory and refresh them without the extra overwrite flag.
 
 ## `update`
 
@@ -144,7 +145,7 @@ The JSON output starts with:
   "schema_version": 1,
   "summary": { "error": 0, "warning": 0, "info": 0, "baseline_matched": 0, "suppressed": 0, "failures": 0 },
   "meta": {
-    "tool_version": "0.1.0",
+    "tool_version": "0.1.1",
     "scope": "changed",
     "files_considered": 0,
     "files_scanned": 0,

package/docs/CONFLICT_RESOLUTION.md

@@ -18,7 +18,7 @@ If `.jhste/profile.yaml` exists, default install keeps it. Overwrite requires `-
 
 ## Existing skills
 
-Installed skill directories are tracked in `.jhste-skills-manifest.json` inside the skills directory. If a target skill directory already exists and differs, default install skips it; `--force` can refresh manifest-managed copies, but unmanaged differing directories are refused unless `--allow-unmanaged-skill-overwrite` is also explicit. The manifest stores skill digests, not absolute local paths.
+Installed skill directories are tracked in `.jhste-skills-manifest.json` inside the skills directory. If a target skill directory already exists and differs, default install skips it; `--force` can refresh manifest-managed copies, but unmanaged differing directories are refused unless `--allow-unmanaged-skill-overwrite` is also explicit. During `sync`/`update`, an already managed skills directory may adopt additional known jhste skills into the manifest and refresh them without the extra overwrite flag. The manifest stores skill digests, not absolute local paths.
 
 ## Bridge block
 
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jhste-skills",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Installable engineering guardrails and workflow skills for AI coding agents.",
   "type": "module",
   "license": "MIT",

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/guard-and-hook-scenarios.mjs

@@ -3,6 +3,7 @@ import path from 'node:path';
 import {
   fail,
   hashFile,
+  packageVersion,
   parseJsonOutput,
   run,
   runAny,
@@ -105,10 +106,11 @@ function assertDeepScanReport(report) {
 
 function runGuardContracts(ctx) {
   const { root, repo, report, tmp } = ctx;
+  const version = packageVersion(root);
   const guardJson = run(process.execPath, [path.join(root, 'cli/guard.mjs'), '--repo', repo, '--scope', 'all', '--format', 'json', '--fail-on', 'none'], { cwd: repo }).stdout;
   const guardResult = parseJsonOutput(guardJson, 'guard result');
   if (guardResult.schema_version !== 1) fail('guard JSON schema_version missing');
-  if (guardResult.meta?.tool_version !== '0.1.0') fail('guard JSON meta tool_version missing');
+  if (guardResult.meta?.tool_version !== version) fail('guard JSON meta tool_version missing');
   if (typeof guardResult.meta?.files_considered !== 'number') fail('guard JSON meta files_considered missing');
   for (const [ruleId, message] of [
     ['silent.catch.empty', 'guard did not report empty catch'],
@@ -154,6 +156,7 @@ function assertGuardFailureModes({ root, repo, tmp }) {
 }
 
 function runProfileCommandAndHookContracts({ root, repo, profilePath, packageHashBefore }) {
+  const version = packageVersion(root);
   const fakeOpenAiKey = 'sk-' + 'A'.repeat(24);
   const fakeGithubToken = 'gh' + 'p_' + 'B'.repeat(36);
   const fakeGenericSecret = 'C'.repeat(16);
@@ -191,7 +194,7 @@ function runProfileCommandAndHookContracts({ root, repo, profilePath, packageHas
   const preCommit = path.join(repo, '.git', 'hooks', 'pre-commit');
   const preCommitText = fs.readFileSync(preCommit, 'utf8');
   if (!preCommitText.includes('jhste-skills managed hook start')) fail('managed pre-commit hook missing marker');
-  if (!preCommitText.includes('# jhste-skills version=0.1.0')) fail('managed pre-commit hook missing version comment');
+  if (!preCommitText.includes(`# jhste-skills version=${version}`)) fail('managed pre-commit hook missing version comment');
   if (preCommitText.indexOf("node '") > preCommitText.indexOf('command -v jhste-skills')) fail('managed hook should prefer local CLI before global fallback');
   const fakeBin = path.join(path.dirname(preCommit), 'fake-bin');
   fs.mkdirSync(fakeBin);

package/scripts/smoke/helpers.mjs

@@ -36,6 +36,10 @@ export function hashFile(file) {
   return fs.existsSync(file) ? crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex') : null;
 }
 
+export function packageVersion(root) {
+  return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).version;
+}
+
 export function skillDirs(dir) {
   return fs.readdirSync(dir, { withFileTypes: true })
     .filter((entry) => entry.isDirectory())

package/scripts/smoke/install-scenarios.mjs

@@ -4,6 +4,7 @@ import {
   assertNoInstallSideEffects,
   fail,
   hashFile,
+  packageVersion,
   run,
   runAny,
   skillDirs,
@@ -27,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');
@@ -77,6 +87,7 @@ function runRefusalScenarios({ root, tmp }) {
 
 function runDefaultInstall(ctx) {
   const { root, repo, skillsDir } = ctx;
+  const version = packageVersion(root);
   ctx.packageHashBefore = hashFile(path.join(repo, 'package.json'));
   ctx.lockHashBefore = hashFile(path.join(repo, 'package-lock.json'));
   const started = Date.now();
@@ -98,23 +109,29 @@ function runDefaultInstall(ctx) {
   const defaultPreCommit = path.join(repo, '.git', 'hooks', 'pre-commit');
   if (!fs.existsSync(defaultPreCommit)) fail('install did not create default advisory pre-commit hook');
   if (!fs.readFileSync(defaultPreCommit, 'utf8').includes('mode=advisory')) fail('default pre-commit hook is not advisory');
-  if (!fs.readFileSync(defaultPreCommit, 'utf8').includes('# jhste-skills version=0.1.0')) fail('default pre-commit hook missing version comment');
+  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');
 }
 
 function runUpdateScenarios({ root, repo, skillsDir }) {
+  const version = packageVersion(root);
   const skillPath = path.join(skillsDir, 'jhste-code-quality', 'SKILL.md');
   const sourceSkillPath = path.join(root, 'skills', 'jhste-code-quality', 'SKILL.md');
+  const adoptedSkillName = 'triage';
+  const adoptedSkillPath = path.join(skillsDir, adoptedSkillName, 'SKILL.md');
+  const adoptedSourceSkillPath = path.join(root, 'skills', adoptedSkillName, 'SKILL.md');
   const agentsPath = path.join(repo, 'AGENTS.md');
   const preCommitPath = path.join(repo, '.git', 'hooks', 'pre-commit');
 
   fs.writeFileSync(skillPath, '# stale local copy\n');
+  fs.mkdirSync(path.dirname(adoptedSkillPath), { recursive: true });
+  fs.writeFileSync(adoptedSkillPath, '# unmanaged but known skill copy\n');
 
   const existingAgents = fs.readFileSync(agentsPath, 'utf8');
   const staleAgents = existingAgents.replace(
@@ -136,6 +153,9 @@ run_jhste_skills guard --scope staged --format text --fail-on warning
   if (fs.readFileSync(skillPath, 'utf8') !== fs.readFileSync(sourceSkillPath, 'utf8')) {
     fail('update did not refresh an installed skill back to the current source version');
   }
+  if (fs.readFileSync(adoptedSkillPath, 'utf8') !== fs.readFileSync(adoptedSourceSkillPath, 'utf8')) {
+    fail('update did not adopt and refresh a known jhste skill into an existing managed installation');
+  }
 
   const updatedAgents = fs.readFileSync(agentsPath, 'utf8');
   if (updatedAgents.includes('Old bridge text that should be replaced.')) {
@@ -148,9 +168,31 @@ run_jhste_skills guard --scope staged --format text --fail-on warning
   const updatedPreCommit = fs.readFileSync(preCommitPath, 'utf8');
   if (!updatedPreCommit.includes('mode=blocking')) fail('update did not preserve managed hook mode');
   if (!updatedPreCommit.includes('--fail-on warning')) fail('update did not preserve managed hook fail-on behavior');
-  if (!updatedPreCommit.includes('# jhste-skills version=0.1.0')) fail('update did not refresh hook version comment');
+  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 = 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');
@@ -204,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');
 
@@ -214,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/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"