forge-workflow 0.1.0-beta.3 → 0.1.0-beta.5

package/lib/skills-sync.js

@@ -34,6 +34,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { parseFrontmatter } = require('./using-forge');
 
 /** Canonical skills live under this directory at the repo/package root. */
 const CANONICAL_SKILLS_DIR = 'skills';
@@ -71,7 +72,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 +89,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));

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/status/identity.js

@@ -0,0 +1,46 @@
+'use strict';
+
+const { secureExecFileSync } = require('../shell-utils.js');
+
+// Developer identity for the status read model. Extracted from the retired
+// lib/status/beads-snapshot.js: the identity lookup is backend-agnostic (it reads
+// git config, never an issue store), so it outlived the Beads reader it shipped in.
+// Kept in its own module so lib/status/snapshot.js stays read-model-only.
+
+/**
+ * Read a single git config value, or '' when git is unavailable or the key is unset.
+ * Never throws — status must render even in a non-git directory.
+ *
+ * @param {string} projectRoot
+ * @param {string} key — git config key (e.g. 'user.email')
+ * @returns {string}
+ */
+function getGitConfig(projectRoot, key) {
+	try {
+		return secureExecFileSync('git', ['config', key], {
+			encoding: 'utf8',
+			cwd: projectRoot,
+			stdio: ['pipe', 'pipe', 'pipe'],
+		}).trim();
+	} catch (_error) {
+		return '';
+	}
+}
+
+/**
+ * The current developer's git identity, used to match claims to "my" work.
+ *
+ * @param {string} projectRoot
+ * @returns {{ email: string, name: string }}
+ */
+function getDeveloperIdentity(projectRoot) {
+	return {
+		email: getGitConfig(projectRoot, 'user.email'),
+		name: getGitConfig(projectRoot, 'user.name'),
+	};
+}
+
+module.exports = {
+	getDeveloperIdentity,
+	getGitConfig,
+};

package/lib/status/presenter.js

@@ -173,43 +173,8 @@ function buildPersonalStatusJson({ context, snapshot, workflowResult = null }) {
 	};
 }
 
-function formatBoard({ context, snapshot }) {
-	return [
-		'',
-		'Team Runtime Board',
-		`Source: local Beads runtime state`,
-		`Branch: ${context.branch}`,
-		`Working tree: ${context.workingTree.summary}`,
-		'',
-		...buildSection('Active', (snapshot.active || []).map(issue => formatIssue(issue, { includeStatus: true })), { limit: DEFAULT_SECTION_LIMIT }),
-		...buildSection('Ready', (snapshot.ready || []).map(issue => formatIssue(issue)), { limit: DEFAULT_SECTION_LIMIT }),
-		...buildSection('Blocked', (snapshot.blocked || []).map(issue => formatIssue(issue, { includeStatus: true })), { limit: DEFAULT_SECTION_LIMIT }),
-		...buildSection('Stale', (snapshot.stale || []).map(issue => formatIssue(issue, { includeStatus: true })), { limit: DEFAULT_SECTION_LIMIT }),
-		...buildSection('Parked', (snapshot.parked || []).map(issue => formatIssue(issue, { includeStatus: true })), { limit: DEFAULT_SECTION_LIMIT }),
-		...buildSection('Recent Completions', (snapshot.recentCompleted || []).map(issue => formatIssue(issue)), { limit: DEFAULT_SECTION_LIMIT }),
-		...buildSection('Limits', snapshot.limits || []),
-	].join('\n');
-}
-
-function buildBoardJson({ context, snapshot }) {
-	return {
-		context,
-		board: {
-			active: (snapshot.active || []).map(toIssueSummary),
-			ready: (snapshot.ready || []).map(toIssueSummary),
-			blocked: (snapshot.blocked || []).map(toIssueSummary),
-			stale: (snapshot.stale || []).map(toIssueSummary),
-			parked: (snapshot.parked || []).map(toIssueSummary),
-			recentCompleted: (snapshot.recentCompleted || []).map(toIssueSummary),
-		},
-		limits: snapshot.limits || [],
-	};
-}
-
 module.exports = {
-	buildBoardJson,
 	buildPersonalStatusJson,
-	formatBoard,
 	formatRunNextLines,
 	formatZeroArgStatus,
 	toIssueSummary,

package/lib/status/snapshot.js

@@ -2,15 +2,14 @@
 
 const { resolveIssueBackend } = require('../issue-backend.js');
 const { runIssueOperation: defaultRunIssueOperation } = require('../forge-issues.js');
-const { readBeadsSnapshot, getDeveloperIdentity } = require('./beads-snapshot.js');
+const { getDeveloperIdentity } = require('./identity.js');
 
 // Kernel status vocabulary (taxonomy-validator): 'open', 'in_progress', 'review',
 // the parked 'backlog', and the terminal 'done' / 'cancelled'. `ready` / `blocked`
 // are DERIVED read-model facts, never stored. An issue is treated as active here when
 // it is OPEN and carries a live claim (claimed_by); parked (`backlog`) work is its own
 // bucket so it stays visible instead of vanishing between ready and done. These buckets
-// mirror the shape readBeadsSnapshot produces so lib/status/presenter.js consumes
-// either backend's snapshot identically.
+// are the contract lib/status/presenter.js renders against.
 const KERNEL_LIMITS = Object.freeze([
 	'Reads Forge Kernel issue authority (ready/blocked/stale/active).',
 	'Does not read GitHub review, CI, project, or sync freshness state.',
@@ -102,7 +101,7 @@ function emptyKernelSnapshot(developer) {
  * @param {object} [options]
  * @param {function} [options.runIssueOperation] — injectable kernel read (tests)
  * @param {object} [options.env]
- * @returns {Promise<object>} snapshot shaped like readBeadsSnapshot's output
+ * @returns {Promise<object>} snapshot in the presenter's bucket contract
  */
 async function readKernelSnapshot(projectRoot, options = {}) {
 	const runIssueOperation = options.runIssueOperation || defaultRunIssueOperation;
@@ -153,29 +152,25 @@ async function readKernelSnapshot(projectRoot, options = {}) {
 }
 
 /**
- * Read the personal/board status snapshot from the active issue backend. Reads the
- * Kernel by default (the flagship `forge status` view); reads Beads only when Beads is
- * explicitly selected (--issue-backend beads / FORGE_ISSUE_BACKEND=beads /
- * issueBackend: beads in .forge/config.yaml). Resolution reuses lib/issue-backend.js
- * so the snapshot never drifts from the issue commands' backend authority.
+ * Read the personal/board status snapshot from the Kernel — the only issue backend.
+ *
+ * A repo that still carries the retired `issueBackend: beads` signal alongside an
+ * unmigrated `.beads/*.jsonl` store now renders the (empty) kernel board rather than
+ * the legacy Beads one; `forge upgrade`'s advisory is what points those users at
+ * `forge migrate --from beads`.
  *
  * @param {string} projectRoot
- * @param {object} [options] — forwarded to the backend reader; `issueBackend` selects
- *   an explicit backend, `env` overrides process.env, `backend` short-circuits resolution.
+ * @param {object} [options] — forwarded to the backend reader; `env` overrides
+ *   process.env, `backend` short-circuits resolution entirely.
  * @returns {Promise<object>} snapshot for lib/status/presenter.js
  */
 async function readStatusSnapshot(projectRoot, options = {}) {
 	const backend = options.backend || resolveIssueBackend({
-		deps: options.issueBackend ? { issueBackend: options.issueBackend } : {},
 		env: options.env || process.env,
 		projectRoot,
 		warn: () => {},
 	});
 
-	if (backend === 'beads') {
-		return readBeadsSnapshot(projectRoot, options);
-	}
-
 	return readKernelSnapshot(projectRoot, { ...options, backend });
 }
 

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;
 }
 
@@ -67,12 +100,13 @@ function safeConfigBackend(projectRoot) {
 }
 
 // Detect the 0.0.10 -> current breaking boundary that hides a returning user's
-// issues (kernel issue a5399f3d): a `.beads/*.jsonl` store still present while the
-// default backend has flipped to the Kernel. `needsMigration` is true only when
-// the user has NOT explicitly opted back into Beads — via `.forge/config.yaml`
-// OR `FORGE_ISSUE_BACKEND` — so the advisory respects the SAME env+config opt-in
-// the issue-path nudge does (both resolve through resolveIssueBackend). Uses the
-// single shared detector so the two surfaces cannot drift.
+// issues (kernel issue a5399f3d): a `.beads/*.jsonl` store still present now that
+// the Kernel is the only backend. There is no longer any way to opt back into
+// Beads, so a leftover `issueBackend: beads` in `.forge/config.yaml` (or
+// FORGE_ISSUE_BACKEND) can no longer suppress this advisory — resolveIssueBackend
+// answers 'kernel' regardless, which is precisely when the user needs to migrate.
+// `configBackend` is still reported so the surface can name the stale setting.
+// Uses the single shared detector so the two surfaces cannot drift.
 function buildBeadsMigrationSummary(projectRoot, env = process.env) {
   const jsonlPresent = detectBeadsJsonlSource(projectRoot) !== null;
   const configBackend = safeConfigBackend(projectRoot);
@@ -179,13 +213,11 @@ function appendBeadsMigration(lines, beadsMigration) {
   lines.push(
     '',
     'Breaking change since 0.0.10 — action required',
-    'Detected a Beads issue store (.beads/*.jsonl). Forge now defaults to the Kernel',
+    'Detected a Beads issue store (.beads/*.jsonl). The Kernel is now the only',
     'issue backend, so these issues will NOT appear until migrated (your data is safe',
     'on disk in the meantime). To migrate:',
     '  forge migrate --from beads   # import your Beads issues into the Kernel',
     '  forge setup                  # (re)wire hooks + provision the Kernel store',
-    'Prefer to stay on Beads? Set `issueBackend: beads` in .forge/config.yaml '
-    + '(or FORGE_ISSUE_BACKEND=beads).',
   );
 }
 
@@ -236,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,