jhste-skills 0.1.0 → 0.1.1

package/README.md

@@ -252,3 +252,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.

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

@@ -68,7 +68,17 @@ 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 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 +101,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 +113,20 @@ 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 (!currentManifest?.skills?.[name] && !canAdopt) {
       out.push({
         status: 'skipped-unmanaged-different',
         source,
@@ -124,7 +138,12 @@ function unmanagedSkillConflicts(selected, sourceRoot, skillsDir, currentManifes
   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);
@@ -135,11 +154,14 @@ 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 results = selected.map((name) => copyManagedSkill(path.join(sourceRoot, name), path.join(skillsDir, name), name, {
     force,
     allowUnmanagedOverwrite,
+    adoptKnownSkills,
     manifest: currentManifest,
     nextManifest,
   }));

package/cli/sync-core.mjs

@@ -159,6 +159,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
 

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
 

package/package.json

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

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,
@@ -77,6 +78,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,7 +100,7 @@ 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'));
@@ -109,12 +111,18 @@ function runDefaultInstall(ctx) {
 }
 
 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 +144,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 +159,12 @@ 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 = JSON.parse(fs.readFileSync(path.join(skillsDir, '.jhste-skills-manifest.json'), 'utf8'));
+  if (!managedManifest.skills?.[adoptedSkillName]?.digest) fail('update did not record adopted known skill in manifest');
+
   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');