@skilly-hand/skilly-hand 0.29.3 → 0.30.0

package/CHANGELOG.md

@@ -16,6 +16,21 @@ All notable changes to this project are documented in this file.
 ### Removed
 - _None._
 
+## [0.30.0] - 2026-06-20
+[View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.30.0)
+
+### Added
+- _None._
+
+### Changed
+- Expanded `review-rangers` with an approval-gated Mender remediation loop, independent re-review, critical-stop rules, bounded termination, repository-native verification, and automatic `test-driven-development` installation.
+
+### Fixed
+- _None._
+
+### Removed
+- _None._
+
 ## [0.29.3] - 2026-06-20
 [View on npm](https://www.npmjs.com/package/@skilly-hand/skilly-hand/v/0.29.3)
 

package/README.md

@@ -47,9 +47,9 @@ The full skill catalog is also discoverable through the [skills.sh](https://www.
 npx skills add Davecelot/skilly-hand --skill '*'
 ```
 
-Use `npx skills add Davecelot/skilly-hand --list` to inspect the available skills before installing. The `skills/` directory is a GitHub-facing overlay made of symlinks to `catalog/skills/`; it helps skills.sh discover the catalog without changing the regular `npx skilly-hand` npm package contents or CLI flow.
+Use `npx skills add Davecelot/skilly-hand --list` to inspect the available skills before installing. The `skills/` directory is a generated GitHub-facing mirror of `catalog/skills/`, using real files because skills.sh discovers `SKILL.md` entries from GitHub's repository tree. Run `npm run skills:sync` after catalog changes; `npm run catalog:check` rejects mirror drift.
 
-Windows contributors who clone the repo locally should enable symlink support before checkout, for example with `git config --global core.symlinks true`, and may also need Developer Mode or elevated symlink privileges. If the repo was already checked out without symlinks, re-check out or reclone after enabling support.
+skills.sh adds a repository to its public catalog after a skill is installed through the official CLI with telemetry enabled. The public page and automated security audits may take a few minutes to appear after the first installation.
 
 ---
 

package/catalog/README.md

@@ -18,7 +18,7 @@ Published portable skills consumed by the `skilly-hand` CLI.
 | `project-teacher` | Scan the active project and teach any concept, code path, or decision using verified information, interactive questions, and simple explanations. Trigger: user asks to explain, understand, clarify, or learn about anything in the project or codebase. | core, workflow, education | all |
 | `prompt-engineering` | Guide users in writing, improving, evaluating, and tuning prompts for LLMs across factual, creative, structured, grounded, coding, safety-sensitive, and production scenarios. Trigger: writing, improving, evaluating, or tuning prompts for LLMs. | prompting, llm, workflow, quality | all |
 | `react-guidelines` | Guide React and Next.js code generation, review, and performance tuning using latest stable React verification and modern framework best practices. Trigger: generating, reviewing, refactoring, or optimizing React code artifacts in React projects. | react, frontend, workflow, best-practices | all |
-| `review-rangers` | Review code, decisions, and artifacts through a multi-perspective committee and a domain expert safety guard, then synthesize a structured verdict. | core, workflow, review, quality | all |
+| `review-rangers` | Review code, decisions, and artifacts through an independent committee and safety guard, then optionally run bounded, approval-gated remediation. Trigger: reviewing risky artifacts or remediating structured review findings. | core, workflow, review, quality | all |
 | `roaster` | Challenge plans with constructive roast-style critique that exposes weak assumptions, missing angles, shallow sequencing, and unclear success criteria. Trigger: when the user proposes, requests, or evaluates a plan of any kind. | core, workflow, planning, quality | all |
 | `spec-driven-development` | Plan, execute, and verify multi-step work through versioned specs with small, testable tasks. Trigger: planning or executing feature work, bug fixes, and multi-phase implementation. | core, workflow, planning | all |
 | `test-driven-development` | Guide implementation through evidence-based RED, GREEN, and REFACTOR cycles without assuming a language, framework, or test runner. Trigger: implementing testable behavior or reproducing a regression with tests first. | testing, workflow, quality, core | all |

package/catalog/skills/review-rangers/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: "review-rangers"
-description: "Review code, decisions, and artifacts through a multi-perspective committee and a domain expert safety guard, then synthesize a structured verdict."
+description: "Review code, decisions, and artifacts through an independent committee and safety guard, then optionally run bounded, approval-gated remediation. Trigger: reviewing risky artifacts or remediating structured review findings."
 skillMetadata:
   author: "skilly-hand"
-  last-edit: "2026-04-26"
+  last-edit: "2026-06-20"
   license: "Apache-2.0"
-  version: "1.1.0"
-  changelog: "Added DECISIONS.md registry ownership guidance; preserves durable review insights and anti-slop decisions across sessions; affects review-rangers workflow, install scaffolding, and project memory usage"
-  auto-invoke: "Reviewing code, decisions, or artifacts where adversarial multi-perspective evaluation adds value"
+  version: "1.2.0"
+  changelog: "Added approval-gated Mender remediation with bounded independent re-review; prevents unauthorized writes and unbounded fix loops; affects review orchestration, installation dependencies, and prompt assets"
+  auto-invoke: "Reviewing risky code, decisions, or artifacts, or remediating structured review findings"
   allowed-tools:
     - "Read"
     - "Edit"
@@ -48,8 +48,13 @@ Do not use this skill for:
 7. Run the committee and safety guard in parallel.
 8. Collect all outputs.
 9. Synthesize a structured verdict following the Synthesis Rules.
-10. Emit the final verdict with confidence tier, top findings, and recommended action.
-11. Decide whether any insight qualifies for `.ai/DECISIONS.md`; if yes, update the registry and its changelog in the same edit.
+10. If the verdict is `HIGH`, emit the final report and stop. If it is `VETO` or any critical-stop condition applies, return control to a human without modifying the target.
+11. For `MEDIUM` or `LOW`, present the open findings and request explicit approval before the first mutation. Skip this checkpoint only when the caller explicitly requested unattended or autonomous remediation in the current task.
+12. After approval, invoke The Mender using `assets/mender-template.md`. Pass only the target context and open findings; do not pass intermediate reviewer discussion.
+13. Run repository-native verification, then send the changed target to a fresh independent committee and safety guard. Reviewers from every round remain read-only.
+14. Repeat only while progress is material and no termination rule applies. Allow at most three remediation rounds and stop when the same finding survives two consecutive rounds without material progress.
+15. Emit the final report with confidence tier, finding-to-fix evidence, unresolved items, stop reason when applicable, and recommended action.
+16. Evaluate durable `.ai/DECISIONS.md` updates after the final `HIGH` report or terminal escalation; if an insight qualifies, update the registry and its changelog in the same edit.
 
 ---
 
@@ -80,6 +85,7 @@ Never assign the same lens to two committee members. Each member evaluates indep
 - Spawn committee members in parallel.
 - Pass only the target artifact and the member's assigned lens as context.
 - Do not share intermediate findings between members before synthesis.
+- Committee members and the safety guard are read-only in every round. They MUST NOT modify the target, assign work, or reuse another reviewer's conclusions.
 
 ---
 
@@ -108,6 +114,66 @@ The safety guard:
 
 ---
 
+## Remediation Protocol
+
+### Role Separation
+
+The Mender is the only role allowed to modify the target during a Review Rangers remediation cycle.
+
+- Committee members and the safety guard remain independent, read-only judges.
+- The Mender receives the synthesized open findings and target context, not reviewer identities or hidden reasoning.
+- The Mender MUST NOT assign, raise, lower, or otherwise edit confidence tiers.
+- The orchestrator owns approval, round counting, critical-stop evaluation, re-review, and the final verdict.
+- A Mender MUST NOT invoke Review Rangers recursively. Re-review returns to the orchestrator.
+
+### Approval Boundary
+
+Interactive review MUST pause before the first file mutation and obtain explicit approval.
+
+- A request to review, assess, audit, or invoke this skill is not write approval.
+- Skill invocation alone is not write approval.
+- The checkpoint may be skipped only when the caller explicitly asks for unattended or autonomous remediation in the current task.
+- Approval covers only the presented open findings and target. New scope or a critical-stop condition returns control to the caller.
+
+### Critical Stops
+
+Stop before another mutation or remediation round when any of these applies:
+
+- The verdict is `VETO`.
+- A security, privacy, accessibility, or data-integrity blocker requires human judgment.
+- A fix would cause a breaking public API change.
+- A fix would alter a broadly shared foundation, architecture, release policy, CI/CD policy, or security policy without explicit authority.
+- Required repository-native verification is unavailable or failing for reasons the remediation cannot safely resolve.
+- Product intent, ownership, migration policy, or another authoritative decision is required.
+- Three remediation rounds have completed.
+- The same finding survives two consecutive rounds without material progress.
+
+For every stop, report the unresolved finding, available evidence, stop reason, and required human decision. Do not broaden scope to conceal a failed check or force a higher confidence tier.
+
+### Repository-Native Verification
+
+The Mender MUST discover and run the narrowest relevant verification supported by the target repository.
+
+1. Read repository instructions and declared scripts or commands.
+2. Choose relevant lint, test, type-check, build, artifact, or deterministic document checks.
+3. When testable behavior changes, follow the installed `test-driven-development` guidance and record RED, GREEN, REFACTOR, and regression evidence.
+4. For non-code artifacts, use the narrowest deterministic structural or content check.
+5. Report exact commands, outcomes, failures, and checks that could not run.
+
+Never assume npm, a particular test runner, or a fixed toolchain. A failed required check blocks `HIGH` unless a human explicitly accepts the residual risk.
+
+### Re-review and Termination
+
+- Every remediation round receives a monotonically increasing round number from 1 through 3.
+- After verification, use a fresh committee and safety guard with the same independence rules as the initial review.
+- Compare findings by underlying issue, not wording alone.
+- Material progress means a finding is resolved, reduced in severity with evidence, or narrowed by a verified constraint.
+- `HIGH` ends the loop successfully.
+- `MEDIUM` or `LOW` may enter another approved round only when progress is material and no stop applies.
+- Any stop ends the loop with a terminal escalation report.
+
+---
+
 ## Synthesis Rules
 
 ### Confidence Tiers
@@ -194,6 +260,8 @@ Every change to `.ai/DECISIONS.md` must update `## Changelog` in the same edit.
 
 If the changelog section is missing, add it as the final section before making any other registry change.
 
+Evaluate registry writes only after the final `HIGH` report or terminal escalation. Intermediate remediation rounds MUST NOT create duplicate or provisional decision entries.
+
 ---
 
 ## Decision Tree
@@ -215,6 +283,17 @@ Does any committee member flag a security or data-integrity risk?
 Does committee majority agree the target is sound?
   YES and safety guard passes -> HIGH or MEDIUM depending on split
   NO                          -> LOW
+
+Is the verdict MEDIUM or LOW without a critical stop?
+  YES -> obtain explicit mutation approval unless unattended remediation was explicitly requested
+
+Is remediation approved and within the termination bounds?
+  YES -> invoke The Mender, verify with repository-native checks, then run a fresh independent review
+  NO  -> emit a terminal escalation report
+
+Did the review reach HIGH, three rounds, or two stagnant rounds?
+  YES -> stop and emit the final report
+  NO  -> continue only when material progress is evidenced
 ```
 
 ---
@@ -227,6 +306,9 @@ cat .skilly-hand/catalog/review-rangers/assets/committee-member-template.md
 
 # Reference safety guard template when constructing agent prompts
 cat .skilly-hand/catalog/review-rangers/assets/safety-guard-template.md
+
+# Reference the only write-capable remediation template after approval
+cat .skilly-hand/catalog/review-rangers/assets/mender-template.md
 ```
 
 ---
@@ -235,3 +317,5 @@ cat .skilly-hand/catalog/review-rangers/assets/safety-guard-template.md
 
 - Committee member prompt template: [assets/committee-member-template.md](assets/committee-member-template.md)
 - Safety guard prompt template: [assets/safety-guard-template.md](assets/safety-guard-template.md)
+- Mender prompt template: [assets/mender-template.md](assets/mender-template.md)
+- Test-driven remediation guidance: [../test-driven-development/SKILL.md](../test-driven-development/SKILL.md)

package/catalog/skills/review-rangers/assets/mender-template.md

@@ -0,0 +1,70 @@
+# The Mender: Remediation Round {{ROUND_NUMBER}}
+
+## Role
+
+You are The Mender, the only write-capable role in this Review Rangers remediation cycle. You repair approved findings; you do not judge the target or choose the final verdict.
+
+## Target
+
+{{TARGET_CONTEXT}}
+
+## Approved Open Findings
+
+{{OPEN_FINDINGS}}
+
+## Repository Context
+
+{{REPOSITORY_INSTRUCTIONS_AND_COMMANDS}}
+
+## Remediation Instructions
+
+1. Confirm every requested change maps to an approved open finding.
+2. Read repository instructions, conventions, scripts, and the affected files before editing.
+3. Stop and return control when a critical-stop condition, new scope, or required authority is discovered.
+4. Apply the smallest coherent fix for each finding. Preserve unrelated behavior and user changes.
+5. For testable behavior, follow the installed `test-driven-development` guidance and record RED, GREEN, REFACTOR, and regression evidence.
+6. For non-code changes, use the narrowest deterministic structural or content check.
+7. Run repository-native verification. Do not assume a package manager, test runner, language, or fixed command.
+8. Return a finding-to-fix map, files changed, exact verification outcomes, unresolved items, and any required human decision.
+
+## Critical Stops
+
+Do not mutate further when remediation requires any of the following without explicit authority:
+
+- Resolving a `VETO` or a security, privacy, accessibility, or data-integrity blocker that requires human judgment.
+- Introducing a breaking public API change.
+- Changing a broadly shared foundation, architecture, release policy, CI/CD policy, or security policy.
+- Proceeding without required verification or concealing a failing check.
+- Choosing product intent, migration policy, ownership, or another authoritative decision.
+
+## Output Format
+
+```text
+ROUND: {{ROUND_NUMBER}}
+
+FINDING-TO-FIX MAP:
+1. Finding: {stable finding summary}
+   Fix: {what changed and why it addresses the finding}
+   Files: {paths}
+   Status: {Resolved | Partially resolved | Unresolved | Stopped}
+
+VERIFICATION:
+1. {exact command or deterministic check} -> {PASS | FAIL | NOT_RUN}
+   Evidence: {short factual result}
+
+UNRESOLVED ITEMS:
+1. {finding or none}
+
+STOP REASON:
+{none | critical-stop condition and required human decision}
+```
+
+## Constraints
+
+- MUST modify only the approved target and findings.
+- MUST preserve unrelated user changes.
+- MUST use repository-native verification and report failures honestly.
+- MUST NOT change confidence, assign a confidence tier, or claim the review passed.
+- MUST NOT invoke Review Rangers, committee members, or the safety guard recursively.
+- MUST NOT edit `.ai/DECISIONS.md`; final registry timing belongs to the orchestrator.
+- MUST NOT begin another remediation round.

package/catalog/skills/review-rangers/manifest.json

@@ -1,7 +1,7 @@
 {
   "id": "review-rangers",
   "title": "Review Rangers",
-  "description": "Review code, decisions, and artifacts through a multi-perspective committee and a domain expert safety guard, then synthesize a structured verdict.",
+  "description": "Review code, decisions, and artifacts through an independent committee and safety guard, then optionally run bounded, approval-gated remediation. Trigger: reviewing risky artifacts or remediating structured review findings.",
   "portable": true,
   "tags": ["core", "workflow", "review", "quality"],
   "detectors": ["always"],
@@ -10,11 +10,11 @@
   "agentSupport": ["codex", "claude", "cursor", "gemini", "copilot", "antigravity", "windsurf", "trae"],
   "skillMetadata": {
     "author": "skilly-hand",
-    "last-edit": "2026-04-26",
+    "last-edit": "2026-06-20",
     "license": "Apache-2.0",
-    "version": "1.1.0",
-    "changelog": "Added DECISIONS.md registry ownership guidance; preserves durable review insights and anti-slop decisions across sessions; affects review-rangers workflow, install scaffolding, and project memory usage",
-    "auto-invoke": "Reviewing code, decisions, or artifacts where adversarial multi-perspective evaluation adds value",
+    "version": "1.2.0",
+    "changelog": "Added approval-gated Mender remediation with bounded independent re-review; prevents unauthorized writes and unbounded fix loops; affects review orchestration, installation dependencies, and prompt assets",
+    "auto-invoke": "Reviewing risky code, decisions, or artifacts, or remediating structured review findings",
     "allowed-tools": [
       "Read",
       "Edit",
@@ -29,7 +29,8 @@
   "files": [
     { "path": "SKILL.md", "kind": "instruction" },
     { "path": "assets/committee-member-template.md", "kind": "asset" },
-    { "path": "assets/safety-guard-template.md", "kind": "asset" }
+    { "path": "assets/safety-guard-template.md", "kind": "asset" },
+    { "path": "assets/mender-template.md", "kind": "asset" }
   ],
-  "dependencies": []
+  "dependencies": ["test-driven-development"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skilly-hand/skilly-hand",
-  "version": "0.29.3",
+  "version": "0.30.0",
   "license": "CC-BY-NC-4.0",
   "type": "module",
   "repository": {
@@ -31,8 +31,10 @@
   "packageManager": "pnpm@11.1.2",
   "scripts": {
     "build": "node ./scripts/build-catalog-index.mjs",
-    "catalog:check": "node ./scripts/check-catalog.mjs",
-    "catalog:sync": "node ./scripts/sync-catalog.mjs",
+    "catalog:check": "node ./scripts/check-catalog.mjs && node ./scripts/sync-skills-overlay.mjs --check",
+    "catalog:sync": "node ./scripts/sync-catalog.mjs && node ./scripts/sync-skills-overlay.mjs",
+    "skills:check": "node ./scripts/sync-skills-overlay.mjs --check",
+    "skills:sync": "node ./scripts/sync-skills-overlay.mjs",
     "agentic:self:sync": "node ./scripts/sync-self-agentic.mjs",
     "test": "node --test tests/*.test.js && node ./scripts/test-in-sandbox.mjs",
     "deps:policy:check": "node ./scripts/dependency-policy-check.mjs",

package/packages/catalog/package.json

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

package/packages/cli/package.json

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

package/packages/core/package.json

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

package/packages/detectors/package.json

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