claude-code-arcane 2.9.4 → 2.9.6

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.9.6](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.9.5...v2.9.6) (2026-09-07)
+
+
+### Bug Fixes
+
+* **rules:** make code-comments the only authority on comments ([99bb84e](https://github.com/SebastianLuser/claude-code-arcane/commit/99bb84e7612630ae67d4942b378ccd1881d4cf64))
+
+## [2.9.5](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.9.4...v2.9.5) (2026-09-07)
+
+
+### Bug Fixes
+
+* **update:** record the hash Arcane shipped, not the customized one on disk ([921c89d](https://github.com/SebastianLuser/claude-code-arcane/commit/921c89d25eb8167e1efbcd27ae233faf3beb85c8))
+
 ## [2.9.4](https://github.com/SebastianLuser/claude-code-arcane/compare/v2.9.3...v2.9.4) (2026-09-07)
 
 

package/dist/cli.js

@@ -2515,7 +2515,12 @@ Update available: ${chalk7.red(installedVersion)} -> ${chalk7.green(currentVersi
         arcane_version: currentVersion,
         source_version: currentVersion,
         updated_at: (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z"),
-        content_hashes: stripForeign(installedHashes, items),
+        content_hashes: hashesToRecord(
+          installedHashes,
+          manifest.content_hashes ?? null,
+          items,
+          opts.force ?? false
+        ),
         installed_skills: merged.skills,
         installed_rules: allRules,
         installed_agents: merged.agents,
@@ -2556,7 +2561,12 @@ Refreshed ${unhashed.length} file(s); no other changes to apply.`) : chalk7.gree
     arcane_version: currentVersion,
     source_version: currentVersion,
     updated_at: (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z"),
-    content_hashes: stripForeign(newHashes, items),
+    content_hashes: hashesToRecord(
+      newHashes,
+      manifest.content_hashes ?? null,
+      items,
+      opts.force ?? false
+    ),
     installed_skills: merged.skills,
     installed_rules: allRules,
     installed_agents: merged.agents,
@@ -2621,19 +2631,25 @@ function granularAgentDivisions(entries) {
   for (const division of whole) partial.delete(division);
   return partial;
 }
-function stripForeign(hashes, items) {
-  const stripped = {
-    skills: { ...hashes.skills },
-    rules: { ...hashes.rules },
-    agents: { ...hashes.agents },
-    hooks: { ...hashes.hooks }
+function hashesToRecord(fresh, previous, items, force) {
+  const recorded = {
+    skills: { ...fresh.skills },
+    rules: { ...fresh.rules },
+    agents: { ...fresh.agents },
+    hooks: { ...fresh.hooks }
   };
   for (const item of items) {
-    if (item.action !== "keep-foreign") continue;
     const bucket = `${item.type}s`;
-    delete stripped[bucket][item.name];
+    if (item.action === "keep-foreign") {
+      delete recorded[bucket][item.name];
+      continue;
+    }
+    if (item.action === "skip-customized" && !force) {
+      const asInstalled = previous?.[bucket]?.[item.name];
+      if (asInstalled) recorded[bucket][item.name] = asInstalled;
+    }
   }
-  return stripped;
+  return recorded;
 }
 function computeUpdatePlan(manifestHashes, installedHashes, sourceHashes, owned, exemptAgentDivisions = /* @__PURE__ */ new Set()) {
   const items = [];

package/docs/coding-standards.md

@@ -55,10 +55,9 @@ Si podés hacerlo con la stdlib de Python, la escotilla no aplica.
 
 ## Comentarios
 
-- **Escribí el porqué, no el qué.** El código ya dice qué hace.
-- **Doc comments para APIs públicas.** Las privadas no los necesitan.
-- **TODOs con owner y fecha:** `// TODO(@alice, 2026-05-01): descripción`
-- **Anti-pattern:** comentarios que explican el obvio (`// increment counter` sobre `counter++`)
+La regla vive en `.claude/rules/code-comments.md` y es la única autoridad.
+No dupliques criterios acá: dos listas sobre comentarios siempre terminan
+contradiciéndose, y gana la permisiva.
 
 ---
 
@@ -145,17 +144,6 @@ Antes de marcar trabajo como completo:
 
 ---
 
-## Comments / Docs Anti-Patterns
+## Comments / Docs
 
-**NO escribir:**
-- Comentarios que describen WHAT (el código ya dice)
-- Comentarios referenciando el task/PR actual ("added for JIRA-123")
-- Docstrings multi-párrafo en funciones simples
-- Comentarios `// removed X` para código borrado
-- `// used by Y` (el tooling lo dice mejor)
-
-**SÍ escribir comentarios cuando:**
-- Explican el WHY que no es obvio
-- Documentan workaround de un bug específico (con link al bug)
-- Marcan invariantes o preconditions no-obvios
-- APIs públicas consumidas por terceros
+Ver `.claude/rules/code-comments.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-arcane",
-  "version": "2.9.4",
+  "version": "2.9.6",
   "description": "Skills, agents, hooks and rules for Claude Code — installable via npx claude-code-arcane",
   "type": "module",
   "bin": {

package/rules/code-comments.md

@@ -50,13 +50,19 @@ Comments are written in **English**, whatever language the conversation is in.
 
 ## Write
 
-- **The WHY that the code cannot show.** A constant that looks arbitrary, an ordering that
-  matters, a deliberate break from the surrounding pattern.
+**The default is no comment.** The code says what it does and the commit says why it changed.
+A new comment has to earn its place; it is never the neutral choice.
+
+The whole list of exceptions:
+
+- **Doc comments on public APIs** consumed from outside the module, one line. Private ones
+  need none.
 - **Workarounds**, with a link to the upstream bug.
-- **Non-obvious invariants or preconditions** a caller has to respect.
-- **Doc comments on public APIs** consumed from outside the module. Private ones need none.
 - **`TODO(@owner, YYYY-MM-DD): description`.** Never a bare `TODO`.
 
+A comment shaped as a comparison with what used to be there — "X and not Y", "no longer X",
+"now uses X" — is session narration wearing a technical disguise. It belongs in the commit.
+
 ## Shape
 
 One line, unless the reason honestly needs two. A comment that needs a paragraph to explain

package/rules/data-files.md

@@ -15,7 +15,7 @@ paths:
 - All JSON / YAML / TOML files must parse cleanly — malformed config blocks the build
 - File naming: lowercase with hyphens or underscores, following `[domain]-[name].[ext]` pattern
 - Every schema-bearing file must have a documented schema (JSON Schema, OpenAPI, Zod, Pydantic — whatever the stack uses)
-- Numeric values with business meaning must include a comment or companion doc explaining unit and intent (`timeout_ms`, not bare `timeout`)
+- Numeric values with business meaning carry the unit in the key (`timeout_ms`, not bare `timeout`)
 - Use consistent key naming within a file: camelCase for JSON, snake_case for YAML if that's the project convention — don't mix
 - No orphaned entries — every record must be referenced by code, another config, or explicitly marked as a default/example
 - Version config files when making breaking schema changes (`v1/`, `v2/` or explicit `schema_version` field)

package/rules/gamedev/engine-code.md

@@ -9,7 +9,7 @@ paths:
 - All engine APIs must be thread-safe OR explicitly documented as single-thread-only
 - Profile before AND after every optimization — document the measured numbers
 - Engine code must NEVER depend on gameplay code (strict dependency direction: engine <- gameplay)
-- Every public API must have usage examples in its doc comment
+- Public API doc comments stay to one line (see `code-comments`); usage examples belong in the docs, not the source
 - Changes to public interfaces require a deprecation period and migration guide
 - Use RAII / deterministic cleanup for all resources
 - All engine systems must support graceful degradation

package/rules/gamedev/shader-code.md

@@ -18,7 +18,7 @@ visual quality, performance, and cross-platform compatibility.
 ## Code Quality
 - All uniforms/parameters must have descriptive names and appropriate hints
 - Group related parameters (Unity: `[Header]`, Unreal: Category)
-- Comment non-obvious calculations (especially math-heavy sections)
+- Name non-obvious calculations rather than commenting them; comments follow `code-comments`
 - No magic numbers — use named constants or documented uniform values
 
 ## Performance Requirements