@skilly-hand/skilly-hand 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -16,6 +16,40 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.17.0] - 2026-04-08
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.17.0)
+
+### Added
+- Added sandbox harness and matrix integration tests (`scripts/test-in-sandbox.mjs`, `tests/sandbox-harness.test.js`, `tests/sandbox-matrix.test.js`) and wired them into the root test pipeline.
+- Added required `review-rangers` final-gate guidance to the spec-driven-development verify flow and validation checklist.
+
+### Changed
+- Updated installer reconciliation logic to remove stale managed targets when agent selection narrows, while preserving/restoring backups for retained targets.
+- Updated backup behavior to skip backup creation for files already marked as managed content.
+- Updated root `npm test` to run sandbox integration verification after the node test suite.
+
+### Fixed
+- Fixed uninstall and re-install behavior for narrowed agent selections by restoring original files and cleaning obsolete managed artifacts.
+
+### Removed
+- _None._
+
+## [0.16.1] - 2026-04-08
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.16.1)
+
+### Added
+- Added a Mandatory Skill Gate section to generated agent instruction files to enforce optimizer sequencing across interactions.
+
+### Changed
+- Updated routing guidance to apply mandatory-gate precedence before task-specific skill chains.
+- Synced catalog markdown rendering so generated AGENTS output includes the Mandatory Skill Gate and precedence guidance.
+
+### Fixed
+- Updated install and self-sync test coverage to assert Mandatory Skill Gate propagation across managed instruction targets.
+
+### Removed
+- _None._
+
 ## [0.16.0] - 2026-04-07
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.16.0)
 

package/catalog/skills/spec-driven-development/SKILL.md

@@ -22,7 +22,7 @@ Do not use this skill for:
 1. Define the spec in `.sdd/active/<feature-name>/spec.md`.
 2. Review and refine scope, constraints, and tasks.
 3. Execute one small task at a time.
-4. Verify each task and the end-to-end outcome.
+4. Verify each task and the end-to-end outcome, ending with a required `review-rangers` final gate.
 5. Archive to `.sdd/archive/` when complete.
 
 Recommended task size:

package/catalog/skills/spec-driven-development/agents/orchestrate.md

@@ -14,7 +14,7 @@ Coordinate planning, implementation, and verification through explicit checkpoin
 1. PLAN: Produce or update the spec.
 2. REVIEW CHECKPOINT: Confirm the plan is approved.
 3. APPLY: Execute agreed task batch.
-4. VERIFY CHECKPOINT: Validate outputs against the spec.
+4. VERIFY CHECKPOINT: Validate outputs against the spec and run the required final `review-rangers` gate.
 5. REPEAT: Continue by phase or task batch.
 6. ARCHIVE: Move completed work from `.sdd/active/` to `.sdd/archive/`.
 

package/catalog/skills/spec-driven-development/agents/verify.md

@@ -15,7 +15,15 @@ Validate that implementation matches the approved spec and passes quality checks
 2. Run task-level verification evidence checks.
 3. Run feature-level validation commands.
 4. Confirm constraints (`MUST`, `MUST NOT`) were respected.
-5. Report pass/fail per area with concrete evidence.
+5. Run a final structured `review-rangers` pass over the full change set.
+6. Report pass/fail per area with concrete evidence.
+
+### Required Final Gate (`review-rangers`)
+
+- Validate selected agent targets vs actual instruction files/symlinks written.
+- Validate stale managed target cleanup after re-install/reselection.
+- Validate backup and restore safety (including uninstall restore behavior).
+- Any unresolved `review-rangers` blocker keeps verification in failed state.
 
 ## Quality Bar
 

package/catalog/skills/spec-driven-development/assets/validation-checklist.md

@@ -28,5 +28,6 @@ Use this checklist before implementation and again before archive.
 - [ ] All planned tasks are complete.
 - [ ] Feature-level validation passes.
 - [ ] Constraints were respected.
+- [ ] Final `review-rangers` gate completed with no unresolved blockers.
 - [ ] No unintended scope creep.
 - [ ] Work is moved from `.sdd/active/` to `.sdd/archive/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "publishConfig": {
@@ -28,7 +28,7 @@
     "catalog:check": "node ./scripts/check-catalog.mjs",
     "catalog:sync": "node ./scripts/sync-catalog-readme.mjs",
     "agentic:self:sync": "node ./scripts/sync-self-agentic.mjs",
-    "test": "node --test tests/*.test.js",
+    "test": "node --test tests/*.test.js && node ./scripts/test-in-sandbox.mjs",
     "security:check": "node ./scripts/security-check.mjs",
     "verify:packlist": "node ./scripts/verify-packlist.mjs",
     "verify:versions": "node ./scripts/verify-versions.mjs",

package/packages/catalog/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/catalog",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "private": true,
   "type": "module"
 }

package/packages/catalog/src/index.js

@@ -118,9 +118,22 @@ export function renderAgentsMarkdown({ skills, detections, generatedAt, projectN
   }
 
   lines.push(
+    "",
+    "### Mandatory Skill Gate (Must Use / Must Read)",
+    "",
+    "This gate has global precedence and applies to every user interaction across all supported agent conventions/files.",
+    "",
+    "1. Always run `token-optimizer` first to classify complexity and set the minimum viable reasoning depth.",
+    "2. Always run `output-optimizer` immediately after `token-optimizer` for response-shape control.",
+    "3. `output-optimizer` mode policy:",
+    "   - Default: select a random canonical mode for each new interaction.",
+    "   - Override: if user explicitly requests a mode (for example `mode: step-brief`), that explicit mode wins.",
+    "   - Persistence: keep the explicitly requested mode active until the user asks for a different mode.",
     "",
     "### Task Routing",
     "",
+    "**Mandatory-gate precedence:** apply the mandatory optimizer gate before task-routing chains below.",
+    "",
     "**SDD-first policy:** for feature delivery, bug fixes, or any multi-step implementation, start with `spec-driven-development` unless the task is clearly trivial and one-step.",
     "",
     "| Task Type | Recommended Skill Chain |",

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/cli",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "private": true,
   "type": "module",
   "bin": {

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/core",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "private": true,
   "type": "module"
 }

package/packages/core/src/index.js

@@ -175,7 +175,11 @@ async function ensureManagedTextFile(targetPath, content, backupsDir, lockData)
       return;
     }
 
-    await backupPathIfNeeded(targetPath, backupsDir, lockData);
+    // Do not back up previously managed content; backups are for restoring
+    // user-authored files replaced by managed files.
+    if (!current.includes(MANAGED_MARKER)) {
+      await backupPathIfNeeded(targetPath, backupsDir, lockData);
+    }
   }
 
   await mkdir(path.dirname(targetPath), { recursive: true });
@@ -230,6 +234,69 @@ function buildInstallTargets(selectedAgents) {
   };
 }
 
+async function reconcileManagedTargets({
+  previousLock,
+  selectedInstructionTargets,
+  selectedSkillTargets,
+  lockData
+}) {
+  if (!previousLock) {
+    return;
+  }
+
+  const selectedInstructions = new Set(selectedInstructionTargets);
+  const selectedSkills = new Set(selectedSkillTargets);
+  const selectedTargets = new Set([...selectedInstructions, ...selectedSkills]);
+  const previousBackups = previousLock.backups || {};
+
+  for (const [targetPath, backupPath] of Object.entries(previousBackups)) {
+    if (!selectedTargets.has(targetPath)) {
+      continue;
+    }
+    if (await exists(backupPath)) {
+      lockData.backups[targetPath] = backupPath;
+    }
+  }
+
+  for (const symlinkPath of previousLock.managedSymlinks || []) {
+    if (selectedSkills.has(symlinkPath)) {
+      continue;
+    }
+
+    if (await exists(symlinkPath)) {
+      await rm(symlinkPath, { recursive: true, force: true });
+    }
+
+    const backupPath = previousBackups[symlinkPath];
+    if (backupPath && await exists(backupPath)) {
+      await mkdir(path.dirname(symlinkPath), { recursive: true });
+      await cp(backupPath, symlinkPath, { recursive: true, force: true });
+    }
+  }
+
+  for (const filePath of previousLock.managedFiles || []) {
+    if (selectedInstructions.has(filePath)) {
+      continue;
+    }
+
+    const backupPath = previousBackups[filePath];
+    if (backupPath && await exists(backupPath)) {
+      await mkdir(path.dirname(filePath), { recursive: true });
+      await cp(backupPath, filePath, { recursive: true, force: true });
+      continue;
+    }
+
+    if (!(await exists(filePath))) {
+      continue;
+    }
+
+    const content = await readFile(filePath, "utf8");
+    if (content.includes(MANAGED_MARKER)) {
+      await rm(filePath, { force: true });
+    }
+  }
+}
+
 export async function installProject({
   cwd,
   agents,
@@ -259,6 +326,7 @@ export async function installProject({
   const targetCatalogDir = path.join(installRoot, "catalog");
   const backupsDir = path.join(installRoot, "backups");
   const lockPath = path.join(installRoot, "manifest.lock.json");
+  const previousLock = await exists(lockPath) ? await readJson(lockPath) : null;
   const lockData = {
     version: 1,
     generatedAt: plan.generatedAt,
@@ -289,15 +357,24 @@ export async function installProject({
   await writeFile(path.join(installRoot, "AGENTS.md"), agentsMarkdown, "utf8");
 
   const { instructionTargets, skillTargets } = buildInstallTargets(selectedAgents);
+  const absoluteInstructionTargets = instructionTargets.map((pathParts) => path.join(cwd, ...pathParts));
+  const absoluteSkillTargets = skillTargets.map((pathParts) => path.join(cwd, ...pathParts));
+
+  await reconcileManagedTargets({
+    previousLock,
+    selectedInstructionTargets: absoluteInstructionTargets,
+    selectedSkillTargets: absoluteSkillTargets,
+    lockData
+  });
 
-  for (const pathParts of instructionTargets) {
-    await ensureManagedTextFile(path.join(cwd, ...pathParts), agentsMarkdown, backupsDir, lockData);
+  for (const targetPath of absoluteInstructionTargets) {
+    await ensureManagedTextFile(targetPath, agentsMarkdown, backupsDir, lockData);
   }
 
   const skillsSourcePath = path.join(installRoot, "catalog");
 
-  for (const pathParts of skillTargets) {
-    await ensureSymlink(path.join(cwd, ...pathParts), skillsSourcePath, backupsDir, lockData);
+  for (const targetPath of absoluteSkillTargets) {
+    await ensureSymlink(targetPath, skillsSourcePath, backupsDir, lockData);
   }
 
   await writeJson(lockPath, lockData);

package/packages/detectors/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/detectors",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "private": true,
   "type": "module"
 }