forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

package/lib/skills-sync.js

@@ -34,6 +34,8 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { parseFrontmatter } = require('./using-forge');
 
 /** Canonical skills live under this directory at the repo/package root. */
 const CANONICAL_SKILLS_DIR = 'skills';
@@ -71,7 +73,7 @@ function isValidSkillName(name) {
  * @param {string} sourceRoot - Directory containing the canonical `skills/` dir.
  * @param {object} [options]
  * @param {Set<string>|string[]} [options.only] - Restrict to these skill names.
- * @returns {{name: string, sourcePath: string}[]} Sorted list of skills.
+ * @returns {{name: string, sourcePath: string, invocation: string}[]} Sorted list of skills.
  */
 function listCanonicalSkills(sourceRoot, options = {}) {
   const skillsDir = path.join(sourceRoot, CANONICAL_SKILLS_DIR);
@@ -88,9 +90,11 @@ function listCanonicalSkills(sourceRoot, options = {}) {
     if (only && !only.has(entry.name)) continue;
 
     const sourcePath = path.join(skillsDir, entry.name);
-    if (!fs.existsSync(path.join(sourcePath, 'SKILL.md'))) continue;
+    const skillFile = path.join(sourcePath, 'SKILL.md');
+    if (!fs.existsSync(skillFile)) continue;
 
-    skills.push({ name: entry.name, sourcePath });
+    const { invocation } = parseFrontmatter(fs.readFileSync(skillFile, 'utf8'));
+    skills.push({ name: entry.name, sourcePath, invocation });
   }
 
   skills.sort((a, b) => a.name.localeCompare(b.name));
@@ -131,6 +135,23 @@ function normalizeContent(buffer) {
   return buffer.toString('utf8').replace(/\r\n/g, '\n');
 }
 
+function gitIgnoredCanonicalPaths(repoRoot, runGit = execFileSync, { strict = false } = {}) {
+  if (!fs.existsSync(path.join(repoRoot, '.git'))) return new Set();
+  try {
+    const output = runGit('git', [
+      'ls-files', '-z', '--others', '--ignored', '--exclude-standard', '--', 'skills',
+    ], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return new Set(output.split('\0').filter(Boolean).map(repoPath => repoPath.normalize('NFC')));
+  } catch (error) {
+    if (strict) throw error;
+    return new Set();
+  }
+}
+
 /**
  * Remove a symlink sitting at a target path so a real directory can be written
  * in its place. Only ever removes the link entry itself — never a real
@@ -174,13 +195,18 @@ function clearSymlinkAtPath(targetPath) {
  * @param {string} sourcePath - Source skill directory.
  * @param {string} targetPath - Target skill directory.
  */
-function copySkillDir(sourcePath, targetPath) {
+function copySkillDir(sourcePath, targetPath, excludeRelativePaths = new Set(), prefix = '') {
   fs.mkdirSync(targetPath, { recursive: true });
   for (const entry of fs.readdirSync(sourcePath, { withFileTypes: true })) {
+    const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
     const src = path.join(sourcePath, entry.name);
     const dest = path.join(targetPath, entry.name);
+    if (excludeRelativePaths.has(relative.normalize('NFC'))) {
+      fs.rmSync(dest, { recursive: true, force: true });
+      continue;
+    }
     if (entry.isDirectory()) {
-      copySkillDir(src, dest);
+      copySkillDir(src, dest, excludeRelativePaths, relative);
     } else if (entry.isFile()) {
       fs.copyFileSync(src, dest);
     }
@@ -201,7 +227,12 @@ function copySkillDir(sourcePath, targetPath) {
  * @param {boolean} [params.clean=false] - Remove canonical-managed stale dirs first.
  * @returns {{written: string[]}} Names of skills written.
  */
-function populateAgentSkills({ sourceRoot, targetSkillsDir, only, clean = false }) {
+function populateAgentSkills({ sourceRoot, targetSkillsDir, only, clean = false, excludeRelativePaths }) {
+  if (excludeRelativePaths === undefined) {
+    excludeRelativePaths = new Set([...gitIgnoredCanonicalPaths(sourceRoot)]
+      .map(repoPath => repoPath.slice('skills/'.length))
+      .filter(relative => !/^[^/]+\/SKILL\.md$/.test(relative)));
+  }
   const skills = listCanonicalSkills(sourceRoot, { only });
   fs.mkdirSync(targetSkillsDir, { recursive: true });
 
@@ -222,7 +253,7 @@ function populateAgentSkills({ sourceRoot, targetSkillsDir, only, clean = false
     // Defensive: clear a pre-existing (possibly dangling) symlink so the copy
     // doesn't fail. Only symlinks are removed — real dirs are overwritten in place.
     clearSymlinkAtPath(targetPath);
-    copySkillDir(skill.sourcePath, targetPath);
+    copySkillDir(skill.sourcePath, targetPath, excludeRelativePaths, skill.name);
     written.push(skill.name);
   }
   return { written };
@@ -235,9 +266,12 @@ function populateAgentSkills({ sourceRoot, targetSkillsDir, only, clean = false
  * @param {string} targetPath - Target (generated) skill dir.
  * @returns {{file: string, status: 'missing'|'changed'|'extra'}[]} Drift entries.
  */
-function diffSkillDir(sourcePath, targetPath) {
+function diffSkillDir(sourcePath, targetPath, excludeRelativePaths = new Set(), prefix = '') {
   const drift = [];
-  const sourceFiles = new Set(listFilesRecursive(sourcePath));
+  const sourceFiles = new Set(listFilesRecursive(sourcePath).filter(rel => {
+    const relative = prefix ? `${prefix}/${rel}` : rel;
+    return !excludeRelativePaths.has(relative.normalize('NFC'));
+  }));
   const targetFiles = new Set(listFilesRecursive(targetPath));
 
   for (const rel of sourceFiles) {
@@ -261,6 +295,28 @@ function diffSkillDir(sourcePath, targetPath) {
   return drift;
 }
 
+function collectAgentSkillDrift({ repoRoot, rel, skills, canonicalByName, excludeRelativePaths }) {
+  const agentDir = path.join(repoRoot, rel);
+  const drift = [];
+  const targetNames = fs.readdirSync(agentDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+  for (const skill of skills) {
+    const targetPath = path.join(agentDir, skill.name);
+    if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
+      drift.push({ agent: rel, skill: skill.name, file: 'SKILL.md', status: 'missing' });
+      continue;
+    }
+    for (const entry of diffSkillDir(skill.sourcePath, targetPath, excludeRelativePaths, skill.name)) {
+      drift.push({ agent: rel, skill: skill.name, ...entry });
+    }
+  }
+  for (const name of targetNames) {
+    if (!canonicalByName.has(name)) drift.push({ agent: rel, skill: name, file: '*', status: 'stale' });
+  }
+  return drift;
+}
+
 /**
  * Check that existing agent skill mirrors match the canonical source.
  *
@@ -276,9 +332,12 @@ function diffSkillDir(sourcePath, targetPath) {
  * @param {string[]} [params.agentSkillDirs] - Override the agent dirs to scan.
  * @returns {{inSync: boolean, checkedAgents: string[], drift: object[]}}
  */
-function checkSkillsSync({ repoRoot, only, agentSkillDirs = AGENT_SKILL_DIRS }) {
+function checkSkillsSync({ repoRoot, only, agentSkillDirs = AGENT_SKILL_DIRS, runGit = execFileSync }) {
   const skills = listCanonicalSkills(repoRoot, { only });
   const canonicalByName = new Map(skills.map((s) => [s.name, s]));
+  const excludeRelativePaths = new Set([...gitIgnoredCanonicalPaths(repoRoot, runGit)]
+    .map(repoPath => repoPath.slice('skills/'.length))
+    .filter(relative => !/^[^/]+\/SKILL\.md$/.test(relative)));
   const drift = [];
   const checkedAgents = [];
 
@@ -287,31 +346,7 @@ function checkSkillsSync({ repoRoot, only, agentSkillDirs = AGENT_SKILL_DIRS })
     if (!fs.existsSync(agentDir)) continue; // populated at setup time; absence ≠ drift
     checkedAgents.push(rel);
 
-    const targetNames = fs
-      .readdirSync(agentDir, { withFileTypes: true })
-      .filter((e) => e.isDirectory())
-      .map((e) => e.name);
-
-    // Skills present canonically but missing/changed in the mirror.
-    for (const skill of skills) {
-      const targetPath = path.join(agentDir, skill.name);
-      // A regular file at the skill path is corruption, not a valid mirror:
-      // treat it as drift instead of letting diffSkillDir() throw ENOTDIR.
-      if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
-        drift.push({ agent: rel, skill: skill.name, file: 'SKILL.md', status: 'missing' });
-        continue;
-      }
-      for (const entry of diffSkillDir(skill.sourcePath, targetPath)) {
-        drift.push({ agent: rel, skill: skill.name, ...entry });
-      }
-    }
-
-    // Skill dirs in the mirror with no canonical source = stale.
-    for (const name of targetNames) {
-      if (!canonicalByName.has(name)) {
-        drift.push({ agent: rel, skill: name, file: '*', status: 'stale' });
-      }
-    }
+    drift.push(...collectAgentSkillDrift({ repoRoot, rel, skills, canonicalByName, excludeRelativePaths }));
   }
 
   return { inSync: drift.length === 0, checkedAgents, drift };
@@ -324,6 +359,7 @@ module.exports = {
   listCanonicalSkills,
   listFilesRecursive,
   clearSymlinkAtPath,
+  gitIgnoredCanonicalPaths,
   populateAgentSkills,
   diffSkillDir,
   checkSkillsSync,

package/lib/smart-merge.js

@@ -1,13 +1,32 @@
 'use strict';
 
+const IMPROVEMENT_FOOTER = `---\n\n## Improving This Workflow\n\nEvery time you give the same instruction twice, add it to this file:\n1. User-specific rules: Add to USER:START section above\n2. Forge workflow improvements: Suggest to forge maintainers\n\n**Keep this file updated as you learn about the project.**\n\n---\n\nSee \`AGENTS.md\` for complete workflow guide.\nSee \`docs/TOOLCHAIN.md\` for comprehensive tool reference.\n`;
+
+function extractUnmanagedContent(existingContent) {
+  let unmanagedContent = existingContent
+    .replace(/\r\n?/g, '\n')
+    .replace(/<!-- FORGE:SETUP-INSTRUCTIONS[\s\S]*?-->/g, '')
+    .replace(/<!-- FORGE:START.*?-->[\s\S]*?<!-- FORGE:END -->/g, '')
+    .trim();
+
+  unmanagedContent = unmanagedContent.replace(/^# AGENTS\.md\s*/, '').trim();
+
+  const footer = IMPROVEMENT_FOOTER.trim();
+  // The generated footer may precede user-appended text; remove every exact managed copy.
+  unmanagedContent = unmanagedContent.split(footer).join('').trim();
+
+  return unmanagedContent;
+}
+
 /**
  * Smart merge for AGENTS.md - preserves USER sections, updates FORGE sections.
  *
- * Handles four cases:
+ * Handles five cases:
  * 1. No markers at all: Wrap existing content in USER markers, append FORGE section
  * 2. USER markers but no FORGE markers: Keep USER section, insert FORGE section
  * 3. Both markers present: Preserve USER section, update FORGE section (existing behavior)
- * 4. Empty existing content: Return only FORGE section (no empty USER block)
+ * 4. Forge markers without USER markers: Preserve surrounding unmanaged content as USER content
+ * 5. Empty existing content: Return only FORGE section (no empty USER block)
  *
  * @param {string} existingContent - The current AGENTS.md content
  * @param {string} newContent - The new template content containing FORGE section
@@ -20,6 +39,7 @@ function smartMergeAgentsMd(existingContent, newContent) {
 
   // Check if existing content has markers
   const hasUserMarkers = existingContent.includes('<!-- USER:START') && existingContent.includes('<!-- USER:END');
+  const hasForgeMarkers = existingContent.includes('<!-- FORGE:START') && existingContent.includes('<!-- FORGE:END');
 
   let userSection;
 
@@ -28,8 +48,12 @@ function smartMergeAgentsMd(existingContent, newContent) {
     const userMatch = (/(<!-- USER:START.*?-->[\s\S]*?<!-- USER:END -->)/).exec(existingContent);
     userSection = userMatch ? userMatch[0] : '';
   } else if (existingContent.trim() === '') {
-    // Empty existing content: no USER block at all
     userSection = null;
+  } else if (hasForgeMarkers) {
+    const unmanagedContent = extractUnmanagedContent(existingContent);
+    userSection = unmanagedContent
+      ? `<!-- USER:START -->\n${unmanagedContent}\n<!-- USER:END -->`
+      : null;
   } else {
     // No markers: wrap entire existing content in USER markers
     userSection = `<!-- USER:START -->\n${existingContent.trim()}\n<!-- USER:END -->`;
@@ -56,7 +80,7 @@ function smartMergeAgentsMd(existingContent, newContent) {
   merged += forgeSection + '\n\n';
 
   // Add footer
-  merged += `---\n\n## Improving This Workflow\n\nEvery time you give the same instruction twice, add it to this file:\n1. User-specific rules: Add to USER:START section above\n2. Forge workflow improvements: Suggest to forge maintainers\n\n**Keep this file updated as you learn about the project.**\n\n---\n\nSee \`AGENTS.md\` for complete workflow guide.\nSee \`docs/TOOLCHAIN.md\` for comprehensive tool reference.\n`;
+  merged += IMPROVEMENT_FOOTER;
 
   return merged;
 }

package/lib/symlink-utils.js

@@ -18,6 +18,40 @@ const path = require('node:path');
 const HEADER_COMMENT =
   '<!-- This file is a copy of AGENTS.md. Keep in sync manually or use: bunx forge setup --symlink -->';
 
+const SYMLINK_FALLBACK_ERRORS = new Set(['EACCES', 'ENOSYS', 'ENOTSUP', 'EOPNOTSUPP', 'EPERM']);
+
+function inspectExistingDestination(target, linkPath) {
+  let stat;
+  try {
+    stat = fs.lstatSync(linkPath);
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+
+  if (stat.isSymbolicLink()) {
+    let linkedTarget;
+    try {
+      linkedTarget = fs.readlinkSync(linkPath);
+    } catch (err) {
+      if (err.code === 'ENOENT') return null;
+      throw err;
+    }
+    if (path.resolve(path.dirname(linkPath), linkedTarget) === path.resolve(target)) {
+      return 'linked';
+    }
+  }
+  if (stat.isDirectory()) {
+    console.warn(`  Warning: Skipped ${linkPath} because it is a directory. Remove it manually and re-run setup.`);
+    return '';
+  }
+  if (stat.isFile() && fs.readFileSync(linkPath, 'utf8').trim() === '@AGENTS.md') {
+    return 'existing-import';
+  }
+  console.warn(`  Warning: Skipped ${linkPath} because an existing destination must be preserved.`);
+  return '';
+}
+
 /**
  * Create a symlink from `linkPath` pointing to `target`.
  * If symlink creation fails (e.g., EPERM on Windows without admin),
@@ -28,7 +62,7 @@ const HEADER_COMMENT =
  * @param {string} linkPath - Absolute path for the symlink/copy (e.g., CLAUDE.md)
  * @param {Object} [options={}] - Options
  * @param {boolean} [options.symlinkOnly=false] - When true, skip copy fallback (--symlink flag)
- * @returns {'linked'|'copied'|''} Result indicator
+ * @returns {'linked'|'copied'|'existing-import'|''} Result indicator
  */
 function createSymlinkOrCopy(target, linkPath, options = {}) {
   try {
@@ -38,17 +72,9 @@ function createSymlinkOrCopy(target, linkPath, options = {}) {
       return '';
     }
 
-    // Remove existing file/symlink at linkPath
-    if (fs.existsSync(linkPath)) {
-      const stat = fs.lstatSync(linkPath);
-      if (stat.isDirectory()) {
-        console.warn(
-          `  ⚠ Skipped ${linkPath} (a directory exists at this path). Remove it manually and re-run setup.`
-        );
-        return '';
-      }
-      fs.unlinkSync(linkPath);
-    }
+    // Existing agent files belong to the user. lstat also sees dangling links.
+    const existing = inspectExistingDestination(target, linkPath);
+    if (existing !== null) return existing;
 
     // Ensure parent directory exists
     const linkDir = path.dirname(linkPath);
@@ -56,22 +82,44 @@ function createSymlinkOrCopy(target, linkPath, options = {}) {
       fs.mkdirSync(linkDir, { recursive: true });
     }
 
-    // Attempt symlink (relative path for portability)
-    try {
-      const relPath = path.relative(linkDir, target);
-      fs.symlinkSync(relPath, linkPath);
-      return 'linked';
-    } catch (_symlinkErr) {
-      // Expected: symlink creation fails with EPERM on Windows without admin privileges — fall back to copy
-      if (options.symlinkOnly) {
-        console.warn(`  ⚠ Symlink failed for ${linkPath} (--symlink requires symlink support)`);
-        return '';
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      // Attempt symlink (relative path for portability)
+      try {
+        const relPath = path.relative(linkDir, target);
+        fs.symlinkSync(relPath, linkPath);
+        return 'linked';
+      } catch (symlinkErr) {
+        if (symlinkErr.code === 'EEXIST') {
+          const racedExisting = inspectExistingDestination(target, linkPath);
+          if (racedExisting !== null) return racedExisting;
+          continue;
+        }
+        if (!SYMLINK_FALLBACK_ERRORS.has(symlinkErr.code)) {
+          throw symlinkErr;
+        }
+        if (options.symlinkOnly) {
+          console.warn(`  ⚠ Symlink failed for ${linkPath} (--symlink requires symlink support)`);
+          return '';
+        }
+        const content = fs.readFileSync(target, 'utf-8');
+        try {
+          fs.writeFileSync(linkPath, HEADER_COMMENT + '\n' + content, {
+            encoding: 'utf8',
+            flag: 'wx',
+          });
+          return 'copied';
+        } catch (copyErr) {
+          if (copyErr.code === 'EEXIST') {
+            const racedExisting = inspectExistingDestination(target, linkPath);
+            if (racedExisting !== null) return racedExisting;
+            continue;
+          }
+          throw copyErr;
+        }
       }
-      // Fall back to copy with header
-      const content = fs.readFileSync(target, 'utf-8');
-      fs.writeFileSync(linkPath, HEADER_COMMENT + '\n' + content, 'utf-8');
-      return 'copied';
     }
+    console.warn(`  ⚠ Could not create ${linkPath} after repeated conflicts; please re-run setup.`);
+    return '';
   } catch (err) {
     console.error(`  ✗ Failed to link/copy ${target} -> ${linkPath}: ${err.message}`);
     return '';

package/lib/upgrade-safety.js

@@ -8,6 +8,14 @@ const { resolvePatchIntentRecords } = require('./patch-intent');
 const { verifyForgeLock, readForgeLock } = require('./forge-lock');
 const { readConfigBackend, resolveIssueBackend } = require('./issue-backend');
 const { detectBeadsJsonlSource } = require('./beads-detect');
+const {
+  FORGE_HOOK_CONTRACT,
+  hasForgeClaudeHooks,
+  hasMultipleHardLinks,
+  HookConfigParseError,
+  renderHookConfig,
+} = require('./hook-renderer');
+const { assertNoAncestorSymlinkEscape, assertNoSymlinkEscape } = require('./protected-state-surfaces');
 
 function checkStatus(ok) {
   return ok ? 'pass' : 'fail';
@@ -55,6 +63,31 @@ function buildSelfHealCandidates(projectRoot) {
       description: 'Create missing Forge audit log file',
     });
   }
+  const claudeDir = path.join(projectRoot, '.claude');
+  if (fs.existsSync(claudeDir)) {
+    const claudeSettings = path.join(claudeDir, 'settings.json');
+    const unsafePath =
+      assertNoAncestorSymlinkEscape(projectRoot, claudeSettings) ||
+      assertNoSymlinkEscape(projectRoot, claudeSettings);
+    if (unsafePath || hasMultipleHardLinks(claudeSettings)) return candidates;
+    const existing = fs.existsSync(claudeSettings) ? fs.readFileSync(claudeSettings, 'utf8') : '';
+    try {
+      if (!hasForgeClaudeHooks(existing, FORGE_HOOK_CONTRACT)) {
+        candidates.push({
+          id: 'claude-hooks',
+          path: '.claude/settings.json',
+          description: 'Merge missing Forge-owned Claude lifecycle hooks',
+        });
+      }
+    } catch (error) {
+      if (!(error instanceof HookConfigParseError)) throw error;
+      candidates.push({
+        id: 'claude-hooks',
+        path: '.claude/settings.json',
+        description: 'Back up malformed Claude settings before hook repair',
+      });
+    }
+  }
   return candidates;
 }
 
@@ -235,6 +268,12 @@ function applySelfHeal(projectRoot, report) {
     applied.push({ path: '.forge/log.jsonl' });
   }
 
+  if (report.selfHealCandidates.some(candidate => candidate.id === 'claude-hooks')) {
+    const result = renderHookConfig({ harness: 'claude', targetRoot: projectRoot });
+    if (result.wrote) applied.push({ path: '.claude/settings.json' });
+    else if (result.backup) applied.push({ path: path.relative(projectRoot, result.backup) });
+  }
+
   return {
     refused: false,
     applied,

package/lib/using-forge.js

@@ -100,10 +100,10 @@ function applyFrontmatterLine(state, line) {
   if (state.inDescription) {
     if (/^\s+\S/.test(line)) {
       state.descParts.push(line.trim());
-    } else if (line.trim() !== '') {
-      state.inDescription = false;
+      return;
     }
-    return;
+    if (line.trim() === '') return;
+    state.inDescription = false;
   }
   // Detect the `name:` key without a regex: SonarCloud flags every /^name:.../ variant for
   // super-linear backtracking. startsWith + slice is behavior-identical — the remainder is
@@ -113,6 +113,15 @@ function applyFrontmatterLine(state, line) {
     if (value) state.name = unquote(value);
     return;
   }
+  if (line.startsWith('invocation:')) {
+    const value = line.slice('invocation:'.length).trim();
+    const quote = value[0];
+    const hasMatchingQuotes = value.length >= 2
+      && (quote === '"' || quote === "'")
+      && value.endsWith(quote);
+    state.invocation = hasMatchingQuotes ? value.slice(1, -1) : value;
+    return;
+  }
   const descMatch = /^description:\s*(.*)$/.exec(line);
   if (descMatch) {
     state.inDescription = true;
@@ -124,10 +133,14 @@ function applyFrontmatterLine(state, line) {
 /** Parse the name and (flattened) description from a SKILL.md frontmatter block. */
 function parseFrontmatter(raw) {
   const block = frontmatterBlock(raw);
-  if (block === null) return { name: null, description: '' };
-  const state = { name: null, descParts: [], inDescription: false };
+  if (block === null) return { name: null, description: '', invocation: 'model' };
+  const state = { name: null, descParts: [], inDescription: false, invocation: 'model' };
   for (const line of block.split(/\r?\n/)) applyFrontmatterLine(state, line);
-  return { name: state.name, description: state.descParts.join(' ').replace(/\s+/g, ' ').trim() };
+  return {
+    name: state.name,
+    description: state.descParts.join(' ').replace(/\s+/g, ' ').trim(),
+    invocation: state.invocation,
+  };
 }
 
 /** Read one skill dir into a `{ name, description }` catalog entry, or null when unreadable. */