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

package/lib/commands/pr.js

@@ -33,7 +33,7 @@ const SUBCOMMANDS = {
   },
   merge: {
     module: merge,
-    summary: 'Opt-in conditional auto-merge, OFF by default (= forge merge --auto <pr>)',
+    summary: 'Opt-in guarded merge, OFF by default (= forge merge --auto <pr> --expect-head <sha> --issue <id>)',
   },
 };
 

package/lib/commands/preflight.js

@@ -103,7 +103,16 @@ function resolveChangeSet(exec = execFileSync, { runAll = false } = {}) {
   // Diff against the SAME base we just resolved. getChangedFiles() re-resolves
   // its own diff ref (and can fall back to a different default branch), so use
   // baseRef directly to keep the file list consistent with the resolved base.
-  return { resolved: true, baseRef, changedFiles: changedFilesForBase(exec, baseRef) };
+  const changedFiles = changedFilesForBase(exec, baseRef);
+  if (changedFiles == null) {
+    return {
+      resolved: false,
+      baseRef,
+      changedFiles: [],
+      reason: `git diff failed or timed out for ${baseRef}`,
+    };
+  }
+  return { resolved: true, baseRef, changedFiles };
 }
 
 /** Files changed between the merge-base of HEAD and `baseRef` and HEAD. */
@@ -111,7 +120,7 @@ function changedFilesForBase(exec, baseRef) {
   const mergeBase = gitTryOut(exec, ['merge-base', 'HEAD', baseRef]);
   const range = mergeBase ? `${mergeBase}...HEAD` : `${baseRef}...HEAD`;
   const out = gitTryOut(exec, ['diff', '--name-only', range]);
-  if (out == null) return [];
+  if (out == null) return null;
   return out.split(/\r?\n/).filter(Boolean);
 }
 

package/lib/commands/prime.js

@@ -6,15 +6,28 @@ const {
   runOrientationCommand,
 } = require('../orientation');
 
+const DEPRECATION_NOTICE =
+  'forge prime is deprecated — run `forge status -v` for the same briefing.\n';
+
+// The single briefing renderer. `forge status -v` calls this so the full
+// session-entry briefing has exactly one implementation.
+// Async: the briefing leads with LIVE state (stage / claims / ready / gates / one
+// adoption nudge), which needs a best-effort (non-throwing) kernel read before the
+// synchronous build assembles it into the bounded orientation.
+async function renderBriefing(args, projectRoot) {
+  const liveState = await collectPrimeLiveState(projectRoot);
+  return runOrientationCommand(buildPrime, args, projectRoot, { liveState });
+}
+
 module.exports = {
   name: 'prime',
-  description: 'Emit session-entry bounded orientation for agents',
-  usage: 'Usage: forge prime [--budget N] [--json]',
-  // Async: prime leads with LIVE state (stage / claims / ready / gates / one adoption nudge),
-  // which needs a best-effort (non-throwing) kernel read before the synchronous build assembles
-  // it into the bounded orientation. All existing prime output/flags are unchanged.
-  handler: async (args, _flags, projectRoot) => {
-    const liveState = await collectPrimeLiveState(projectRoot);
-    return runOrientationCommand(buildPrime, args, projectRoot, { liveState });
+  description: 'Deprecated alias for `forge status -v`: session-entry bounded orientation',
+  usage: 'Usage: forge prime [--budget N] [--json]  (deprecated — use `forge status -v`)',
+  // Session-start hooks in consumer repos call this and consume stdout as context,
+  // so the notice goes to stderr and stdout stays byte-identical to `status -v`.
+  handler: async (args, _flags, projectRoot, options = {}) => {
+    (options.stderr || process.stderr).write(DEPRECATION_NOTICE);
+    return renderBriefing(args, projectRoot);
   },
+  renderBriefing,
 };

package/lib/commands/push.js

@@ -4,8 +4,8 @@ const { execFileSync, spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
 const forgeToken = require('../../scripts/check-forge-token');
-const { startPrWatcherDetached } = require('../pr-monitor/watch-lifecycle');
-const { autoShepherdRailEnabled } = require('./ship');
+const { QUICK_LANE_ENV_VAR, QUICK_LANE_VALUE } = require('../../scripts/test');
+const { fireAndForget } = require('../pr-monitor/reconcile-executor');
 
 const isWindows = process.platform === 'win32';
 
@@ -113,54 +113,49 @@ async function autoFileBackingIssueForPush(projectRoot, execFn, deps = {}) {
 }
 
 /**
- * Resolve the OPEN PR number for the current branch via `gh pr view`. Returns
- * null when there is no PR, gh is unavailable, or anything errors (fail-open).
- * NEVER throws.
+ * Best-effort wake of the repository-wide singleton after a successful push.
+ * The shared trigger owns all containment and gate checks and never selects a
+ * per-PR watcher here.
  *
- * @param {function} execFn - execFileSync or mock
- * @returns {number|null}
+ * @param {object} params
+ * @returns {{ armed: boolean, reason?: string }}
  */
-function resolveOpenPrNumber(execFn) {
+function maybeTriggerShepherdAfterPush({
+	projectRoot,
+	fireAndForget: trigger = fireAndForget,
+}) {
 	try {
-		const out = execFn('gh', ['pr', 'view', '--json', 'number', '-q', '.number'], {
-			encoding: 'utf8', timeout: 15000, stdio: ['pipe', 'pipe', 'pipe'],
-		});
-		const n = Number.parseInt(String(out).trim(), 10);
-		return Number.isInteger(n) && n > 0 ? n : null;
-	} catch (_err) { /* intentional: no open PR / gh missing → arm nothing */ // NOSONAR S2486
-		return null;
+		trigger({ projectRoot });
+		return { armed: true };
+	} catch (err) {
+		return { armed: false, reason: err.message };
 	}
 }
 
 /**
- * Best-effort, NON-BLOCKING arm of the constant PR watcher after a successful
- * push, when an OPEN PR exists for the current branch. This closes the gap where
- * PRs not born from `forge ship` (gh pr create, the GitHub UI, an earlier push)
- * never got a watcher. Gated by the default-ON `rail.auto_shepherd`, idempotent
- * via the watch loop's own PID/journal lock, and reusing the same
- * `startPrWatcherDetached` as ship. MUST NEVER throw into or fail the push: a
- * disabled rail, no PR, a gh error, or a spawn error all degrade to
- * `{ armed: false }`.
+ * Build the environment for the spawned `git push`, declaring the push lane.
  *
- * @param {object} params
- * @returns {{ armed: boolean, reason?: string, prNumber?: number }}
+ * `--quick` skips the test step push.js controls, but the `git push` it spawns
+ * still fires the lefthook pre-push hook, whose tests job runs scripts/test.js —
+ * so --quick was quick only up to the push. This declares the lane to that hook
+ * so the quick lane is lint-only end to end.
+ *
+ * The declaration is set on the child env only, and is explicitly REMOVED for a
+ * full push so an inherited value from an outer shell can never silently drop
+ * the tests from a `forge push`.
+ *
+ * @param {boolean} quickMode - Whether this is a --quick push
+ * @param {NodeJS.ProcessEnv} [baseEnv=process.env] - Environment to derive from
+ * @returns {NodeJS.ProcessEnv} Environment for the git push child process
  */
-function maybeArmWatcherAfterPush({
-	projectRoot,
-	execFn,
-	startWatcher = startPrWatcherDetached,
-	railEnabled = autoShepherdRailEnabled,
-	prLookup = resolveOpenPrNumber,
-}) {
-	try {
-		if (!railEnabled(projectRoot)) return { armed: false, reason: 'rail.auto_shepherd disabled' };
-		const prNumber = prLookup(execFn);
-		if (!prNumber) return { armed: false, reason: 'no-open-pr' };
-		const res = startWatcher({ prNumber, cwd: projectRoot });
-		return { armed: !!(res && res.started), reason: res && res.reason, prNumber };
-	} catch (err) {
-		return { armed: false, reason: err.message };
+function buildPushEnv(quickMode, baseEnv = process.env) {
+	const env = { ...baseEnv };
+	if (quickMode) {
+		env[QUICK_LANE_ENV_VAR] = QUICK_LANE_VALUE;
+	} else {
+		delete env[QUICK_LANE_ENV_VAR];
 	}
+	return env;
 }
 
 /**
@@ -288,7 +283,7 @@ module.exports = {
 		// Step 5: git push with passthrough args
 		const gitArgs = args.filter(a => a !== '--quick');
 		try {
-			execFn('git', ['push', ...gitArgs], { stdio: 'inherit' });
+			execFn('git', ['push', ...gitArgs], { stdio: 'inherit', env: buildPushEnv(quickMode) });
 		} catch (_pushErr) { // NOSONAR S2486
 			log('git push failed.');
 			return {
@@ -300,15 +295,10 @@ module.exports = {
 			};
 		}
 
-		// Arm the constant PR watcher for this branch's open PR (best-effort,
-		// gated by rail.auto_shepherd, never fails the push). Covers PRs not born
-		// from `forge ship`.
-		maybeArmWatcherAfterPush({
+		// Wake the repository-wide singleton after a successful push.
+		maybeTriggerShepherdAfterPush({
 			projectRoot,
-			execFn,
-			startWatcher: deps?.startWatcher,
-			railEnabled: deps?.railEnabled,
-			prLookup: deps?.prLookup,
+			fireAndForget: deps?.fireAndForget,
 		});
 
 		return {
@@ -323,7 +313,7 @@ module.exports = {
 	// Exposed for unit tests; not part of the CLI surface.
 	_internal: {
 		autoFileBackingIssueForPush,
-		maybeArmWatcherAfterPush,
-		resolveOpenPrNumber,
+		buildPushEnv,
+		maybeTriggerShepherdAfterPush,
 	},
 };

package/lib/commands/recall.js

@@ -3,8 +3,11 @@
 const memoryRouter = require('../memory/router');
 const { stripGlobalFlags } = require('../global-flags');
 const { fenceUntrusted } = require('../untrusted-content');
+const { applyBudget, buildSection, estimateTokens } = require('../orientation');
+const { memoryTrustStatus } = require('../memory-recall');
 
 const usage = 'Usage: forge recall [query] [--kind <type>] [--limit N] [--all] [--json]';
+const RECALL_CONTENT_BUDGET = 1100;
 
 // Reserved tag prefix that `remember --kind` writes (kernel issue 8cc1db4d). A `--kind`
 // filter keeps only notes carrying this tag; the prefix is stripped when surfacing the
@@ -79,21 +82,28 @@ function withType(entry) {
 
 function formatEntry(entry) {
   const date = entry.timestamp ? entry.timestamp.slice(0, 10) : '';
-  const prefix = date ? `${date}  ` : '';
+  const trust = memoryTrustStatus({
+    tags: entry.tags,
+    sourceAgent: entry.sourceAgent,
+    value: entry.machine ? {} : entry.note,
+  });
+  const sourceAgent = entry.sourceAgent || 'unknown';
+  const label = `[source=${sourceAgent} trust=${trust} updated=${date || 'unknown'}] `;
   // The reserved `type:` tag renders as a leading `(kind)` marker, not as a raw tag, so the
   // displayed tags stay the user's own labels.
   const type = typeOf(entry);
-  const userTags = (entry.tags || []).filter(t => !t.startsWith(TYPE_TAG_PREFIX));
+  const userTags = (entry.tags || []).filter(
+    t => !t.startsWith(TYPE_TAG_PREFIX) && !t.startsWith('trust:')
+  );
   const tagSuffix = userTags.length > 0 ? ` [${userTags.join(', ')}]` : '';
   const typeMarker = type ? `(${type}) ` : '';
   // Machine/insights records are LABELED with their source so they are never mistaken for a
   // plain human note; human `remember` notes render clean.
   const marker = entry.machine && entry.sourceAgent ? `(${entry.sourceAgent}) ` : '';
-  // Stored note text is UNTRUSTED (a planted memory could carry injected directives),
-  // so the human/agent-facing render is provenance-fenced. The `--json` path above
-  // keeps the raw note so programmatic consumers/parsers are unaffected.
-  const note = fenceUntrusted(entry.note, { source: 'memory' });
-  return `- ${prefix}${marker}${typeMarker}${note}${tagSuffix}`;
+  // Stored note text is untrusted. Fence it after budgeting so a truncation cannot
+  // sever the close marker; the `--json` path above keeps the raw note unchanged.
+  const note = String(entry.note == null ? '' : entry.note);
+  return `- ${label}${marker}${typeMarker}${note}${tagSuffix}`;
 }
 
 async function handler(args, flags, projectRoot) {
@@ -137,23 +147,57 @@ async function handler(args, flags, projectRoot) {
     return { success: true, output: reason };
   }
 
+  const sections = notes
+    .map((entry, index) => {
+      const content = formatEntry(entry);
+      if (estimateTokens(content) > RECALL_CONTENT_BUDGET) return null;
+      const trust = memoryTrustStatus({
+        tags: entry.tags,
+        sourceAgent: entry.sourceAgent,
+        value: entry.machine ? {} : entry.note,
+      });
+      return buildSection({
+        id: `recall_${index}`,
+        title: '',
+        content,
+        priority: index,
+        preserve: false,
+        data: { trust },
+      });
+    })
+    .filter(Boolean);
+  const budgeted = applyBudget(sections, RECALL_CONTENT_BUDGET).sections
+    .filter(section => section.content);
+  for (const section of budgeted) {
+    section.content = fenceUntrusted(section.content, { source: 'memory' });
+  }
+  const rendered = budgeted.length;
   const noun = scope === 'all' && !query ? 'stored memory record(s)' : 'remembered note(s)';
   let header;
   if (query) {
     // BM25 returns at most `limit`; when full, signal it is the TOP-N, not the whole set.
-    header = capped
-      ? `Top ${notes.length} note(s) matching "${query}" (raise --limit for more):`
-      : `${notes.length} note(s) matching "${query}":`;
-  } else if (capped) {
-    // Never a bare full dump: show the newest N and the true total.
-    header = `Showing ${notes.length} of ${total} ${noun} (newest first):`;
+    header = capped || rendered < notes.length
+      ? `Top ${rendered} note(s) matching "${query}" (raise --limit for more):`
+      : `${rendered} note(s) matching "${query}":`;
+  } else if (capped || rendered < notes.length) {
+    // Never a bare full dump: show the rendered count and the true total.
+    header = `Showing ${rendered} of ${total} ${noun} (newest first):`;
   } else {
-    header = `${total} ${noun}:`;
+    header = `${rendered} ${noun}:`;
   }
-  const lines = notes.map(formatEntry);
+  const confirmed = budgeted.filter(section => section.data.trust === 'confirmed');
+  const suggested = budgeted.filter(section => section.data.trust === 'suggested');
+  const groups = [
+    confirmed.length ? ['Confirmed memory', confirmed] : null,
+    suggested.length ? ['Suggested memory — verify before relying', suggested] : null,
+  ].filter(Boolean);
+  const body = groups.flatMap(([title, entries]) => [
+    title,
+    ...entries.map(entry => entry.content),
+  ]);
   return {
     success: true,
-    output: [header, ...lines].join('\n'),
+    output: [header, ...body].join('\n'),
   };
 }
 

package/lib/commands/recap.js

@@ -46,7 +46,12 @@ async function handler(args, _flags, projectRoot, opts = {}) {
   }
 
   const budget = readOption(args, '--budget', undefined);
-  const recap = buildIssueRecap(projectRoot, issueId, { budgetTokens: budget });
+  // `runIssueOperation` is the injectable kernel-read seam (Slice C2) — the same
+  // pass-through opts already carry for the grounding write below.
+  const recap = await buildIssueRecap(projectRoot, issueId, {
+    budgetTokens: budget,
+    runIssueOperation: opts.runIssueOperation,
+  });
 
   // Grounding (gate.read_first): a successful recap IS the load-the-doc action,
   // so append a `context.loaded` event that unblocks a later `forge claim <id>`.

package/lib/commands/release.js

@@ -8,12 +8,13 @@ const {
 } = require('../release-readiness');
 const { runIssueOperation: defaultRunIssueOperation } = require('../forge-issues');
 const { normalizeArgs, normalizeIssueResult, withResolvedIssueBackend } = require('./_issue');
+const { generateNpmPublishWorkflow } = require('../npm-publish-workflow');
 
 // `forge release <id>` releases a claimed issue; `forge release check` runs the
 // release-readiness gate. The two share the top-level verb, so this command
 // dispatches `check` to the gate and routes everything else through the shared
 // issue dispatch (resolve backend → runIssueOperation('release') → normalize).
-const usage = 'Usage: forge release <id>  |  forge release check --target 0.1.0 [--json]  |  forge release regen-audit';
+const usage = 'Usage: forge release <id>  |  forge release check --target 0.1.0 [--json]  |  forge release regen-audit  |  forge release generate-npm-workflow';
 
 async function runReleaseIssue(args, projectRoot, opts = {}) {
   const resolved = withResolvedIssueBackend(projectRoot, opts);
@@ -55,7 +56,21 @@ function parseReleaseArgs(args = []) {
 }
 
 async function handler(args, _flags, projectRoot, opts = {}) {
-  const parsed = parseReleaseArgs(args);
+	const parsed = parseReleaseArgs(args);
+
+	if (parsed.subcommand === 'generate-npm-workflow') {
+		const generated = await generateNpmPublishWorkflow(projectRoot, {
+			env: opts.env,
+			kernelDeps: opts.kernelDeps,
+		});
+		return generated.success
+			? {
+				success: true,
+				generated,
+				output: `Generated ${generated.path} (${generated.contentHash}).\n`,
+			}
+			: generated;
+	}
 
   if (parsed.subcommand === 'regen-audit') {
     // forge release regen-audit — rewrite the D20 kill-list from a live re-scan.