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

package/lib/protected-state-authority.js

@@ -0,0 +1,305 @@
+'use strict';
+
+// The ignored JSONL audit log is visibility-only. Workflow write authority is
+// an append-only Kernel capability scoped to one worktree and consumed once.
+
+const { randomUUID } = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveOwnedKernel, closeIfOwned } = require('./kernel/owned-kernel');
+const { hashProtectedContent, normalizeRepoPath } = require('./protected-state-surfaces');
+
+const PROTECTED_STATE_ENTITY_TYPE = 'protected_state';
+const PROTECTED_STATE_AUTHORIZATION_ISSUED = 'protected_state.authorization.issued';
+const PROTECTED_STATE_AUTHORIZATION_CONSUMED = 'protected_state.authorization.consumed';
+const PROTECTED_STATE_AUTHORIZATION_VERSION = 1;
+const PROTECTED_STATE_AUTHORIZATION_ORIGIN = 'cli';
+const NPM_WORKFLOW_SOURCE_COMMAND = 'forge release generate-npm-workflow';
+
+function resolveWorktreeScope(projectRoot, deps = {}) {
+	const resolved = path.resolve(projectRoot);
+	const realpath = deps.realpathSync || fs.realpathSync.native;
+	let canonical;
+	try {
+		canonical = realpath(resolved);
+	} catch {
+		canonical = resolved;
+	}
+	if (process.platform === 'win32') canonical = canonical.toLowerCase();
+	return hashProtectedContent(canonical);
+}
+
+function authorizationEntityId(worktreeScope, filePath) {
+	return `${worktreeScope}:${normalizeRepoPath(filePath)}`;
+}
+
+function parsePayload(row) {
+	try {
+		return row?.payload_json ? JSON.parse(row.payload_json) : (row?.payload || {});
+	} catch {
+		return {};
+	}
+}
+
+function parseAuthorizationEvent(row) {
+	const payload = parsePayload(row);
+	return {
+		eventType: row?.event_type,
+		actor: row?.actor,
+		payloadActor: payload.actor,
+		origin: row?.origin,
+		entityId: row?.entity_id,
+		createdAt: row?.created_at,
+		version: payload.version,
+		capabilityId: payload.capabilityId,
+		path: normalizeRepoPath(payload.path),
+		surface: payload.surface,
+		contentHash: payload.contentHash,
+		operation: payload.operation,
+		sourceCommand: payload.sourceCommand,
+		worktreeScope: payload.worktreeScope,
+	};
+}
+
+function blockedDecision(request, reason) {
+	return {
+		allowed: false,
+		decision: 'blocked',
+		actor: request.actor,
+		path: normalizeRepoPath(request.path),
+		operation: request.operation || 'staged_edit',
+		requiredSurface: request.surface,
+		declaredSurface: request.surface,
+		contentHash: hashProtectedContent(request.content),
+		reason,
+		repairHint: 'Regenerate the protected file through its owning Forge command, then stage that exact output.',
+	};
+}
+
+function evaluateAuthorization(request, rows = []) {
+	const expected = {
+		actor: request.actor,
+		path: normalizeRepoPath(request.path),
+		surface: request.surface,
+		contentHash: hashProtectedContent(request.content),
+		worktreeScope: request.worktreeScope,
+	};
+	const issued = rows
+		.filter(row => row?.event_type === PROTECTED_STATE_AUTHORIZATION_ISSUED)
+		.map(parseAuthorizationEvent);
+	const consumedCapabilities = new Set(rows
+		.filter(row => row?.event_type === PROTECTED_STATE_AUTHORIZATION_CONSUMED)
+		.map(row => parseAuthorizationEvent(row).capabilityId)
+		.filter(Boolean));
+	const active = issued.filter(event => !consumedCapabilities.has(event.capabilityId));
+
+	if (issued.length === 0) {
+		return blockedDecision(request, 'No Forge-owned authorization exists for this protected path and content-bound write.');
+	}
+	if (active.length === 0) {
+		return blockedDecision(request, 'The latest Forge-owned authorization was already consumed; stale and same-content replays are denied.');
+	}
+	if (active.length !== 1) {
+		return blockedDecision(request, 'Protected-state authority is ambiguous because multiple unconsumed authorizations exist; failing closed.');
+	}
+	const latest = active[0];
+
+	const structurallyValid =
+		latest.version === PROTECTED_STATE_AUTHORIZATION_VERSION &&
+		typeof latest.capabilityId === 'string' && latest.capabilityId.length > 0 &&
+		latest.origin === PROTECTED_STATE_AUTHORIZATION_ORIGIN &&
+		latest.actor === latest.payloadActor &&
+		latest.worktreeScope === expected.worktreeScope &&
+		latest.entityId === authorizationEntityId(expected.worktreeScope, latest.path) &&
+		latest.sourceCommand === NPM_WORKFLOW_SOURCE_COMMAND;
+	if (!structurallyValid) {
+		return blockedDecision(request, 'The latest Forge-owned authorization is malformed or was not issued by the owning command.');
+	}
+
+	if (
+		latest.actor !== expected.actor ||
+		latest.path !== expected.path ||
+		latest.surface !== expected.surface ||
+		latest.contentHash !== expected.contentHash
+	) {
+		return blockedDecision(request, 'The latest Forge-owned content-bound authorization does not match this actor, surface, path, and content hash.');
+	}
+
+	return {
+		allowed: true,
+		decision: 'allowed',
+		actor: expected.actor,
+		path: expected.path,
+		operation: request.operation || 'staged_edit',
+		requiredSurface: expected.surface,
+		declaredSurface: expected.surface,
+		contentHash: expected.contentHash,
+		capabilityId: latest.capabilityId,
+		worktreeScope: latest.worktreeScope,
+		reason: 'Staged content matches the latest unconsumed Forge-owned authorization.',
+		repairHint: null,
+	};
+}
+
+async function issueProtectedStateAuthorization(projectRoot, request = {}, options = {}) {
+	const actor = request.actor;
+	const normalizedPath = normalizeRepoPath(request.path);
+	if (!actor || !request.surface || !normalizedPath || request.content === undefined) {
+		throw new TypeError('Protected state authorization requires actor, surface, path, and content');
+	}
+
+	const capabilityId = options.capabilityId || randomUUID();
+	const createdAt = options.now || new Date().toISOString();
+	const worktreeScope = options.worktreeScope || resolveWorktreeScope(projectRoot, options.deps);
+	const entityId = authorizationEntityId(worktreeScope, normalizedPath);
+	const event = {
+		entity_type: PROTECTED_STATE_ENTITY_TYPE,
+		entity_id: entityId,
+		event_type: PROTECTED_STATE_AUTHORIZATION_ISSUED,
+		idempotency_key: `${PROTECTED_STATE_AUTHORIZATION_ISSUED}:${capabilityId}`,
+		expected_revision: 0,
+		actor,
+		origin: PROTECTED_STATE_AUTHORIZATION_ORIGIN,
+		payload: {
+			version: PROTECTED_STATE_AUTHORIZATION_VERSION,
+			capabilityId,
+			actor,
+			path: normalizedPath,
+			surface: request.surface,
+			contentHash: hashProtectedContent(request.content),
+			worktreeScope,
+			operation: request.operation || 'generate',
+			sourceCommand: request.sourceCommand || NPM_WORKFLOW_SOURCE_COMMAND,
+		},
+		created_at: createdAt,
+	};
+
+	const kernel = await resolveOwnedKernel(projectRoot, options.deps);
+	try {
+		const existingRows = await kernel.driver.listKernelEvents(
+			PROTECTED_STATE_ENTITY_TYPE,
+			entityId,
+			{},
+			kernel.config,
+		);
+		const consumedCapabilities = new Set((existingRows || [])
+			.filter(row => row?.event_type === PROTECTED_STATE_AUTHORIZATION_CONSUMED)
+			.map(row => parseAuthorizationEvent(row).capabilityId)
+			.filter(Boolean));
+		const activeCapabilities = (existingRows || [])
+			.filter(row => row?.event_type === PROTECTED_STATE_AUTHORIZATION_ISSUED)
+			.map(parseAuthorizationEvent)
+			.filter(existing => existing.capabilityId && !consumedCapabilities.has(existing.capabilityId));
+		for (const existing of activeCapabilities) {
+			await kernel.driver.insertKernelEvent({
+				entity_type: PROTECTED_STATE_ENTITY_TYPE,
+				entity_id: entityId,
+				event_type: PROTECTED_STATE_AUTHORIZATION_CONSUMED,
+				idempotency_key: `${PROTECTED_STATE_AUTHORIZATION_CONSUMED}:${existing.capabilityId}`,
+				expected_revision: 0,
+				actor,
+				origin: PROTECTED_STATE_AUTHORIZATION_ORIGIN,
+				payload: {
+					version: PROTECTED_STATE_AUTHORIZATION_VERSION,
+					capabilityId: existing.capabilityId,
+					actor,
+					path: normalizedPath,
+					surface: existing.surface,
+					contentHash: existing.contentHash,
+					worktreeScope,
+					operation: 'superseded',
+					sourceCommand: request.sourceCommand || NPM_WORKFLOW_SOURCE_COMMAND,
+				},
+				created_at: createdAt,
+			}, {}, kernel.config);
+		}
+		const inserted = await kernel.driver.insertKernelEvent(event, {}, kernel.config);
+		return { success: true, capabilityId, event: parseAuthorizationEvent(inserted) };
+	} finally {
+		closeIfOwned(kernel);
+	}
+}
+
+async function issueNpmPublishWorkflowAuthorization(projectRoot, params = {}, options = {}) {
+	const {
+		NPM_PUBLISH_WORKFLOW_PATH,
+		renderNpmPublishWorkflow,
+	} = require('./npm-publish-workflow');
+	return issueProtectedStateAuthorization(projectRoot, {
+		actor: params.actor,
+		surface: 'workflows',
+		path: NPM_PUBLISH_WORKFLOW_PATH,
+		content: renderNpmPublishWorkflow(),
+		operation: 'generate_npm_workflow',
+		sourceCommand: NPM_WORKFLOW_SOURCE_COMMAND,
+	}, options);
+}
+
+async function authorizeAndConsumeProtectedStateWrites(projectRoot, requests = [], options = {}) {
+	if (requests.length === 0) return { success: true, decisions: [] };
+	const worktreeScope = options.worktreeScope || resolveWorktreeScope(projectRoot, options.deps);
+	const kernel = await resolveOwnedKernel(projectRoot, options.deps);
+	try {
+		const decisions = [];
+		for (const request of requests) {
+			const normalizedPath = normalizeRepoPath(request.path);
+			const entityId = authorizationEntityId(worktreeScope, normalizedPath);
+			const rows = await kernel.driver.listKernelEvents(
+				PROTECTED_STATE_ENTITY_TYPE,
+				entityId,
+				{},
+				kernel.config,
+			);
+			decisions.push(evaluateAuthorization({
+				...request,
+				path: normalizedPath,
+				worktreeScope,
+			}, rows || []));
+		}
+
+		if (decisions.some(decision => !decision.allowed)) {
+			return { success: false, decisions };
+		}
+
+		for (const decision of decisions) {
+			const createdAt = options.now || new Date().toISOString();
+			await kernel.driver.insertKernelEvent({
+				entity_type: PROTECTED_STATE_ENTITY_TYPE,
+				entity_id: authorizationEntityId(decision.worktreeScope, decision.path),
+				event_type: PROTECTED_STATE_AUTHORIZATION_CONSUMED,
+				idempotency_key: `${PROTECTED_STATE_AUTHORIZATION_CONSUMED}:${decision.capabilityId}`,
+				expected_revision: 0,
+				actor: decision.actor,
+				origin: PROTECTED_STATE_AUTHORIZATION_ORIGIN,
+				payload: {
+					version: PROTECTED_STATE_AUTHORIZATION_VERSION,
+					capabilityId: decision.capabilityId,
+					actor: decision.actor,
+					path: decision.path,
+					surface: decision.requiredSurface,
+					contentHash: decision.contentHash,
+					worktreeScope: decision.worktreeScope,
+					operation: 'staged_edit',
+					sourceCommand: 'scripts/protected-state-check.js',
+				},
+				created_at: createdAt,
+			}, {}, kernel.config);
+		}
+
+		return { success: true, decisions };
+	} finally {
+		closeIfOwned(kernel);
+	}
+}
+
+module.exports = {
+	PROTECTED_STATE_ENTITY_TYPE,
+	PROTECTED_STATE_AUTHORIZATION_ISSUED,
+	PROTECTED_STATE_AUTHORIZATION_CONSUMED,
+	resolveWorktreeScope,
+	authorizationEntityId,
+	parseAuthorizationEvent,
+	evaluateAuthorization,
+	issueNpmPublishWorkflowAuthorization,
+	authorizeAndConsumeProtectedStateWrites,
+};

package/lib/protected-state-surfaces.js

@@ -1,7 +1,17 @@
 const fs = require('node:fs');
 const path = require('node:path');
-const { execFileSync } = require('node:child_process');
+const crypto = require('node:crypto');
 const { redact } = require('./audit-evidence');
+const { appendCappedJsonlRecord } = require('./capped-jsonl-log');
+
+/**
+ * Protected-state decisions are logged locally rather than to the kernel event
+ * stream: kernel events are issue-scoped and async, and this runs inside a
+ * synchronous pre-commit hook that has no issue id and must not open the kernel
+ * SQLite handle. Capped so a repeated blocked commit cannot grow it unbounded.
+ */
+const PROTECTED_STATE_AUDIT_LOG = '.forge/protected-state-audit.jsonl';
+const PROTECTED_STATE_AUDIT_MAX_RECORDS = 500;
 
 function normalizeRepoPath(filePath) {
 	return String(filePath || '')
@@ -10,6 +20,30 @@ function normalizeRepoPath(filePath) {
 		.replace(/\/+/g, '/');
 }
 
+function hashProtectedContent(content) {
+	const bytes = Buffer.isBuffer(content) ? content : Buffer.from(String(content), 'utf8');
+	return `sha256:${crypto.createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+function createProtectedStateAuditRecord({ actor, surface, path: filePath, content, operation = 'generate' }) {
+	if (!actor || !surface || !filePath || content === undefined) {
+		throw new TypeError('Protected state audit record requires actor, surface, path, and content');
+	}
+
+	return {
+		kind: 'protected_state_write',
+		actor,
+		path: normalizeRepoPath(filePath),
+		decision: 'allowed',
+		requiredSurface: surface,
+		declaredSurface: surface,
+		operation,
+		contentHash: hashProtectedContent(content),
+		reason: `Forge API generated content for protected surface: ${surface}.`,
+		repairHint: null,
+	};
+}
+
 function startsWithAny(filePath, prefixes) {
 	return prefixes.some(prefix => filePath === prefix || filePath.startsWith(`${prefix}/`));
 }
@@ -42,13 +76,13 @@ const PROTECTED_SURFACES = [
 				'.forge/agent-log.ndjson',
 				'.beads/interactions.jsonl',
 			].includes(filePath),
-		repairHint: 'append-only logs must be written by the Forge or Beads audit writer; do not rewrite existing log content.',
+		repairHint: 'append-only logs must be written by the Forge audit writer; do not rewrite existing log content.',
 	},
 	{
 		id: 'beads_state',
-		label: 'Beads state',
+		label: 'Legacy Beads state',
 		matches: filePath => startsWithAny(filePath, ['.beads']),
-		repairHint: 'Use bd or Forge issue commands such as bd update, bd close, forge ready, or forge close.',
+		repairHint: 'A legacy .beads directory is import-only state. Import it with `forge migrate --from beads`, then use Forge issue commands such as forge ready or forge close.',
 	},
 	{
 		id: 'forge_config',
@@ -164,8 +198,12 @@ function nearestExistingPath(candidate) {
 	return current;
 }
 
+function realpathNearestExistingPath(candidate) {
+	return fs.realpathSync(nearestExistingPath(candidate));
+}
+
 function assertNoAncestorSymlinkEscape(root, target) {
-	const realRoot = fs.realpathSync(root);
+	const realRoot = realpathNearestExistingPath(root);
 	const existing = nearestExistingPath(path.dirname(target));
 	const existingStat = lstatIfPresent(existing);
 	if (existing !== root && existingStat?.isSymbolicLink()) {
@@ -177,7 +215,7 @@ function assertNoAncestorSymlinkEscape(root, target) {
 		};
 	}
 
-	const realExisting = fs.realpathSync(existing);
+	const realExisting = realpathNearestExistingPath(existing);
 	if (!pathStaysInsideRoot(realRoot, realExisting)) {
 		return {
 			allowed: false,
@@ -191,8 +229,8 @@ function assertNoAncestorSymlinkEscape(root, target) {
 
 function assertNoSymlinkEscape(root, target) {
 	const parent = path.dirname(target);
-	const realRoot = fs.realpathSync(root);
-	const existingParent = fs.existsSync(parent) ? fs.realpathSync(parent) : parent;
+	const realRoot = realpathNearestExistingPath(root);
+	const existingParent = realpathNearestExistingPath(parent);
 	if (!pathStaysInsideRoot(realRoot, existingParent)) {
 		return {
 			allowed: false,
@@ -297,7 +335,7 @@ function writeProtectedFile(projectRoot, filePath, content, options = {}) {
 	}
 
 	fs.writeFileSync(resolved.target, content, options.encoding || 'utf8');
-	return { ...decision, fullPath: resolved.target };
+	return { ...decision, contentHash: hashProtectedContent(content), fullPath: resolved.target };
 }
 
 function buildProtectedStateAuditEvent(decision) {
@@ -313,12 +351,14 @@ function buildProtectedStateAuditEvent(decision) {
 		requiredSurface: decision.requiredSurface,
 		declaredSurface: decision.declaredSurface || null,
 		operation: decision.operation || 'write',
+		contentHash: decision.contentHash || null,
 		reason: decision.reason,
 		repairHint: decision.repairHint,
 		metadata: {
 			actor: decision.actor || 'unknown',
 			path: decision.path,
 			operation: decision.operation || 'write',
+			contentHash: decision.contentHash || null,
 			requiredSurface: decision.requiredSurface,
 			declaredSurface: decision.declaredSurface || null,
 			decision: decision.decision,
@@ -330,51 +370,31 @@ function buildProtectedStateAuditEvent(decision) {
 	return redact(event);
 }
 
+/**
+ * Best-effort: a failed audit write is reported to the caller, never thrown, so
+ * the protected-state decision itself still stands.
+ */
 function recordProtectedStateAuditEvent(decision, options = {}) {
 	const event = buildProtectedStateAuditEvent(decision);
-	const runCommand = options.runCommand || execFileSync;
-	try {
-		const args = [
-			'audit',
-			'record',
-			'--json',
-			'--kind',
-			'protected_state_write',
-			'--model',
-			'forge-protected-state',
-			'--prompt',
-			JSON.stringify({
-				actor: event.actor,
-				path: event.path,
-				operation: event.operation,
-			}),
-			'--response',
-			JSON.stringify({
-				decision: event.decision,
-				requiredSurface: event.requiredSurface,
-				repairHint: event.repairHint,
-			}),
-		];
-
-		if (event.metadata) {
-			args.push('--meta-json', JSON.stringify(event.metadata));
-		}
+	const logPath = path.resolve(options.cwd || process.cwd(), PROTECTED_STATE_AUDIT_LOG);
+	const appendRecord = options.appendRecord || appendCappedJsonlRecord;
 
-		const output = runCommand('bd', args, {
-			cwd: options.cwd || process.cwd(),
-			encoding: 'utf8',
-			stdio: ['ignore', 'pipe', 'pipe'],
-			timeout: options.timeoutMs || 5000,
-		});
-		return { success: true, event, output };
+	try {
+		const record = { ...event, recordedAt: options.now || new Date().toISOString() };
+		appendRecord(logPath, record, options.maxRecords || PROTECTED_STATE_AUDIT_MAX_RECORDS);
+		return { success: true, event, logPath };
 	} catch (error) {
-		return { success: false, event, error: error.message };
+		return { success: false, event, logPath, error: error.message };
 	}
 }
 
 module.exports = {
 	PROTECTED_SURFACES,
+	PROTECTED_STATE_AUDIT_LOG,
+	PROTECTED_STATE_AUDIT_MAX_RECORDS,
 	normalizeRepoPath,
+	hashProtectedContent,
+	createProtectedStateAuditRecord,
 	resolveRepoRelativePath,
 	lstatIfPresent,
 	assertNoAncestorSymlinkEscape,

package/lib/release-readiness.js

@@ -413,13 +413,27 @@ function readSyncManifestScanRoots(projectRoot) {
   }
 }
 
+// Scan roots reach here in whatever spelling their source used — a plugin manifest
+// directory entry, a sync-manifest file, an explicit scanRoots option — so they are
+// normalized once, at the single place they are resolved. walkFiles would join a trailing
+// separator away and scan the tree regardless, while isBdCensusPath would build `root//`
+// and match nothing under it; normalizing here is what keeps the census and the
+// pre-commit predicate from disagreeing about which files count.
+function normalizeScanRoot(root) {
+  if (typeof root !== 'string' || root.length === 0) {
+    return '';
+  }
+  return normalizeRepoPath(root).replace(/[/\\]+$/, '');
+}
+
 function getScanRoots(projectRoot, options = {}) {
   const roots = options.scanRoots || getDefaultScanRoots(projectRoot);
   return [
-    ...new Set([
-      ...roots,
-      ...readSyncManifestScanRoots(projectRoot),
-    ]),
+    ...new Set(
+      [...roots, ...readSyncManifestScanRoots(projectRoot)]
+        .map(normalizeScanRoot)
+        .filter(Boolean),
+    ),
   ];
 }
 
@@ -557,6 +571,38 @@ function auditBdCallSites(projectRoot, options = {}) {
   };
 }
 
+// Would a change to this repo-relative path shift the bd call-site census?
+//
+// The pre-commit auto-heal (scripts/sync-d20-audit.js) asks this before doing any work,
+// so it must answer exactly what auditBdCallSites would scan. It is therefore assembled
+// from that walk's own pieces — getScanRoots, shouldSkipRelativePath, isTextFile,
+// SKIP_DIR_NAMES — rather than a parallel list that could drift from the gate.
+function isBdCensusPath(projectRoot, filePath, options = {}) {
+  const relativePath = safeNormalizeRepoPath(projectRoot, filePath);
+  if (!relativePath || shouldSkipRelativePath(relativePath) || !isTextFile(relativePath, projectRoot)) {
+    return false;
+  }
+
+  // getScanRoots already returns normalized roots — re-normalizing here would be a second
+  // copy of that rule, free to drift from the one auditBdCallSites walks.
+  return getScanRoots(projectRoot, options)
+    .some(root => {
+      // walkFiles applies no directory skips to a root that is itself a file.
+      if (relativePath === root) {
+        return true;
+      }
+      if (!relativePath.startsWith(`${root}/`)) {
+        return false;
+      }
+      // Below a directory root it refuses to descend into skipped directories.
+      return !relativePath
+        .slice(root.length + 1)
+        .split('/')
+        .slice(0, -1)
+        .some(directory => SKIP_DIR_NAMES.has(directory));
+    });
+}
+
 function readRepoFile(projectRoot, relativePath) {
   const fullPath = absolutePath(projectRoot, relativePath);
   return fs.existsSync(fullPath) ? fs.readFileSync(fullPath, 'utf8') : '';
@@ -2096,6 +2142,7 @@ module.exports = {
   auditBdCallSites,
   buildReadinessReport,
   canonicalizeAuditArtifact,
+  isBdCensusPath,
   renderBdCallSiteAuditMarkdown,
   renderReadinessReport,
   writeAuditArtifact,

package/lib/shell-utils.js

@@ -105,7 +105,7 @@ function secureExecFileSync(command, args = [], options = {}) {
       // metacharacters, so fold them into a single command line and pass no args array —
       // identical execution through cmd.exe (npm.cmd/npx.cmd shims), no deprecation warning.
       const commandLine = [command, ...args].join(' ');
-      return _execFileSync(commandLine, [], { ...execOptions, shell: true });
+      return _execFileSync(commandLine, [], { env: process.env, ...execOptions, shell: true });
     }
     return _execFileSync(spec.file, args, execOptions);
   }

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;
 }