forge-workflow 0.0.10 → 0.1.0-beta.2

package/lib/audit-evidence.js

@@ -0,0 +1,282 @@
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const VERDICT_LABELS = {
+	PASS: 'good',
+	FAIL: 'bad',
+};
+
+const REVIEWER_ROLES = new Set(['spec_reviewer', 'quality_reviewer']);
+const SECRET_KEY_PATTERN = /(api(?:[_-]|\s)?key|authorization|credential|password|private(?:[_-]|\s)?key|secret|token)/i;
+const SECRET_TEXT_KEY_PATTERN = String.raw`(?:api(?:[_-]|\s)?key|authorization|credential|password|private(?:[_-]|\s)?key|secret|token)`;
+const SECRET_TEXT_PATTERNS = [
+	{
+		pattern: /\bBearer\s+\S+/gi,
+		replace: () => 'Bearer [REDACTED]',
+	},
+	{
+		pattern: new RegExp(`(\\b${SECRET_TEXT_KEY_PATTERN}\\b\\s*=\\s*)([^&,\r\n]+)`, 'gi'),
+		replace: (_match, prefix) => `${prefix}[REDACTED]`,
+	},
+	{
+		pattern: new RegExp(`(\\b${SECRET_TEXT_KEY_PATTERN}\\b\\s+is\\s+)([^&,\r\n]+)`, 'gi'),
+		replace: (_match, prefix) => `${prefix}[REDACTED]`,
+	},
+	{
+		pattern: new RegExp(
+			`(\\b${SECRET_TEXT_KEY_PATTERN}\\b\\s+)(?!is\\b)([^&,\r\n]*?)(?=\\s+\\b${SECRET_TEXT_KEY_PATTERN}\\b\\s+|[&,\r\n]|$)`,
+			'gi'
+		),
+		replace: (_match, prefix) => `${prefix}[REDACTED]`,
+	},
+	{
+		pattern: new RegExp(
+			`((?:"|')?${SECRET_TEXT_KEY_PATTERN}(?:"|')?\\s*:\\s*)(?:"[^"]*"|'[^']*'|[^,}\\]\r\n]+)`,
+			'gi'
+		),
+		replace: (_match, prefix) => `${prefix}"[REDACTED]"`,
+	},
+	/\bsk-[A-Za-z0-9_-]{8,}\b/g,
+];
+
+function defaultRunCommand(command, args, options = {}) {
+	return execFileSync(command, args, {
+		cwd: options.cwd || process.cwd(),
+		encoding: 'utf8',
+		input: options.input,
+		timeout: options.timeout || 120000,
+	});
+}
+
+function redactString(value) {
+	return SECRET_TEXT_PATTERNS.reduce(
+		(current, entry) => {
+			if (entry && typeof entry === 'object' && !(entry instanceof RegExp)) {
+				return current.replace(entry.pattern, entry.replace);
+			}
+			return current.replace(entry, () => '[REDACTED]');
+		},
+		value,
+	);
+}
+
+function redact(value, key = '') {
+	if (SECRET_KEY_PATTERN.test(key)) {
+		return '[REDACTED]';
+	}
+
+	if (typeof value === 'string') {
+		return redactString(value);
+	}
+
+	if (Array.isArray(value)) {
+		return value.map(item => redact(item));
+	}
+
+	if (value && typeof value === 'object') {
+		return Object.fromEntries(
+			Object.entries(value).map(([entryKey, entryValue]) => [entryKey, redact(entryValue, entryKey)]),
+		);
+	}
+
+	return value;
+}
+
+function asJsonString(value) {
+	if (typeof value === 'string') return redactString(value);
+	return JSON.stringify(redact(value));
+}
+
+function buildSubagentAuditPayload(event) {
+	if (!event || typeof event !== 'object') {
+		throw new TypeError('Audit event must be an object');
+	}
+	if (!event.command) {
+		throw new TypeError('Audit event command is required');
+	}
+	if (!event.role) {
+		throw new TypeError('Audit event role is required');
+	}
+
+	const metadata =
+		event.metadata && typeof event.metadata === 'object' && !Array.isArray(event.metadata)
+			? event.metadata
+			: {};
+
+	return {
+		kind: 'llm_call',
+		command: event.command,
+		issueId: event.issueId,
+		role: event.role,
+		phase: event.phase,
+		taskId: event.taskId,
+		taskTitle: event.taskTitle,
+		model: event.model || 'unknown',
+		prompt: asJsonString({
+			command: event.command,
+			role: event.role,
+			phase: event.phase,
+			taskId: event.taskId,
+			taskTitle: event.taskTitle,
+			content: event.prompt || '',
+		}),
+		response: asJsonString({
+			command: event.command,
+			role: event.role,
+			verdict: event.verdict || 'UNKNOWN',
+			content: event.response || '',
+		}),
+		metadata: redact(metadata),
+		verdict: event.verdict,
+	};
+}
+
+function parseRecordId(output, { requireJson = false } = {}) {
+	if (!output) return null;
+	try {
+		const parsed = JSON.parse(output);
+		return typeof parsed.id === 'string' ? parsed.id : null;
+	} catch (_error) {
+		if (requireJson) return null;
+		const match = /\bint-[A-Za-z0-9_-]+\b/.exec(String(output));
+		return match ? match[0] : null;
+	}
+}
+
+function hasAuditMetaJsonSupport(runCommand = defaultRunCommand, options = {}) {
+	const output = runCommand('bd', ['audit', 'record', '--help'], options);
+	return String(output).includes('--meta-json');
+}
+
+function writeFallbackMetadata(payload, entryId, options) {
+	if (!entryId || !payload.metadata || Object.keys(payload.metadata).length === 0) {
+		return null;
+	}
+
+	const cwd = options.cwd || process.cwd();
+	const fsImpl = options.fs || fs;
+	const forgeDir = path.join(cwd, '.forge').replace(/\\/g, '/');
+	const logPath = path.join(forgeDir, 'log.jsonl').replace(/\\/g, '/');
+	const line = {
+		kind: 'forge.auditEvidence',
+		sourceOfTruth: 'beads',
+		beadsEntryId: entryId,
+		command: redact(payload.command),
+		role: redact(payload.role),
+		phase: redact(payload.phase),
+		taskId: redact(payload.taskId),
+		taskTitle: redact(payload.taskTitle),
+		metadata: redact(payload.metadata),
+	};
+
+	try {
+		fsImpl.mkdirSync(forgeDir, { recursive: true });
+		fsImpl.appendFileSync(logPath, `${JSON.stringify(line)}\n`);
+		return { path: logPath, line };
+	} catch (error) {
+		return { path: logPath, line, skipped: true, error: error.message };
+	}
+}
+
+function recordSubagentAuditEvent(event, options = {}) {
+	const payload = buildSubagentAuditPayload(event);
+	const runCommand = options.runCommand || defaultRunCommand;
+	const metaJsonSupported =
+		typeof options.metaJsonSupported === 'boolean'
+			? options.metaJsonSupported
+			: hasAuditMetaJsonSupport(runCommand, { cwd: options.cwd || process.cwd() });
+	const args = [
+		'audit',
+		'record',
+		'--json',
+		'--kind',
+		'llm_call',
+	];
+
+	if (payload.issueId) {
+		args.push('--issue-id', payload.issueId);
+	}
+
+	args.push(
+		'--model',
+		payload.model,
+		'--prompt',
+		payload.prompt,
+		'--response',
+		payload.response,
+	);
+
+	if (metaJsonSupported && Object.keys(payload.metadata).length > 0) {
+		args.push('--meta-json', JSON.stringify(payload.metadata));
+	}
+
+	const output = runCommand('bd', args, { cwd: options.cwd || process.cwd() });
+	const entryId = parseRecordId(output, { requireJson: true });
+	const fallback = metaJsonSupported ? null : writeFallbackMetadata(payload, entryId, options);
+
+	return {
+		success: Boolean(entryId),
+		entryId,
+		output,
+		payload,
+		fallback,
+	};
+}
+
+function labelSubagentAuditEvent(entryId, event, options = {}) {
+	const verdict = String(event?.verdict || '').toUpperCase();
+	const role = event?.role;
+	const label = VERDICT_LABELS[verdict];
+
+	if (!entryId || !REVIEWER_ROLES.has(role) || !label) {
+		return { skipped: true };
+	}
+
+	const runCommand = options.runCommand || defaultRunCommand;
+	const reason = `${role} verdict: ${verdict}`;
+	let output;
+	try {
+		output = runCommand('bd', [
+			'audit',
+			'label',
+			entryId,
+			'--json',
+			'--label',
+			label,
+			'--reason',
+			reason,
+		], { cwd: options.cwd || process.cwd() });
+	} catch (error) {
+		return {
+			success: false,
+			label,
+			error: error.message,
+		};
+	}
+
+	const labeledEntryId = parseRecordId(output, { requireJson: true });
+
+	return {
+		success: labeledEntryId === entryId,
+		label,
+		entryId: labeledEntryId,
+		output,
+	};
+}
+
+function recordAndLabelSubagentAuditEvent(event, options = {}) {
+	const record = recordSubagentAuditEvent(event, options);
+	const label = labelSubagentAuditEvent(record.entryId, event, options);
+	return { record, label };
+}
+
+module.exports = {
+	VERDICT_LABELS,
+	buildSubagentAuditPayload,
+	recordSubagentAuditEvent,
+	labelSubagentAuditEvent,
+	recordAndLabelSubagentAuditEvent,
+	hasAuditMetaJsonSupport,
+	redact,
+};

package/lib/beads-setup.js

@@ -12,6 +12,13 @@ const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const { secureExecFileSync } = require('./shell-utils');
 
+const BEADS_LOCAL_EXCLUDE_LINES = [
+  '# Forge local Beads state',
+  '.beads/',
+  '.dolt/',
+  '.beads-credential-key'
+];
+
 function isIgnorableFsError(error) {
   return ['EACCES', 'ENOENT', 'ENOTDIR', 'EPERM'].includes(error?.code);
 }
@@ -103,6 +110,10 @@ function writeBeadsGitignore(projectRoot) {
   fs.mkdirSync(beadsDir, { recursive: true });
 
   const gitignoreContent = [
+    '# Beads runtime, export, and backup state is local',
+    '*',
+    '!.gitignore',
+    '',
     '# Dolt database files (binary, not suitable for git)',
     'dolt/',
     '*.db',
@@ -117,6 +128,108 @@ function writeBeadsGitignore(projectRoot) {
   );
 }
 
+function resolveGitInfoExcludePath(projectRoot) {
+  try {
+    const gitExcludePath = secureExecFileSync(resolveCommand('git'), ['rev-parse', '--git-path', 'info/exclude'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    }).trim();
+
+    if (gitExcludePath) {
+      return path.isAbsolute(gitExcludePath)
+        ? gitExcludePath
+        : path.resolve(projectRoot, gitExcludePath);
+    }
+  } catch (error) {
+    if (!isRecoverableCommandError(error)) {
+      throw error;
+    }
+  }
+
+  return path.join(projectRoot, '.git', 'info', 'exclude');
+}
+
+function untrackExistingBeadsState(projectRoot) {
+  let tracked;
+  try {
+    tracked = secureExecFileSync(resolveCommand('git'), [
+      'ls-files',
+      '-z',
+      '--',
+      '.beads',
+      '.dolt',
+      '.beads-credential-key'
+    ], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    });
+  } catch (error) {
+    if (!isRecoverableCommandError(error)) {
+      throw error;
+    }
+    return;
+  }
+
+  if (!tracked) {
+    return;
+  }
+
+  try {
+    secureExecFileSync(resolveCommand('git'), [
+      'rm',
+      '--cached',
+      '-r',
+      '-f',
+      '--ignore-unmatch',
+      '--',
+      '.beads',
+      '.dolt',
+      '.beads-credential-key'
+    ], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    });
+  } catch (error) {
+    if (!isRecoverableCommandError(error)) {
+      throw error;
+    }
+  }
+}
+
+/**
+ * Add local-only Git exclude rules for Beads state.
+ *
+ * Uses `.git/info/exclude` instead of the tracked `.gitignore` so `forge setup`
+ * does not dirty downstream repositories just to keep Beads runtime files local.
+ * Existing tracked Beads state is removed from the Git index only, leaving local
+ * files in place for the Beads runtime.
+ *
+ * @param {string} projectRoot - Absolute path to the project root
+ */
+function ensureBeadsGitExclude(projectRoot) {
+  const excludePath = resolveGitInfoExcludePath(projectRoot);
+  fs.mkdirSync(path.dirname(excludePath), { recursive: true });
+
+  const existing = fs.existsSync(excludePath)
+    ? fs.readFileSync(excludePath, 'utf8')
+    : '';
+  const existingLines = new Set(existing.split(/\r?\n/));
+  const missingLines = BEADS_LOCAL_EXCLUDE_LINES.filter((line) => !existingLines.has(line));
+
+  if (missingLines.length === 0) {
+    untrackExistingBeadsState(projectRoot);
+    return;
+  }
+
+  const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
+  const spacer = existing.trim() ? '\n' : '';
+  fs.appendFileSync(excludePath, `${prefix}${spacer}${missingLines.join('\n')}\n`, 'utf8');
+  untrackExistingBeadsState(projectRoot);
+}
+
 /**
  * Check whether Beads is properly initialized in a project.
  *
@@ -334,6 +447,13 @@ function safeBeadsInit(projectRoot, options = {}) {
   const warnings = [];
   const errors = [];
 
+  // Keep Beads runtime/export state local even when the tracker already exists.
+  try {
+    ensureBeadsGitExclude(projectRoot);
+  } catch (err) {
+    warnings.push(`Failed to write local Beads git exclude rules: ${err.message}`);
+  }
+
   // (a) Check if already initialized — idempotent skip
   if (isBeadsInitialized(projectRoot)) {
     return {
@@ -410,6 +530,7 @@ module.exports = {
   sanitizePrefix,
   writeBeadsConfig,
   writeBeadsGitignore,
+  ensureBeadsGitExclude,
   isBeadsInitialized,
   readBeadsDatabaseName,
   preSeedJsonl,

package/lib/beads-sync-scaffold.js

@@ -3,6 +3,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
+const { cleanupDeprecatedSyncFiles } = require('./deprecated-sync-cleanup');
 
 const DEFAULT_BEADS_VERSION = '1.0.0';
 
@@ -141,119 +142,41 @@ function templateWorkflows(workflowDir, branch, beadsVersion, createdFiles = [])
   }
 }
 
-/**
- * @typedef {Object} ScaffoldResult
- * @property {string[]} filesCreated - Relative paths of files written (new or overwritten)
- * @property {string[]} filesSkipped - Relative paths of files that already existed and were preserved
- */
+function cleanupDeprecatedBeadsSync(projectRoot, options = {}) {
+  return cleanupDeprecatedSyncFiles(projectRoot, options);
+}
 
 /**
- * Copy a single file from src to dest, creating parent directories as needed.
- *
- * @param {string} src - Absolute source path
- * @param {string} dest - Absolute destination path
- * @returns {void}
+ * @typedef {Object} ScaffoldResult
+ * @property {string[]} filesCreated - Always empty; retained for deprecated API compatibility.
+ * @property {string[]} filesSkipped - Always empty; retained for deprecated API compatibility.
+ * @property {string[]} filesRemoved - Relative paths of deprecated generated sync files removed.
+ * @property {boolean} deprecated - Indicates the legacy scaffold path is deprecated.
+ * @property {string} message - Deprecation guidance for future sync direction.
  */
-function copyFileWithDirs(src, dest) {
-  fs.mkdirSync(path.dirname(dest), { recursive: true });
-  fs.copyFileSync(src, dest);
-}
 
 /**
- * Scaffold Beads sync workflows and scripts to the user's project.
+ * Deprecated compatibility shim for removed Beads/GitHub sync scaffolding.
  *
- * Copies workflow templates, sync modules, config, and mapping stub into
- * the project's `.github/` tree from the forge package source.
+ * Performs cleanup of generated legacy sync artifacts only. User-owned files
+ * at matching paths are preserved unless their content matches known generated
+ * templates.
  *
  * @param {string} projectRoot - Absolute path to the user's project root
  * @param {string} packageDir - Absolute path to the forge package install location
  * @param {Object} [_options={}] - Reserved for future options
- * @returns {ScaffoldResult}
+ * @returns {ScaffoldResult} Deprecated cleanup result.
  */
 function scaffoldBeadsSync(projectRoot, packageDir, _options = {}) {
-  /** @type {string[]} */
-  const filesCreated = [];
-  /** @type {string[]} */
-  const filesSkipped = [];
-
-  const githubDir = path.join(projectRoot, '.github');
-
-  // --- Step a: Copy workflow templates ---
-  const workflowNames = ['github-to-beads.yml', 'beads-to-github.yml'];
-  const srcWorkflowsDir = path.join(packageDir, '.github', 'workflows');
-
-  for (const name of workflowNames) {
-    const src = path.join(srcWorkflowsDir, name);
-    const relPath = `.github/workflows/${name}`;
-    const dest = path.join(projectRoot, '.github', 'workflows', name);
-
-    if (!fs.existsSync(src)) continue;
-    if (fs.existsSync(dest)) {
-      filesSkipped.push(relPath);
-    } else {
-      copyFileWithDirs(src, dest);
-      filesCreated.push(relPath);
-    }
-  }
-
-  // --- Step b: Copy sync modules ---
-  const srcSyncDir = path.join(packageDir, 'scripts', 'github-beads-sync');
-  const destSyncDir = path.join(githubDir, 'scripts', 'beads-sync');
-
-  if (fs.existsSync(srcSyncDir)) {
-    const entries = fs.readdirSync(srcSyncDir);
-    for (const entry of entries) {
-      const srcFile = path.join(srcSyncDir, entry);
-      const stat = fs.statSync(srcFile);
-      if (stat.isFile()) {
-        const relPath = `.github/scripts/beads-sync/${entry}`;
-        const dest = path.join(destSyncDir, entry);
-        if (fs.existsSync(dest)) {
-          filesSkipped.push(relPath);
-        } else {
-          copyFileWithDirs(srcFile, dest);
-          filesCreated.push(relPath);
-        }
-      }
-    }
-  }
-
-  // --- Step c: Create beads-sync-config.json ---
-  const configRelPath = '.github/beads-sync-config.json';
-  const configDest = path.join(githubDir, 'beads-sync-config.json');
-  const srcConfig = path.join(packageDir, 'scripts', 'github-beads-sync.config.json');
-
-  if (fs.existsSync(configDest)) {
-    filesSkipped.push(configRelPath);
-  } else if (fs.existsSync(srcConfig)) {
-    copyFileWithDirs(srcConfig, configDest);
-    filesCreated.push(configRelPath);
-  } else {
-    // Create a sensible default config
-    const defaultConfig = {
-      defaultType: 'task',
-      defaultPriority: 2,
-      mapAssignee: true,
-      publicRepoGate: 'none'
-    };
-    fs.mkdirSync(path.dirname(configDest), { recursive: true });
-    fs.writeFileSync(configDest, JSON.stringify(defaultConfig, null, 2) + '\n');
-    filesCreated.push(configRelPath);
-  }
-
-  // --- Step d: Create beads-mapping.json if not exists ---
-  const mappingRelPath = '.github/beads-mapping.json';
-  const mappingDest = path.join(githubDir, 'beads-mapping.json');
-
-  if (fs.existsSync(mappingDest)) {
-    filesSkipped.push(mappingRelPath);
-  } else {
-    fs.mkdirSync(path.dirname(mappingDest), { recursive: true });
-    fs.writeFileSync(mappingDest, '{}');
-    filesCreated.push(mappingRelPath);
-  }
-
-  return { filesCreated, filesSkipped };
+  const cleanup = cleanupDeprecatedBeadsSync(projectRoot, { packageDir });
+
+  return {
+    filesCreated: [],
+    filesSkipped: [],
+    filesRemoved: cleanup.removed,
+    deprecated: true,
+    message: 'Beads GitHub sync scaffolding is deprecated; future GitHub issue sync must use Forge Kernel/server authority.'
+  };
 }
 
 module.exports = {
@@ -261,5 +184,6 @@ module.exports = {
   detectDefaultBranch,
   detectBeadsVersion,
   templateWorkflows,
+  cleanupDeprecatedBeadsSync,
   scaffoldBeadsSync,
 };

package/lib/codex-skills.js

@@ -2,6 +2,19 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
+const { populateAgentSkills } = require('./skills-sync');
+
+/**
+ * Codex's documented repo-local skill discovery directory, relative to a project
+ * root. Codex scans `.agents/skills/<name>/SKILL.md` from the current working
+ * directory up to the repo root (developers.openai.com/codex/skills). Unlike the
+ * GLOBAL `$CODEX_HOME/skills` install, this surface is COMMITTED to the repo (kept
+ * byte-identical to the canonical `skills/` source by a pre-commit sync hook and
+ * the drift gate), so a teammate who clones the repo WITHOUT running `forge setup`
+ * still gets the Forge skills/stages auto-discovered.
+ */
+const CODEX_REPO_SKILLS_DIR = '.agents/skills';
+
 function injectForgeAdapter(content, commandName) {
   const adapter = [
     '> Forge stage adapter',
@@ -20,7 +33,10 @@ function injectForgeAdapter(content, commandName) {
 }
 
 function listCodexSkillEntries(sourceRoot) {
-  const skillsDir = path.join(sourceRoot, '.codex', 'skills');
+  // Read from the canonical `skills/` source (single source of truth) rather than
+  // a committed `.codex/skills` mirror. The GLOBAL `$CODEX_HOME/skills` install is
+  // generated from these entries with the stage adapter injected below.
+  const skillsDir = path.join(sourceRoot, 'skills');
 
   if (!fs.existsSync(skillsDir)) {
     return [];
@@ -94,10 +110,44 @@ function buildCodexSkillInstallPlan(sourceRoot, options = {}) {
   }));
 }
 
+/**
+ * Absolute path to a project's repo-local Codex skill discovery dir.
+ *
+ * @param {string} projectRoot - The project/repo root.
+ * @returns {string} `<projectRoot>/.agents/skills`.
+ */
+function resolveCodexRepoSkillsDir(projectRoot) {
+  return path.join(projectRoot, '.agents', 'skills');
+}
+
+/**
+ * Generate the repo-local Codex skill discovery mirror (`.agents/skills`) from
+ * the canonical `skills/` source.
+ *
+ * Content matches the other harness mirrors byte-for-byte (raw canonical — the
+ * `$CODEX_HOME` stage adapter is NOT injected here) so the skills-sync drift gate
+ * can enforce it, and so repo-local discovery reaches parity with the
+ * `.claude/skills` / `.cursor/skills` discovery surfaces.
+ *
+ * @param {object} params
+ * @param {string} params.sourceRoot - Root containing the canonical `skills/` dir.
+ * @param {string} params.projectRoot - Target project/repo root.
+ * @param {boolean} [params.clean=false] - Remove stale canonical-managed dirs first.
+ * @returns {{targetSkillsDir: string, written: string[]}}
+ */
+function populateCodexRepoSkills({ sourceRoot, projectRoot, clean = false }) {
+  const targetSkillsDir = resolveCodexRepoSkillsDir(projectRoot);
+  const { written } = populateAgentSkills({ sourceRoot, targetSkillsDir, clean });
+  return { targetSkillsDir, written };
+}
+
 module.exports = {
+  CODEX_REPO_SKILLS_DIR,
   buildCodexSkillInstallPlan,
   formatCodexSkillsInstallDir,
   listCodexSkillEntries,
+  populateCodexRepoSkills,
   resolveCodexHome,
+  resolveCodexRepoSkillsDir,
   resolveCodexSkillsInstallDir,
 };