@hone-ai/cli 1.10.0 → 1.12.0

package/hone-cli.js

@@ -387,7 +387,12 @@ program
       process.exit(1);
     }
 
-    // ── Phase 1b: Install Claude Code files (CLAUDE.md + .claude/agents/) ────
+    // ── Phase 1b: Install CLAUDE.md ──────────────────────────────────────────
+    // HC-019y: removed the install-time .github/agents/ -> .claude/agents/
+    // mirror. The bash setup script now writes agents directly to
+    // .claude/agents/ (the path Claude Code actually reads). Pre-fix the
+    // mirror ran only at install time, so post-install edits to
+    // .github/agents/ were silently dropped (OptionsFlow E34-A: 6+ PRs).
     const repoRoot = process.cwd();
     const claudeMdSrc = path.join(tmpDir, 'CLAUDE.md');
     const claudeMdDst = path.join(repoRoot, 'CLAUDE.md');
@@ -402,20 +407,6 @@ program
       }
     }
 
-    // Create .claude/agents/ with symlinks or copies of .github/agents/
-    const ghAgentsDir = path.join(repoRoot, '.github', 'agents');
-    const claudeAgentsDir = path.join(repoRoot, '.claude', 'agents');
-    if (fs.existsSync(ghAgentsDir)) {
-      fs.mkdirSync(claudeAgentsDir, { recursive: true });
-      const agentFiles = fs.readdirSync(ghAgentsDir).filter(f => f.endsWith('.agent.md'));
-      for (const file of agentFiles) {
-        const src = path.join(ghAgentsDir, file);
-        const dst = path.join(claudeAgentsDir, file);
-        fs.copyFileSync(src, dst);
-      }
-      console.log(`  ✓ .claude/agents/ created (${agentFiles.length} agents mirrored from .github/agents/)`);
-    }
-
     // ── Phase 1c: Platform grounding (HC-013b-setup) ──────────────────────
     //    Runs AFTER bash script writes .pipeline-config.yml.
     //    Discovers metadata types, detects MCP, selects doc registry URLs,
@@ -1096,13 +1087,24 @@ program
       // Write generated skills to disk
       console.log('Writing generated skills...');
       if (result.skills) {
+        let preservedCount = 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 });
-          fs.writeFileSync(skillFile, content);
-          console.log(`  ✓ .github/skills/${skillName}/SKILL.md`);
+          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)`);
+          } 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)`);
         }
       }
 
@@ -1505,7 +1507,12 @@ program
       }
     }
 
-    // ── 2. Sync agent prompts into .github/agents/*.agent.md ───────────────
+    // ── 2. Sync agent prompts into .claude/agents/*.agent.md ───────────────
+    // HC-019y: writes directly to .claude/agents/ (the path Claude Code
+    // actually reads). Pre-fix `hone sync` wrote to .github/agents/ and
+    // mirrored to .claude/agents/, but the dual-directory layout caused
+    // OptionsFlow E34-A's silent-drop trap when adopters edited the wrong
+    // path. Mirror eliminated; .github/agents/ is now legacy.
     if (!opts.skillsOnly) {
       const agents = [
         'story-groomer',
@@ -1520,9 +1527,16 @@ program
       ];
 
       console.log('\nSyncing agent prompts...');
-      const agentsDir = path.join(process.cwd(), '.github', 'agents');
+      const agentsDir = path.join(process.cwd(), '.claude', 'agents');
       fs.mkdirSync(agentsDir, { recursive: true });
 
+      // Legacy-path migration warning (one-time, non-destructive).
+      const legacyGhAgents = path.join(process.cwd(), '.github', 'agents');
+      if (fs.existsSync(legacyGhAgents)) {
+        console.log('  ⚠ Legacy .github/agents/ detected — Claude Code reads .claude/agents/');
+        console.log('    Migrate any REPO-SPECIFIC edits then `rm -rf .github/agents/`');
+      }
+
       let synced = 0;
       for (const agent of agents) {
         try {
@@ -1531,7 +1545,7 @@ program
             headers: { Accept: 'text/markdown' },
           });
           const dest = path.join(agentsDir, `${agent}.agent.md`);
-          const rel = `agents/${agent}.agent.md`;
+          const rel = `.claude/agents/${agent}.agent.md`;
           const result = safeWrite(dest, rel, r.data);
           if (result !== 'skipped') {
             console.log(`  ✓ ${rel}`);
@@ -1539,28 +1553,13 @@ program
           }
         } catch (e) {
           if (e.response?.status === 404) {
-            console.log(`  ⚠ agents/${agent}.agent.md — prompt not seeded yet (run seed-agent-prompts.js)`);
+            console.log(`  ⚠ .claude/agents/${agent}.agent.md — prompt not seeded yet (run seed-agent-prompts.js)`);
           } else {
-            console.log(`  ⚠ agents/${agent}.agent.md — ${e.message}`);
+            console.log(`  ⚠ .claude/agents/${agent}.agent.md — ${e.message}`);
           }
         }
       }
       if (synced > 0) console.log(`\nSynced ${synced} agent prompts.`);
-
-      // Mirror to .claude/agents/ for Claude Code. This mirror is a derived
-      // copy of .github/agents/, so it's safe to overwrite — local edits
-      // belong in the source-of-truth dir. We still respect skipped files:
-      // if the source was skipped, don't overwrite the mirror either.
-      const claudeAgentsDir = path.join(process.cwd(), '.claude', 'agents');
-      const ghAgentsDir = path.join(process.cwd(), '.github', 'agents');
-      if (fs.existsSync(ghAgentsDir)) {
-        fs.mkdirSync(claudeAgentsDir, { recursive: true });
-        const files = fs.readdirSync(ghAgentsDir).filter(f => f.endsWith('.agent.md'));
-        for (const f of files) {
-          fs.copyFileSync(path.join(ghAgentsDir, f), path.join(claudeAgentsDir, f));
-        }
-        console.log(`  ✓ .claude/agents/ mirrored (${files.length} agents)`);
-      }
     }
 
     // ── 3. Sync copilot-instructions.md from server ──────────────────────
@@ -2029,7 +2028,7 @@ program
     console.log('╚══════════════════════════════════════════════╝');
     console.log('');
     console.log('  Your repo now has:');
-    console.log('    • 9 agents (.github/agents/ + .claude/agents/)');
+    console.log('    • 9 agents (.claude/agents/)');
     console.log('    • 11 enterprise skills + domain skills');
     console.log('    • CI workflow (ai-review.yml)');
     console.log('    • CLAUDE.md + copilot-instructions.md');
@@ -2611,6 +2610,50 @@ function sleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+/**
+ * HC-019y-followup-1: when `hone derive` writes a SKILL.md, splice the
+ * existing adopter REPO-SPECIFIC content over whatever the LLM produced
+ * for that section. The semantic guarantee: adopter-curated content
+ * (everything below the `<!-- REPO-SPECIFIC -->` marker) is NEVER lost
+ * across derive runs.
+ *
+ * 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.
+ *
+ * Returns { merged, preserved }:
+ *   - merged:    the bytes to write (always a string)
+ *   - preserved: true if adopter REPO-SPECIFIC content was preserved
+ *                across the splice; false for fresh writes
+ */
+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 };
+  }
+  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 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 };
+  }
+  // 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,
+  };
+}
+module.exports.splicePreserveRepoSpecific = splicePreserveRepoSpecific;
+
 // ── STATUS command (H-009) ────────────────────────────────────────────────────
 // Show pipeline state for a story (or use --all for every in-flight story).
 // Reads .github/pipeline/<STORY-ID>/metadata.yml + filesystem; uses
@@ -5252,4 +5295,9 @@ program
   .description('Hone AI — Enterprise SDLC Pipeline CLI')
   .version(pkg.version);
 
-program.parse(process.argv);
+// HC-019y-followup-1: gate commander invocation so the file can be
+// require()'d by tests for helpers like splicePreserveRepoSpecific
+// without auto-running the CLI's --help.
+if (require.main === module) {
+  program.parse(process.argv);
+}

package/lib/refresh-knowledge.js

@@ -26,9 +26,12 @@ const path = require('node:path');
 const crypto = require('node:crypto');
 const { execSync } = require('node:child_process');
 
+// HC-019y (2026-05-29): removed `.github/agents` from refresh paths.
+// Agents live exclusively at `.claude/agents/` (Claude Code's read path)
+// after the install-time mirror was eliminated. `.github/agents/` is now
+// a legacy directory adopters are expected to manually delete.
 const KNOWLEDGE_DIRS = [
   '.github/skills',
-  '.github/agents',
   '.claude/agents',
   '.github/copilot-instructions.md',
 ];

package/package.json

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