@hone-ai/cli 1.16.0 → 1.17.0

package/hone-cli.js

@@ -1112,24 +1112,41 @@ program
       console.log('Writing generated skills...');
       if (result.skills) {
         let preservedCount = 0;
+        let sidecarCount = 0;
         for (const [skillName, content] of Object.entries(result.skills)) {
           if (!content || content.length < 50) continue;
           const skillDir  = path.join(repoRoot, '.github', 'skills', skillName);
           const skillFile = path.join(skillDir, 'SKILL.md');
           fs.mkdirSync(skillDir, { recursive: true });
-          const { merged, preserved } = splicePreserveRepoSpecific(skillFile, content);
-          fs.writeFileSync(skillFile, merged);
-          if (preserved) {
-            preservedCount++;
-            console.log(`  ✓ .github/skills/${skillName}/SKILL.md (preserved adopter REPO-SPECIFIC content)`);
+          const spliceResult = splicePreserveRepoSpecific(skillFile, content);
+          if (spliceResult.sidecar) {
+            // HC-019y-followup-2: legacy unmarked file — write to sidecar,
+            // don't overwrite, prompt adopter to review.
+            fs.writeFileSync(spliceResult.sidecarPath, spliceResult.merged);
+            sidecarCount++;
+            console.log(`  ⚠ .github/skills/${skillName}/SKILL.md — NOT overwritten`);
+            console.log(`    Wrote derive output to: ${path.relative(repoRoot, spliceResult.sidecarPath)}`);
+            console.log(`    Reason: ${spliceResult.reason}`);
           } else {
-            console.log(`  ✓ .github/skills/${skillName}/SKILL.md`);
+            fs.writeFileSync(skillFile, spliceResult.merged);
+            if (spliceResult.preserved) {
+              preservedCount++;
+              console.log(`  ✓ .github/skills/${skillName}/SKILL.md (preserved adopter REPO-SPECIFIC content)`);
+            } else {
+              console.log(`  ✓ .github/skills/${skillName}/SKILL.md`);
+            }
           }
         }
         if (preservedCount > 0) {
           console.log(`\n  Preserved adopter REPO-SPECIFIC content in ${preservedCount} skill(s).`);
           console.log(`  (HC-019y-followup-1: derive no longer overwrites curated REPO-SPECIFIC sections)`);
         }
+        if (sidecarCount > 0) {
+          console.log(`\n  ⚠ HC-019y-followup-2: ${sidecarCount} legacy unmarked SKILL(s) routed to .derive-new sidecars.`);
+          console.log(`  Review each sidecar; if the derive output is acceptable, replace the original.`);
+          console.log(`  To opt into automatic splice protection on the next derive, add a`);
+          console.log(`  '<!-- REPO-SPECIFIC -->' marker to the original file.`);
+        }
       }
 
       // H-022: surface parser warnings so silent drops become VISIBLE failures.

package/lib/splice-repo-specific.js

@@ -6,6 +6,24 @@
  * (everything below the `<!-- REPO-SPECIFIC -->` marker) is NEVER lost
  * across derive runs.
  *
+ * HC-019y-followup-2: legacy adopter-curated SKILLs WITHOUT the
+ * REPO-SPECIFIC marker were still vulnerable. OptionsFlow's
+ * `python-developer/SKILL.md` (834 lines authored by stories E22-E /
+ * E22-A / E16-A predating the marker convention) was REPLACED with
+ * 69 lines of fresh LLM output on 2026-05-30 because the file had no
+ * marker — the helper fell through to "fresh write" and 765 lines of
+ * legitimately-curated content were lost. Restored manually in
+ * OptionsFlow PR #106.
+ *
+ * Fix: non-destructive sidecar mode. When the existing file is
+ * substantial (>500 bytes) AND has neither the REPO-SPECIFIC marker
+ * nor the ENTERPRISE-MANAGED marker, the helper now returns
+ * sidecar=true. The caller writes to `<path>.derive-new` instead of
+ * overwriting, emits a warning, and prompts the adopter to add a
+ * `<!-- REPO-SPECIFIC -->` marker to opt into splice on the next derive.
+ * Same pattern as `setup-ai-pipeline.sh copy_skills()` uses a `.bak`
+ * fallback.
+ *
  * Pre-fix: derive wrote the file blind (fs.writeFileSync(skillFile,
  * content)). 5 OptionsFlow regression tests broke after a single derive
  * because 378 lines of E33-A/E34-B-added content disappeared.
@@ -21,41 +39,104 @@
  */
 const fs = require('node:fs');
 
+const REPO_SPECIFIC_MARKER = '<!-- REPO-SPECIFIC';
+const ENTERPRISE_MARKER = '<!-- ENTERPRISE-MANAGED';
+
+// HC-019y-followup-2: the sidecar threshold. Files smaller than this
+// are treated as stubs / placeholders and overwritten normally — only
+// genuinely substantial unmarked content triggers sidecar mode. 500
+// bytes is roughly: 5-10 lines of meaningful markdown. Tonight's
+// evidence (python-developer/SKILL.md at 834 lines / ~32KB) is well
+// above the threshold; trivial scaffolding (a 1-line stub) is well
+// below. Tunable if real adopter data shows this is wrong.
+const SIDECAR_MIN_BYTES = 500;
+
 /**
- * Splice adopter REPO-SPECIFIC tail into derive output.
+ * Splice adopter REPO-SPECIFIC tail into derive output, OR fall back
+ * to sidecar mode for legacy unmarked files (HC-019y-followup-2).
  *
  * @param {string} existingPath  absolute path of the file being overwritten
  * @param {string} newContent    the content from `hone derive` server response
- * @returns {{ merged: string, preserved: boolean }}
- *   merged:    bytes to write
- *   preserved: true if adopter REPO-SPECIFIC content was preserved
- *              across the splice; false for fresh writes
+ * @returns {{
+ *   merged: string,
+ *   preserved: boolean,
+ *   sidecar: boolean,
+ *   sidecarPath: string|null,
+ *   reason: string|null
+ * }}
+ *   merged:      bytes to write (to existingPath OR sidecarPath)
+ *   preserved:   true if adopter REPO-SPECIFIC content was preserved
+ *   sidecar:     true if caller should write to sidecarPath instead of
+ *                overwriting existingPath; false otherwise
+ *   sidecarPath: when sidecar=true, the path the caller should write to
+ *                (always `${existingPath}.derive-new`); null otherwise
+ *   reason:      when sidecar=true, human-readable explanation for the
+ *                warning the caller should emit; null otherwise
  */
 function splicePreserveRepoSpecific(existingPath, newContent) {
-  const MARKER = '<!-- REPO-SPECIFIC';
   if (!fs.existsSync(existingPath)) {
     // Fresh adopter — no existing file. Write new content as-is.
-    return { merged: newContent, preserved: false };
+    return { merged: newContent, preserved: false, sidecar: false, sidecarPath: null, reason: null };
   }
   const existing = fs.readFileSync(existingPath, 'utf8');
-  const oldIdx = existing.indexOf(MARKER);
-  if (oldIdx < 0) {
-    // Existing file has no REPO-SPECIFIC marker (likely a non-skill or
-    // legacy file). Nothing to preserve.
-    return { merged: newContent, preserved: false };
+  const oldIdx = existing.indexOf(REPO_SPECIFIC_MARKER);
+
+  if (oldIdx >= 0) {
+    // Existing has REPO-SPECIFIC marker — splice as before.
+    const newIdx = newContent.indexOf(REPO_SPECIFIC_MARKER);
+    if (newIdx < 0) {
+      // New content has no REPO-SPECIFIC section. Append the existing one.
+      return {
+        merged: newContent.trimEnd() + '\n\n' + existing.slice(oldIdx),
+        preserved: true,
+        sidecar: false,
+        sidecarPath: null,
+        reason: null,
+      };
+    }
+    // Both have REPO-SPECIFIC. Take new content up to the marker, then
+    // append everything from existing's marker to EOF.
+    return {
+      merged: newContent.slice(0, newIdx) + existing.slice(oldIdx),
+      preserved: true,
+      sidecar: false,
+      sidecarPath: null,
+      reason: null,
+    };
   }
-  const newIdx = newContent.indexOf(MARKER);
-  if (newIdx < 0) {
-    // New content has no REPO-SPECIFIC section. Append the existing one.
-    return { merged: newContent.trimEnd() + '\n\n' + existing.slice(oldIdx), preserved: true };
+
+  // No REPO-SPECIFIC marker. HC-019y-followup-2: check if this is a
+  // legacy substantial-unmarked file that we'd risk destroying.
+  const hasEnterpriseMarker = existing.indexOf(ENTERPRISE_MARKER) >= 0;
+  const isSubstantial = Buffer.byteLength(existing, 'utf8') >= SIDECAR_MIN_BYTES;
+
+  if (isSubstantial && !hasEnterpriseMarker) {
+    // Legacy unmarked file with real content. Write new content to a
+    // sidecar path instead of overwriting. Adopter reviews + decides
+    // whether to adopt the derive output, manually merge, or opt into
+    // splice protection by adding a REPO-SPECIFIC marker.
+    return {
+      merged: newContent,
+      preserved: false,
+      sidecar: true,
+      sidecarPath: `${existingPath}.derive-new`,
+      reason:
+        `legacy unmarked file (${Buffer.byteLength(existing, 'utf8')} bytes) — ` +
+        `wrote derive output to <path>.derive-new instead of overwriting. ` +
+        `Review the sidecar, then either: (a) replace the original, ` +
+        `(b) manually merge curated sections, or (c) add ` +
+        `'<!-- REPO-SPECIFIC -->' to the original to opt into splice on next derive.`,
+    };
   }
-  // Both have REPO-SPECIFIC. Take new content up to the marker, then
-  // append everything from existing's marker to EOF. This preserves
-  // adopter-curated content while updating the body before the marker.
-  return {
-    merged: newContent.slice(0, newIdx) + existing.slice(oldIdx),
-    preserved: true,
-  };
+
+  // Either small (stub/placeholder) or has ENTERPRISE-MANAGED marker
+  // (deliberately enterprise-controlled). Safe to overwrite.
+  return { merged: newContent, preserved: false, sidecar: false, sidecarPath: null, reason: null };
 }
 
-module.exports = { splicePreserveRepoSpecific };
+module.exports = {
+  splicePreserveRepoSpecific,
+  REPO_SPECIFIC_MARKER,
+  ENTERPRISE_MARKER,
+  SIDECAR_MIN_BYTES,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hone-ai/cli",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Hone AI — Enterprise SDLC Pipeline CLI",
   "main": "hone-cli.js",
   "bin": {