claude-dev-env 4.2.0 → 7.0.0

package/bin/install.prune.test.mjs

@@ -25,16 +25,43 @@ const RETIRED_SKILL_DIRECTORIES = [
     'post-audit-findings',
     'pr-consistency-audit',
     'bdd-protocol',
+    'hitl',
+    'autoconverge',
+    'pr-cleanup',
+    'pr-name-by-capability',
+    'pr-plain-language-cleanup',
+    'pr-refinement',
+    'pr-shared-extraction',
+    'pr-small-cl',
+    'pr-title-description',
+    'prototype',
+    'rebase',
+    'review-router',
+    'review-tier',
+    'run-claude-dev-env',
+    'session-log',
+    'session-tidy',
+    'source-command-sr-loop',
+    'update',
 ];
 const PERSONAL_SKILL_DIRECTORIES = ['credit-card-picker', 'midjourney-sref'];
-const SHIPPED_SKILL_DIRECTORY = 'autoconverge';
+const SHIPPED_SKILL_DIRECTORY = 'e-code-review';
 const PRUNED_BACKUP_DIRECTORY_NAME = '.claude-dev-env-pruned';
 const SKIP_PRUNE_NOTICE_MARKER = 'Skipping retired-skill and stale-file prune';
 const STALE_SKILL_FILE_RELATIVE_SEGMENTS = ['scripts', 'retired_module.py'];
 const RUNTIME_ARTIFACT_RELATIVE_SEGMENTS = ['scripts', '__pycache__', 'helper.cpython-312.pyc'];
 const SCOPED_GROUP_SKILL_DIRECTORY = 'orchestrator';
-const CORE_REVIEW_GUIDE_SKILL_DIRECTORIES = [
-    'pr-small-cl',
+const CORE_SKILL_DIRECTORIES = [
+    'orchestrator',
+    'orchestrator-refresh',
+    'team-advisor',
+    'grok-spawn',
+    'everything-search',
+    'test-runner',
+    'privacy-hygiene',
+    'issue-tracker',
+    'task-build',
+    'eli5',
 ];
 const PRIOR_RUN_BACKUP_DIRECTORY_NAMES = [
     '2020-01-01T00-00-00-000Z',
@@ -66,6 +93,41 @@ const NESTED_SKILL_DIRECTORY = 'foo';
 const NESTED_SKILL_FILE_SEGMENTS = [NESTED_SKILL_DIRECTORY, 'scripts', 'a.py'];
 const MYPY_INI_FILE_NAME = '.mypy.ini';
 const SKIPPED_RECORD_SUMMARY_MARKER = 'manifest record(s) skipped';
+const RETIRED_PULL_REQUEST_HOOK_RELATIVE_PATHS = [
+    '_gh_pr_author_swap_utils.py',
+    'test__gh_pr_author_swap_utils.py',
+    'blocking/conventional_pr_title_gate.py',
+    'blocking/gh_body_arg_blocker.py',
+    'blocking/gh_pr_author_enforcer.py',
+    'blocking/gh_pr_author_restore.py',
+    'blocking/pr_description_writer_gate.py',
+    'blocking/test_conventional_pr_title_gate.py',
+    'blocking/test_gh_body_arg_blocker.py',
+    'blocking/test_gh_pr_author_enforcer.py',
+    'blocking/test_gh_pr_author_restore.py',
+    'blocking/test_gh_pr_author_swap_utils.py',
+    'blocking/test_pr_description_writer_gate.py',
+    'blocking/test_volatile_path_in_post_blocker.py',
+    'blocking/volatile_path_in_post_blocker.py',
+    'hooks_constants/conventional_pr_title_gate_constants.py',
+    'hooks_constants/gh_pr_author_swap_constants.py',
+    'hooks_constants/pr_description_writer_gate_constants.py',
+    'hooks_constants/volatile_path_in_post_blocker_constants.py',
+    'observability/pr_description_writer_spawn_tracker.py',
+    'observability/test_pr_description_writer_spawn_tracker.py',
+    'session/gh_pr_author_session_cleanup.py',
+    'session/test_gh_pr_author_session_cleanup.py',
+];
+const RETIRED_PULL_REQUEST_REGISTRATION_PATHS = [
+    'blocking/conventional_pr_title_gate.py',
+    'blocking/gh_body_arg_blocker.py',
+    'blocking/gh_pr_author_enforcer.py',
+    'blocking/gh_pr_author_restore.py',
+    'blocking/pr_description_writer_gate.py',
+    'blocking/volatile_path_in_post_blocker.py',
+    'observability/pr_description_writer_spawn_tracker.py',
+    'session/gh_pr_author_session_cleanup.py',
+];
 
 /**
  * Report whether a path under one managed root landed in a run backup.
@@ -658,25 +720,33 @@ test('a scoped --only install leaves retired skills in place because prune runs
     }
 });
 
-test('a full reinstall keeps autoconverge because the package ships it again', () => {
+test('a full reinstall keeps the skill-builder stub and archives its obsolete support files', () => {
     const sandbox = createSandbox();
     try {
-        plantSkillDirectory(sandbox.skillsDirectory, 'autoconverge', true);
-        writeFileSync(join(sandbox.skillsDirectory, 'autoconverge', 'SKILL.md'), 'stale seeded copy\n');
+        const skillName = 'skill-builder';
+        plantSkillDirectory(sandbox.skillsDirectory, skillName, true);
+        const stubPath = join(sandbox.skillsDirectory, skillName, 'SKILL.md');
+        const obsoleteReferencePath = join(sandbox.skillsDirectory, skillName, 'references', 'retired.md');
+        writeFileWithParents(obsoleteReferencePath, 'obsolete skill-builder guidance\n');
+        writeFileSync(sandbox.manifestPath, JSON.stringify({
+            package: 'claude-dev-env',
+            version: '0.0.0',
+            installedAt: new Date().toISOString(),
+            files: [stubPath, obsoleteReferencePath],
+            skills: [skillName],
+        }, null, 2) + '\n');
 
         const installerOutput = runInstaller(sandbox.homeDirectory, []);
 
+        assert.equal(installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER), false);
+        assert.equal(existsSync(stubPath), true, 'the requested stub stays installed');
+        assert.match(readFileSync(stubPath, 'utf8'), /TODO: Rework to follow pstack philosophy\./);
+        assert.ok(readManifest(sandbox.manifestPath).skills.includes(skillName));
+        assert.equal(existsSync(obsoleteReferencePath), false);
         assert.equal(
-            installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
-            false,
-            'the full install runs the prune rather than skipping it',
-        );
-        const restoredSkillPath = join(sandbox.skillsDirectory, 'autoconverge', 'SKILL.md');
-        assert.equal(existsSync(restoredSkillPath), true, 'autoconverge survives and is reinstalled');
-        assert.notEqual(
-            readFileSync(restoredSkillPath, 'utf8'),
-            'stale seeded copy\n',
-            'the shipped autoconverge overwrites the stale seeded copy',
+            prunedSkillBackupContains(sandbox.claudeDirectory, join(skillName, 'references', 'retired.md')),
+            true,
+            'old implementation files move to the recovery backup while the stub stays',
         );
     } finally {
         rmSync(sandbox.homeDirectory, { recursive: true, force: true });
@@ -704,20 +774,24 @@ test('a scoped --only install records the skill names it installed', () => {
     }
 });
 
-test('a scoped core install ships the canonical review guide skills', () => {
+test('a fresh scoped core install ships active skills and omits retired skills', () => {
     const sandbox = createSandbox();
     try {
         runInstaller(sandbox.homeDirectory, ['--only', 'core']);
 
-        const missingGuideSkillNames = CORE_REVIEW_GUIDE_SKILL_DIRECTORIES.filter(
+        const missingSkillNames = CORE_SKILL_DIRECTORIES.filter(
             eachSkillName => !existsSync(join(sandbox.skillsDirectory, eachSkillName, 'SKILL.md')),
         );
-        assert.deepEqual(missingGuideSkillNames, []);
+        assert.deepEqual(missingSkillNames, []);
 
         const recordedSkillNames = new Set(readManifest(sandbox.manifestPath).skills);
-        for (const eachSkillName of CORE_REVIEW_GUIDE_SKILL_DIRECTORIES) {
+        for (const eachSkillName of CORE_SKILL_DIRECTORIES) {
             assert.equal(recordedSkillNames.has(eachSkillName), true);
         }
+        for (const eachSkillName of RETIRED_SKILL_DIRECTORIES) {
+            assert.equal(existsSync(join(sandbox.skillsDirectory, eachSkillName)), false);
+            assert.equal(recordedSkillNames.has(eachSkillName), false);
+        }
     } finally {
         rmSync(sandbox.homeDirectory, { recursive: true, force: true });
     }
@@ -1113,6 +1187,61 @@ test('a full reinstall removes the retired Everything path rewriter and keeps a
     }
 });
 
+test('a full reinstall removes retired pull request hooks and preserves foreign and recovery state', () => {
+    const sandbox = createSandbox();
+    try {
+        runInstaller(sandbox.homeDirectory, []);
+        const retiredPaths = RETIRED_PULL_REQUEST_HOOK_RELATIVE_PATHS.map(relativePath => (
+            join(sandbox.claudeDirectory, HOOKS_DIRECTORY_NAME, ...relativePath.split('/'))
+        ));
+        for (const retiredPath of retiredPaths) {
+            writeFileWithParents(retiredPath, 'an earlier install managed this file\n');
+        }
+        appendManifestFiles(sandbox.manifestPath, retiredPaths);
+        const foreignHookPath = join(
+            sandbox.claudeDirectory, HOOKS_DIRECTORY_NAME, 'blocking', 'foreign_pr_hook.py',
+        );
+        const foreignHookBytes = Buffer.from('a user hook the installer never wrote\n', 'utf8');
+        writeFileWithParents(foreignHookPath, foreignHookBytes);
+        const recoveryStatePath = join(
+            sandbox.homeDirectory, 'pending', 'gh_pr_author_swap_session-a.json',
+        );
+        const recoveryStateBytes = Buffer.from('{"original_account":"prior"}\n', 'utf8');
+        writeFileWithParents(recoveryStatePath, recoveryStateBytes);
+        const settings = readSettings(sandbox.claudeDirectory);
+        settings.hooks.PreToolUse.push({
+            matcher: 'Bash',
+            hooks: [
+                ...RETIRED_PULL_REQUEST_REGISTRATION_PATHS.map(relativePath => ({
+                    type: 'command',
+                    command: `python3 "${join(sandbox.claudeDirectory, HOOKS_DIRECTORY_NAME, ...relativePath.split('/')).replace(/\\/g, '/')}"`,
+                })),
+                { type: 'command', command: `python3 "${foreignHookPath.replace(/\\/g, '/')}"` },
+            ],
+        });
+        writeFileSync(
+            join(sandbox.claudeDirectory, SETTINGS_FILE_NAME),
+            JSON.stringify(settings, null, 4) + '\n',
+        );
+
+        runInstaller(sandbox.homeDirectory, []);
+
+        const freshManifest = readManifest(sandbox.manifestPath);
+        const allCommands = allHookCommands(readSettings(sandbox.claudeDirectory));
+        for (const retiredPath of retiredPaths) {
+            assert.equal(existsSync(retiredPath), false, `${retiredPath} leaves installed hooks`);
+            assert.equal(freshManifest.files.includes(retiredPath), false);
+        }
+        for (const relativePath of RETIRED_PULL_REQUEST_REGISTRATION_PATHS) {
+            assert.ok(allCommands.every(command => !command.includes(relativePath)));
+        }
+        assert.deepEqual(readFileSync(foreignHookPath), foreignHookBytes);
+        assert.deepEqual(readFileSync(recoveryStatePath), recoveryStateBytes);
+    } finally {
+        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
+    }
+});
+
 test('a full reinstall removes a retired hook entry under an event type the current config leaves out', () => {
     const sandbox = createSandbox();
     try {

package/bin/install.pstack-plugin.test.mjs

@@ -0,0 +1,114 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import {
+    mkdtempSync,
+    mkdirSync,
+    writeFileSync,
+    readFileSync,
+    existsSync,
+    rmSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { resolveInstallRoot } from './resolve-install-root.mjs';
+import { PSTACK_PLUGIN_MANIFEST_RELATIVE_PATH } from '../scripts/refresh_pstack_plugin_skills.mjs';
+
+const THIS_DIRECTORY = dirname(fileURLToPath(import.meta.url));
+const INSTALLER_PATH = join(THIS_DIRECTORY, 'install.mjs');
+const PACKAGE_DIRECTORY = dirname(THIS_DIRECTORY);
+
+function runInstaller(homeDirectory, extraArguments) {
+    return execFileSync('node', [INSTALLER_PATH, ...extraArguments], {
+        cwd: PACKAGE_DIRECTORY,
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            HOME: homeDirectory,
+            USERPROFILE: homeDirectory,
+            CODEX_HOME: join(homeDirectory, '.codex'),
+            CLAUDE_CONFIG_DIR: join(homeDirectory, '.claude'),
+            GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+        },
+    });
+}
+
+function seedPstackSkills(agentsHome, skillNames) {
+    const pluginRoot = join(agentsHome, 'skills', 'pstack');
+    for (const eachSkillName of skillNames) {
+        const skillDirectory = join(pluginRoot, eachSkillName);
+        mkdirSync(skillDirectory, { recursive: true });
+        writeFileSync(join(skillDirectory, 'SKILL.md'), '---\nname: ' + eachSkillName + '\n---\n');
+    }
+    return pluginRoot;
+}
+
+function withTemporaryHome(runAssertions) {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-pstack-plugin-'));
+    try {
+        const resolution = resolveInstallRoot({
+            homeDirectory,
+            environment: {},
+            explicitTarget: null,
+        });
+        runAssertions(homeDirectory, resolution);
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+}
+
+test('a pstack folder the user installed gains a plugin manifest', () => {
+    withTemporaryHome((homeDirectory, resolution) => {
+        const pluginRoot = seedPstackSkills(resolution.agentsHome, ['how', 'why']);
+
+        runInstaller(homeDirectory, ['--only', 'core']);
+
+        const manifestPath = join(pluginRoot, PSTACK_PLUGIN_MANIFEST_RELATIVE_PATH);
+        assert.equal(existsSync(manifestPath), true);
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        assert.equal(manifest.name, 'pstack');
+        assert.deepEqual(manifest.skills, ['./how', './why']);
+    });
+});
+
+test('a second install leaves an unchanged manifest byte for byte', () => {
+    withTemporaryHome((homeDirectory, resolution) => {
+        const pluginRoot = seedPstackSkills(resolution.agentsHome, ['how']);
+
+        runInstaller(homeDirectory, ['--only', 'core']);
+        const manifestPath = join(pluginRoot, PSTACK_PLUGIN_MANIFEST_RELATIVE_PATH);
+        const afterFirstInstall = readFileSync(manifestPath, 'utf8');
+        runInstaller(homeDirectory, ['--only', 'core']);
+
+        assert.equal(readFileSync(manifestPath, 'utf8'), afterFirstInstall);
+    });
+});
+
+test('a later install lists a skill a pstack update added', () => {
+    withTemporaryHome((homeDirectory, resolution) => {
+        const pluginRoot = seedPstackSkills(resolution.agentsHome, ['how']);
+        runInstaller(homeDirectory, ['--only', 'core']);
+
+        seedPstackSkills(resolution.agentsHome, ['why']);
+        runInstaller(homeDirectory, ['--only', 'core']);
+
+        const manifestPath = join(pluginRoot, PSTACK_PLUGIN_MANIFEST_RELATIVE_PATH);
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        assert.deepEqual(manifest.skills, ['./how', './why']);
+    });
+});
+
+test('an install with no pstack folder writes no manifest and does not fail', () => {
+    withTemporaryHome((homeDirectory, resolution) => {
+        runInstaller(homeDirectory, ['--only', 'core']);
+
+        const manifestPath = join(
+            resolution.agentsHome,
+            'skills',
+            'pstack',
+            PSTACK_PLUGIN_MANIFEST_RELATIVE_PATH,
+        );
+        assert.equal(existsSync(manifestPath), false);
+    });
+});

package/bin/install.test.mjs

@@ -43,6 +43,7 @@ import {
     retiredManagedHookRelativePaths,
     pruneRetiredHookEntriesFromSettings,
     retainNewestRunBackupOnly,
+    refreshInstalledPstackPluginManifest,
 } from './install.mjs';
 import { EVER_SHIPPED_SKILL_NAMES } from './ever-shipped-skills.mjs';
 import {
@@ -228,6 +229,11 @@ test('CORE_SKILLS ships ELI5 as the leaf presentation skill', () => {
     assert.equal(INSTALL_GROUPS.core.skills.includes('eli5'), true);
 });
 
+test('CORE_SKILLS ships test-runner for explicit Django and Playwright readiness checks', () => {
+    assert.ok(CORE_SKILLS.includes('test-runner'));
+    assert.equal(INSTALL_GROUPS.core.skills.includes('test-runner'), true);
+});
+
 
 test('EVER_SHIPPED_SKILL_NAMES retains imagegen so reinstall prunes the retired skill', () => {
     assert.ok(
@@ -1246,7 +1252,7 @@ const OLD_FOLDED_HOOKS_SETTINGS = {
 
 
 test('FOLDED_HOOK_RELATIVE_PATHS contains folded hooks plus retired entries', () => {
-    assert.equal(FOLDED_HOOK_RELATIVE_PATHS.size, 16);
+    assert.equal(FOLDED_HOOK_RELATIVE_PATHS.size, 21);
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/write_existing_file_blocker.py'));
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/code_rules_enforcer.py'));
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/pytest_testpaths_orphan_blocker.py'));
@@ -1256,16 +1262,22 @@ test('FOLDED_HOOK_RELATIVE_PATHS contains folded hooks plus retired entries', ()
 
 
 test('retired hook registrations stay managed so reinstall removes them', () => {
-    const retiredPath = 'session/untracked_repo_detector.py';
+    const retiredPaths = new Set([
+        'session/untracked_repo_detector.py',
+        'session/gh_pr_author_session_cleanup.py',
+        'observability/pr_description_writer_spawn_tracker.py',
+    ]);
     const shippedHooks = JSON.parse(
         readFileSync(new URL('../hooks/hooks.json', import.meta.url), 'utf8')
     );
     const shippedCommands = Object.values(shippedHooks.hooks).flatMap(matcherGroups => (
         matcherGroups.flatMap(matcherGroup => matcherGroup.hooks.map(hook => hook.command))
     ));
-    assert.deepEqual(RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS, new Set([retiredPath]));
-    assert.ok(managedHookScriptRelativePaths({ hooks: {} }).has(retiredPath));
-    assert.ok(shippedCommands.every(command => !command.includes(retiredPath)));
+    assert.deepEqual(RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS, retiredPaths);
+    for (const retiredPath of retiredPaths) {
+        assert.ok(managedHookScriptRelativePaths({ hooks: {} }).has(retiredPath));
+        assert.ok(shippedCommands.every(command => !command.includes(retiredPath)));
+    }
 });
 
 
@@ -1288,6 +1300,11 @@ test('FOLDED_HOOK_RELATIVE_PATHS lists every hook the PreToolUse dispatcher host
     ];
     const retiredHooks = [
         'blocking/md_to_html_blocker.py',
+        'blocking/gh_body_arg_blocker.py',
+        'blocking/volatile_path_in_post_blocker.py',
+        'blocking/conventional_pr_title_gate.py',
+        'blocking/gh_pr_author_enforcer.py',
+        'blocking/pr_description_writer_gate.py',
         'session/untracked_repo_detector.py',
     ];
     for (const hostedPath of dispatcherHostedHooks) {
@@ -1480,12 +1497,13 @@ const OLD_POST_FOLDED_HOOKS_SETTINGS = {
 };
 
 
-test('POST_FOLDED_HOOK_RELATIVE_PATHS contains the after-write hooks and the retired md_to_html_companion', () => {
-    assert.equal(POST_FOLDED_HOOK_RELATIVE_PATHS.size, 4);
+test('POST_FOLDED_HOOK_RELATIVE_PATHS contains hosted and retired post-tool hooks', () => {
+    assert.equal(POST_FOLDED_HOOK_RELATIVE_PATHS.size, 5);
     assert.ok(POST_FOLDED_HOOK_RELATIVE_PATHS.has('validation/mypy_validator.py'));
     assert.ok(POST_FOLDED_HOOK_RELATIVE_PATHS.has('workflow/auto_formatter.py'));
     assert.ok(POST_FOLDED_HOOK_RELATIVE_PATHS.has('workflow/doc_gist_auto_publish.py'));
     assert.ok(POST_FOLDED_HOOK_RELATIVE_PATHS.has('workflow/md_to_html_companion.py'));
+    assert.ok(POST_FOLDED_HOOK_RELATIVE_PATHS.has('blocking/gh_pr_author_restore.py'));
 });
 
 
@@ -2524,3 +2542,39 @@ test('pruneStaleInstalledFiles leaves the run backup root standing when the rena
         rmSync(sandbox.root, { recursive: true, force: true });
     }
 });
+
+test('the pstack step writes a manifest for a skills root that carries pstack', () => {
+    const skillsRoot = mkdtempSync(join(tmpdir(), 'cdev-pstack-step-'));
+    try {
+        const skillDirectory = join(skillsRoot, 'pstack', 'how');
+        mkdirSync(skillDirectory, { recursive: true });
+        writeFileSync(join(skillDirectory, 'SKILL.md'), '---\nname: how\n---\n');
+
+        const manifestPath = refreshInstalledPstackPluginManifest(skillsRoot);
+
+        assert.equal(
+            manifestPath,
+            join(skillsRoot, 'pstack', '.claude-plugin', 'plugin.json'),
+            'the step reports the manifest it wrote so the run records the path',
+        );
+        const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        assert.deepEqual(manifest.skills, ['./how']);
+        assert.equal(
+            refreshInstalledPstackPluginManifest(skillsRoot),
+            null,
+            'a second run writes nothing and reports no path',
+        );
+    } finally {
+        rmSync(skillsRoot, { recursive: true, force: true });
+    }
+});
+
+test('the pstack step reports no path for a skills root without pstack', () => {
+    const skillsRoot = mkdtempSync(join(tmpdir(), 'cdev-pstack-absent-'));
+    try {
+        assert.equal(refreshInstalledPstackPluginManifest(skillsRoot), null);
+        assert.equal(existsSync(join(skillsRoot, 'pstack')), false);
+    } finally {
+        rmSync(skillsRoot, { recursive: true, force: true });
+    }
+});

package/bin/refresh-pstack-plugin-skills.test.mjs

@@ -0,0 +1,211 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import {
+    mkdtempSync,
+    mkdirSync,
+    readFileSync,
+    rmSync,
+    symlinkSync,
+    writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import {
+    PSTACK_PLUGIN_MANIFEST_RELATIVE_PATH,
+    findPstackSkillDirectoryNames,
+    refreshPstackPluginManifest,
+} from '../scripts/refresh_pstack_plugin_skills.mjs';
+
+function buildPluginRoot(homeDirectory, skillNames, manifest) {
+    const pluginRoot = join(homeDirectory, 'pstack');
+    for (const eachSkillName of skillNames) {
+        const skillDirectory = join(pluginRoot, eachSkillName);
+        mkdirSync(skillDirectory, { recursive: true });
+        writeFileSync(join(skillDirectory, 'SKILL.md'), '---\n');
+    }
+    const manifestPath = join(pluginRoot, PSTACK_PLUGIN_MANIFEST_RELATIVE_PATH);
+    mkdirSync(join(pluginRoot, '.claude-plugin'), { recursive: true });
+    if (manifest !== null) {
+        writeFileSync(manifestPath, JSON.stringify(manifest));
+    }
+    return pluginRoot;
+}
+
+function withTemporaryHome(runAssertions) {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-pstack-manifest-'));
+    try {
+        runAssertions(homeDirectory);
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+}
+
+test('finds only sub-folders that hold a skill entry file', () => {
+    withTemporaryHome((homeDirectory) => {
+        const pluginRoot = buildPluginRoot(homeDirectory, ['how', 'why'], { skills: [] });
+        mkdirSync(join(pluginRoot, 'docs'), { recursive: true });
+        writeFileSync(join(pluginRoot, '.claude-plugin', 'SKILL.md'), '---\n');
+
+        assert.deepEqual(findPstackSkillDirectoryNames(pluginRoot), ['how', 'why']);
+    });
+});
+
+test('writes a manifest when the plugin folder has none', () => {
+    withTemporaryHome((homeDirectory) => {
+        const pluginRoot = buildPluginRoot(homeDirectory, ['how'], null);
+
+        const outcome = refreshPstackPluginManifest(pluginRoot);
+
+        assert.equal(outcome.didWrite, true);
+        const manifestPath = join(pluginRoot, PSTACK_PLUGIN_MANIFEST_RELATIVE_PATH);
+        const written = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        assert.equal(written.name, 'pstack');
+        assert.deepEqual(written.skills, ['./how']);
+    });
+});
+
+test('adds a skill folder the manifest does not list', () => {
+    withTemporaryHome((homeDirectory) => {
+        const pluginRoot = buildPluginRoot(homeDirectory, ['how', 'why'], {
+            name: 'pstack',
+            skills: ['./how'],
+        });
+
+        const outcome = refreshPstackPluginManifest(pluginRoot);
+
+        assert.equal(outcome.didWrite, true);
+        assert.deepEqual(outcome.previousSkillPaths, ['./how']);
+        assert.deepEqual(outcome.currentSkillPaths, ['./how', './why']);
+    });
+});
+
+test('leaves the manifest byte for byte when nothing changed', () => {
+    withTemporaryHome((homeDirectory) => {
+        const pluginRoot = buildPluginRoot(homeDirectory, ['how'], {
+            name: 'pstack',
+            skills: ['./how'],
+        });
+        const manifestPath = join(pluginRoot, PSTACK_PLUGIN_MANIFEST_RELATIVE_PATH);
+        writeFileSync(manifestPath, JSON.stringify({ name: 'pstack', skills: ['./how'] }));
+        const before = readFileSync(manifestPath, 'utf8');
+
+        const outcome = refreshPstackPluginManifest(pluginRoot);
+
+        assert.equal(outcome.didWrite, false);
+        assert.equal(readFileSync(manifestPath, 'utf8'), before);
+    });
+});
+
+test('reads a string skills value as a one-entry list', () => {
+    withTemporaryHome((homeDirectory) => {
+        const pluginRoot = buildPluginRoot(homeDirectory, ['how'], {
+            name: 'pstack',
+            skills: './',
+        });
+
+        const outcome = refreshPstackPluginManifest(pluginRoot);
+
+        assert.deepEqual(outcome.previousSkillPaths, ['./']);
+        assert.deepEqual(outcome.currentSkillPaths, ['./how']);
+    });
+});
+
+test('keeps manifest fields the refresher does not own', () => {
+    withTemporaryHome((homeDirectory) => {
+        const pluginRoot = buildPluginRoot(homeDirectory, ['how'], {
+            name: 'pstack',
+            version: '9.9.9',
+            description: 'a description the user edited',
+            skills: [],
+        });
+
+        refreshPstackPluginManifest(pluginRoot);
+
+        const manifestPath = join(pluginRoot, PSTACK_PLUGIN_MANIFEST_RELATIVE_PATH);
+        const written = JSON.parse(readFileSync(manifestPath, 'utf8'));
+        assert.equal(written.version, '9.9.9');
+        assert.equal(written.description, 'a description the user edited');
+    });
+});
+
+test('refuses a folder that is itself one skill', () => {
+    withTemporaryHome((homeDirectory) => {
+        const pluginRoot = buildPluginRoot(homeDirectory, ['how'], null);
+        writeFileSync(join(pluginRoot, 'SKILL.md'), '---\n');
+
+        const outcome = refreshPstackPluginManifest(pluginRoot);
+
+        assert.equal(outcome.didWrite, false);
+        assert.equal(outcome.reason, 'plugin root is itself a skill');
+    });
+});
+
+test('running the file directly reports what it did', () => {
+    withTemporaryHome((homeDirectory) => {
+        const pluginRoot = buildPluginRoot(homeDirectory, ['how'], null);
+        const modulePath = join(
+            dirname(dirname(fileURLToPath(import.meta.url))),
+            'scripts',
+            'refresh_pstack_plugin_skills.mjs',
+        );
+
+        const firstRun = execFileSync('node', [modulePath, pluginRoot], { encoding: 'utf8' });
+        const secondRun = execFileSync('node', [modulePath, pluginRoot], { encoding: 'utf8' });
+
+        assert.match(firstRun, /Updated\. 1 skills listed\./);
+        assert.match(secondRun, /No change\. 1 skills listed\./);
+    });
+});
+
+test('running the file through a directory link still reports what it did', () => {
+    withTemporaryHome((homeDirectory) => {
+        const pluginRoot = buildPluginRoot(homeDirectory, ['how'], null);
+        const scriptsDirectory = join(
+            dirname(dirname(fileURLToPath(import.meta.url))),
+            'scripts',
+        );
+        const linkedScriptsDirectory = join(homeDirectory, 'linked-scripts');
+        symlinkSync(scriptsDirectory, linkedScriptsDirectory, 'junction');
+        const linkedModulePath = join(linkedScriptsDirectory, 'refresh_pstack_plugin_skills.mjs');
+
+        const output = execFileSync('node', [linkedModulePath, pluginRoot], { encoding: 'utf8' });
+
+        assert.match(output, /Updated\. 1 skills listed\./);
+    });
+});
+
+test('with no folder argument it follows CLAUDE_CONFIG_DIR', () => {
+    withTemporaryHome((homeDirectory) => {
+        const claudeConfigDirectory = join(homeDirectory, 'profile', '.claude');
+        const pluginRoot = join(claudeConfigDirectory, 'skills', 'pstack');
+        mkdirSync(join(pluginRoot, 'how'), { recursive: true });
+        writeFileSync(join(pluginRoot, 'how', 'SKILL.md'), '---\n');
+        const modulePath = join(
+            dirname(dirname(fileURLToPath(import.meta.url))),
+            'scripts',
+            'refresh_pstack_plugin_skills.mjs',
+        );
+
+        const output = execFileSync('node', [modulePath], {
+            encoding: 'utf8',
+            env: { ...process.env, CLAUDE_CONFIG_DIR: claudeConfigDirectory },
+        });
+
+        assert.match(output, /Updated\. 1 skills listed\./);
+        const manifestPath = join(pluginRoot, PSTACK_PLUGIN_MANIFEST_RELATIVE_PATH);
+        assert.deepEqual(JSON.parse(readFileSync(manifestPath, 'utf8')).skills, ['./how']);
+    });
+});
+
+test('refuses a folder that holds no skills', () => {
+    withTemporaryHome((homeDirectory) => {
+        const pluginRoot = buildPluginRoot(homeDirectory, [], null);
+
+        const outcome = refreshPstackPluginManifest(pluginRoot);
+
+        assert.equal(outcome.didWrite, false);
+        assert.equal(outcome.reason, 'plugin root holds no skills');
+    });
+});