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

package/lib/npm-publish-workflow.js

@@ -0,0 +1,272 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const {
+	createProtectedStateAuditRecord,
+	recordProtectedStateAuditEvent,
+	writeProtectedFile,
+} = require('./protected-state-surfaces');
+const {
+	issueNpmPublishWorkflowAuthorization,
+} = require('./protected-state-authority');
+
+const NPM_PUBLISH_WORKFLOW_PATH = '.github/workflows/npm-publish.yml';
+
+function snapshotWorkflow(projectRoot) {
+	const fullPath = path.resolve(projectRoot, NPM_PUBLISH_WORKFLOW_PATH);
+	try {
+		const stat = fs.lstatSync(fullPath);
+		return {
+			fullPath,
+			existed: true,
+			content: stat.isFile() ? fs.readFileSync(fullPath) : null,
+		};
+	} catch (error) {
+		if (error.code === 'ENOENT') return { fullPath, existed: false, content: null };
+		throw error;
+	}
+}
+
+function rollbackWorkflow(snapshot, projectRoot, protectedWriter, writeOptions) {
+	if (!snapshot.existed) {
+		fs.rmSync(snapshot.fullPath, { force: true });
+		return;
+	}
+	if (!Buffer.isBuffer(snapshot.content)) {
+		throw new Error('Previous workflow was not a regular file');
+	}
+	const restored = protectedWriter(
+		projectRoot,
+		NPM_PUBLISH_WORKFLOW_PATH,
+		snapshot.content,
+		writeOptions,
+	);
+	if (!restored.allowed) throw new Error(restored.reason || 'Protected workflow restore was denied');
+}
+
+function renderNpmPublishWorkflow() {
+	return `# Generated by \`forge release generate-npm-workflow\`. Do not edit directly.
+name: Bun Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  resolve-release:
+    name: Resolve immutable release SHA
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      commitSha: \${{ steps.resolve.outputs.commitSha }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: \${{ github.event.release.tag_name }}
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Resolve release tag
+        id: resolve
+        shell: bash
+        env:
+          RELEASE_TAG: \${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+          COMMIT_SHA="$(git rev-parse "\${RELEASE_TAG}^{commit}")"
+          if [ -z "$COMMIT_SHA" ] || [ "$COMMIT_SHA" != "$(git rev-parse HEAD)" ]; then
+            echo "::error::Release tag did not resolve to the checked out commit"
+            exit 1
+          fi
+          echo "commitSha=$COMMIT_SHA" >> "$GITHUB_OUTPUT"
+
+  build:
+    needs: resolve-release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      commitSha: \${{ steps.evidence.outputs.commitSha }}
+      receipt: \${{ steps.evidence.outputs.receipt }}
+      receiptSubject: \${{ steps.evidence.outputs.receiptSubject }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: \${{ needs.resolve-release.outputs.commitSha }}
+          fetch-depth: 1
+          persist-credentials: false
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.12
+      - run: bun install --frozen-lockfile
+      - name: Setup test fixtures
+        shell: bash
+        run: bash test-env/automation/setup-fixtures.sh --force
+      - name: Run complete release suite
+        shell: bash
+        run: |
+          set -euo pipefail
+          node scripts/test-full-suite.js --label-prefix release-full
+      - name: Emit attributable release suite receipt
+        id: evidence
+        env:
+          EXPECTED_SHA: \${{ needs.resolve-release.outputs.commitSha }}
+        run: node scripts/npm-release-receipt.js emit
+
+  publish-npm:
+    needs: [resolve-release, build]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: \${{ needs.resolve-release.outputs.commitSha }}
+          fetch-depth: 1
+          persist-credentials: false
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org/
+      - name: Verify exact release suite receipt
+        env:
+          EXPECTED_SHA: \${{ needs.resolve-release.outputs.commitSha }}
+          VERIFIED_SHA: \${{ needs.build.outputs.commitSha }}
+          RECEIPT: \${{ needs.build.outputs.receipt }}
+          RECEIPT_SUBJECT: \${{ needs.build.outputs.receiptSubject }}
+        run: node scripts/npm-release-receipt.js verify
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.12
+      - run: bun install --frozen-lockfile
+      - name: Release tag matches package.json version
+        shell: bash
+        run: |
+          set -euo pipefail
+          PKG="$(node -p "require('./package.json').version")"
+          TAG="\${GITHUB_REF_NAME#v}"
+          if [ "$PKG" != "$TAG" ]; then
+            echo "::error::Release tag ($TAG) != package.json version ($PKG). Bump package.json before releasing."
+            exit 1
+          fi
+      - name: Release-readiness gate
+        run: node bin/forge.js release check --target "$(node -p "require('./package.json').version.split('-')[0]")"
+      - name: Verify package contents
+        run: npm pack --dry-run
+      - name: Ensure OIDC-capable npm
+        run: npm install --global npm@11.5.1 && npm --version
+      - name: Publish to npm
+        shell: bash
+        run: |
+          set -euo pipefail
+          VERSION="$(node -p "require('./package.json').version")"
+          if echo "$VERSION" | grep -q '-'; then
+            echo "Prerelease $VERSION -> publishing under the beta dist-tag"
+            npm publish --provenance --tag beta
+          else
+            npm publish --provenance
+          fi
+`;
+}
+
+async function generateNpmPublishWorkflow(projectRoot, options = {}) {
+	const content = renderNpmPublishWorkflow();
+	const actor = options.actor || options.env?.FORGE_ACTOR || process.env.FORGE_ACTOR || process.env.USER || process.env.USERNAME || 'unknown';
+	const protectedWriter = options.writeProtectedFile || writeProtectedFile;
+	const auditWriter = options.recordProtectedStateAuditEvent || recordProtectedStateAuditEvent;
+	const authorizationWriter = options.issueNpmPublishWorkflowAuthorization || issueNpmPublishWorkflowAuthorization;
+	const snapshot = snapshotWorkflow(projectRoot);
+	const writeOptions = {
+		actor,
+		operation: 'generate_npm_workflow',
+		viaForgeApi: true,
+		surface: 'workflows',
+	};
+	let write;
+	try {
+		write = protectedWriter(projectRoot, NPM_PUBLISH_WORKFLOW_PATH, content, writeOptions);
+	} catch (error) {
+		return { success: false, error: error.message };
+	}
+	if (!write.allowed) {
+		return { success: false, error: write.reason, write };
+	}
+
+	const auditRecord = createProtectedStateAuditRecord({
+		actor,
+		surface: 'workflows',
+		path: NPM_PUBLISH_WORKFLOW_PATH,
+		content,
+		operation: 'generate_npm_workflow',
+	});
+	let audit;
+	try {
+		audit = auditWriter(auditRecord, { cwd: projectRoot });
+	} catch (error) {
+		audit = { success: false, error: error.message };
+	}
+	if (!audit.success) {
+		let rollbackError;
+		try {
+			rollbackWorkflow(snapshot, projectRoot, protectedWriter, writeOptions);
+		} catch (error) {
+			rollbackError = error.message;
+		}
+		return {
+			success: false,
+			error: `Could not record protected-state authorization: ${audit.error}`,
+			audit,
+			rollbackError,
+		};
+	}
+
+	let trustedAuthorization;
+	try {
+		trustedAuthorization = await authorizationWriter(
+			projectRoot,
+			{ actor },
+			{ deps: options.kernelDeps },
+		);
+	} catch (error) {
+		trustedAuthorization = { success: false, error: error.message };
+	}
+	if (!trustedAuthorization.success) {
+		let rollbackError;
+		try {
+			rollbackWorkflow(snapshot, projectRoot, protectedWriter, writeOptions);
+		} catch (error) {
+			rollbackError = error.message;
+		}
+		return {
+			success: false,
+			error: `Could not record trusted protected-state authorization: ${trustedAuthorization.error}`,
+			audit,
+			trustedAuthorization,
+			rollbackError,
+		};
+	}
+
+	return {
+		success: true,
+		path: NPM_PUBLISH_WORKFLOW_PATH,
+		contentHash: write.contentHash,
+		write,
+		audit,
+		trustedAuthorization,
+	};
+}
+
+module.exports = {
+	NPM_PUBLISH_WORKFLOW_PATH,
+	renderNpmPublishWorkflow,
+	generateNpmPublishWorkflow,
+};

package/lib/orientation.js

@@ -3,6 +3,8 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { fenceUntrusted } = require('./untrusted-content');
+const { runIssueOperation: defaultRunIssueOperation } = require('./forge-issues');
+const { memoryTrustStatus } = require('./memory-recall');
 
 const DEFAULT_BUDGET_TOKENS = 2000;
 const MIN_BUDGET_TOKENS = 40;
@@ -43,25 +45,6 @@ function readJsonFile(projectRoot, relativeFilePath) {
   }
 }
 
-function readJsonl(projectRoot, relativeFilePath) {
-  const text = readText(projectRoot, relativeFilePath);
-  if (!text) return [];
-  return text
-    .split(/\r?\n/)
-    .map(line => line.trim())
-    .filter(Boolean)
-    .map((line, index) => {
-      try {
-        return JSON.parse(line);
-      } catch (error) {
-        return {
-          _parseError: true,
-          line: index + 1,
-          error: error.message,
-        };
-      }
-    });
-}
 
 function firstLine(value) {
   return String(value || '')
@@ -426,17 +409,43 @@ function buildMemorySection(projectRoot, options = {}) {
     const result = memoryRouter.recall(projectRoot, { limit: MEMORY_SECTION_NOTE_LIMIT }, { store });
     const notes = Array.isArray(result && result.notes) ? result.notes : [];
     if (notes.length === 0) return [];
-    return [buildSection({
-      id: 'remembered_notes',
-      title: 'Remembered Notes',
-      content: notes.map(formatMemoryNote).join('\n'),
-      sources: [source('kernel.remembered_notes', 'kernel_memory', 'project_memory', 'remembered_notes')],
-      priority: 45,
-      preserve: false,
-      // Remembered notes are untrusted DATA (a planted note must not read as directives).
-      // Raw here; the assembler fences it AFTER applyBudget truncation.
-      untrustedSource: 'memory',
-    })];
+    const groups = [
+      {
+        id: 'remembered_notes',
+        title: 'Confirmed Memory',
+        trust: 'confirmed',
+        priority: 45,
+      },
+      {
+        id: 'suggested_memory',
+        title: 'Suggested Memory — Verify Before Relying',
+        trust: 'suggested',
+        priority: 46,
+      },
+    ];
+    return groups.map(group => {
+      const content = notes
+        .filter(note => memoryTrustStatus({
+          tags: note.tags,
+          sourceAgent: note.sourceAgent,
+          value: note.machine ? {} : note.note,
+        }) === group.trust)
+        .map(formatMemoryNote)
+        .filter(line => estimateTokens(line) <= DEFAULT_BUDGET_TOKENS)
+        .join('\n');
+      if (!content) return null;
+      return buildSection({
+        id: group.id,
+        title: group.title,
+        content,
+        sources: [source('kernel.remembered_notes', 'kernel_memory', 'project_memory', group.id)],
+        priority: group.priority,
+        preserve: false,
+        // Remembered notes are untrusted DATA (a planted note must not read as directives).
+        // Raw here; the assembler fences it AFTER applyBudget truncation.
+        untrustedSource: 'memory',
+      });
+    }).filter(Boolean);
   } catch {
     return [];
   } finally {
@@ -470,8 +479,13 @@ function openMemoryStore(projectRoot) {
 /** Render one recall note as a compact `- [date] text` line. */
 function formatMemoryNote(note) {
   const date = typeof note.timestamp === 'string' && note.timestamp ? note.timestamp.slice(0, 10) : '';
-  const prefix = date ? `${date} ` : '';
-  return `- ${prefix}${note.note}`;
+  const trust = memoryTrustStatus({
+    tags: note.tags,
+    sourceAgent: note.sourceAgent,
+    value: note.machine ? {} : note.note,
+  });
+  const sourceAgent = note.sourceAgent || 'unknown';
+  return `- [source=${sourceAgent} trust=${trust} updated=${date || 'unknown'}] ${note.note}`;
 }
 
 function buildQueueSections() {
@@ -671,7 +685,8 @@ const PRIME_KEY_COMMANDS_CONTENT = [
   'forge upgrade [--dry-run] — preview/self-heal safe Forge upgrade readiness',
   'forge gate <verb> <gate-id> — toggle a workflow gate, or approve/reject a human gate',
   'forge role <role> --use <skill> — bind a role to a skill/ideology',
-  'forge merge --auto <pr> — opt-in conditional auto-merge (off by default)',
+  'forge merge --auto <pr> --expect-head <full-sha> --issue <issue-id> — opt-in guarded merge (off by default)',
+  'post-ship loop: forge ship → forge shepherd <pr> --pull --json → guarded forge merge with exact head + owned issue',
 ].map(line => `- ${line}`).join('\n');
 
 function buildPrimeKeyCommandsSection() {
@@ -685,14 +700,24 @@ function buildPrimeKeyCommandsSection() {
   });
 }
 
-function findIssue(projectRoot, issueId) {
-  const issues = readJsonl(projectRoot, '.beads/issues.jsonl')
-    .filter(row => row && !row._parseError && row._type === 'issue');
-  return issues.find(issue => issue.id === issueId) || null;
+// Read a single issue from the Kernel (the sole issue-state authority). The `show`
+// contract returns the issue summary DIRECTLY as `result.data` (ISSUE_SUMMARY_SCHEMA),
+// NOT `result.data.issue` — the nested shape belongs to the mutation envelope. Resilient
+// by contract: any read failure degrades to `null` (not-found) so orientation never crashes.
+async function findIssue(projectRoot, issueId, runIssueOperation = defaultRunIssueOperation) {
+  try {
+    const result = await runIssueOperation('show', [issueId], projectRoot, { issueBackend: 'kernel' });
+    if (result && result.ok && result.data && result.data.id) {
+      return result.data;
+    }
+  } catch {
+    // best-effort: a kernel read failure surfaces as "not found", never a thrown error
+  }
+  return null;
 }
 
-function buildIssueSection(projectRoot, issueId) {
-  const issue = findIssue(projectRoot, issueId);
+async function buildIssueSection(projectRoot, issueId, options = {}) {
+  const issue = await findIssue(projectRoot, issueId, options.runIssueOperation);
   const content = issue
     ? [
       `id: ${issue.id}`,
@@ -700,7 +725,7 @@ function buildIssueSection(projectRoot, issueId) {
       issue.status ? `status: ${issue.status}` : null,
       issue.description ? `description: ${issue.description}` : null,
     ].filter(Boolean).join('\n')
-    : `id: ${issueId}\nstatus: unknown\nIssue not found in compatibility projection.`;
+    : `id: ${issueId}\nstatus: unknown\nIssue not found in the kernel.`;
 
   return {
     issue: issue ? {
@@ -716,19 +741,19 @@ function buildIssueSection(projectRoot, issueId) {
       id: 'issue_summary',
       title: 'Issue Summary',
       content,
-      sources: [source('.beads/issues.jsonl', 'beads_compat', 'compatibility_projection', 'issue_summary')],
+      sources: [source('kernel', 'kernel', 'issue_read', 'issue_summary')],
       priority: 5,
       preserve: true,
     }),
   };
 }
 
-function buildIssueRecap(projectRoot, issueId, options = {}) {
+async function buildIssueRecap(projectRoot, issueId, options = {}) {
   if (!issueId || typeof issueId !== 'string') {
     throw new Error('Issue id is required for issue-scoped recap.');
   }
 
-  const issueResult = buildIssueSection(projectRoot, issueId);
+  const issueResult = await buildIssueSection(projectRoot, issueId, options);
   const sections = [
     issueResult.section,
     ...buildProjectDesignSections(projectRoot),

package/lib/plugin-catalog.js

@@ -91,15 +91,25 @@ const CATALOG = Object.freeze({
   },
 
   // ── Plan ──
-  beads: {
-    name: 'Beads',
+  'forge-kernel-issues': {
+    name: 'Forge Kernel issues',
     type: 'cli',
     tier: 'free',
     stage: 'plan',
-    description: 'Git-backed issue tracking',
+    description: 'Built-in issue tracker backing /plan — forge issue create, forge ready, forge claim',
     detectWhen: [],
-    install: { method: 'npm', cmd: 'bun add -g @beads/bd' },
+    install: { method: 'config', cmd: 'built-in (forge issue create)' },
   },
+  'mermaid-cli': {
+    name: 'Mermaid CLI',
+    type: 'cli',
+    tier: 'free',
+    stage: 'plan',
+    description: 'Render Mermaid architecture diagrams from design docs to SVG/PNG',
+    detectWhen: [],
+    install: { method: 'npm', cmd: 'bun add -D @mermaid-js/mermaid-cli', dev: true },
+  },
+
   // ── Dev ──
   'typescript-lsp': {
     name: 'TypeScript LSP',

package/lib/pr-bundle.js

@@ -86,12 +86,12 @@ async function gatherUnresolvedComments(adapter, { owner, repo, pr }) {
  * Predict merge conflicts. `detectConflicts` is optional on the adapter; when
  * absent or failing, report it as unsupported rather than throwing.
  */
-async function gatherConflicts(adapter, { baseRef, cwd }) {
+async function gatherConflicts(adapter, { baseRef, cwd, headRef }) {
   if (typeof adapter.detectConflicts !== 'function') {
     return { supported: false, reason: 'adapter has no detectConflicts capability' };
   }
   try {
-    return await adapter.detectConflicts({ baseRef, cwd });
+    return await adapter.detectConflicts({ baseRef, cwd, headRef });
   } catch (error) {
     return { supported: false, reason: error.message || 'conflict detection failed' };
   }
@@ -148,9 +148,9 @@ async function gatherPrBundle({ pr, owner, repo, base, baseRef, cwd, adapter })
   // silently yields a null required set. `pr` lets the adapter fall back to the
   // rollup `isRequired` set when branch protection is unreadable in CI.
   const requiredRaw = await adapter.readRequiredChecks({ owner, repo, base, pr });
-  const divergence = await adapter.readDivergence({ baseRef, cwd });
+  const divergence = await adapter.readDivergence({ baseRef, cwd, headRef: state.headSha });
   const comments = await gatherUnresolvedComments(adapter, { owner, repo, pr });
-  const conflicts = await gatherConflicts(adapter, { baseRef, cwd });
+  const conflicts = await gatherConflicts(adapter, { baseRef, cwd, headRef: state.headSha });
 
   const requiredSet = requiredRaw === undefined ? null : requiredRaw;
 
@@ -172,8 +172,7 @@ async function gatherPrBundle({ pr, owner, repo, base, baseRef, cwd, adapter })
       state: String(state.state || 'OPEN').toUpperCase(),
     },
     ci: buildCi(state.checks, requiredSet),
-    // Which source answered the required-checks read (`protection` | `rollup` |
-    // null) — `rollup` is the CI path where branch protection is unreadable.
+    // The authoritative required-check source (`protection` or null).
     requiredSource: adapter.lastRequiredSource || null,
     branch: {
       ahead: divergence.ahead || 0,

package/lib/pr-monitor/journal.js

@@ -35,14 +35,29 @@ function sanitize(part) {
   return String(part || '').replace(/[^A-Za-z0-9._-]+/g, '-');
 }
 
+/**
+ * Resolve the one journal authority shared by every worktree. Standard repos
+ * use `<main-root>/.forge/pr-monitor`; a nonstandard common dir centralizes
+ * beneath that shared metadata directory. No common dir preserves legacy use.
+ */
+function resolveJournalRoot({ root, gitCommonDir }) {
+  const fallbackRoot = path.resolve(root);
+  if (!gitCommonDir) return path.join(fallbackRoot, '.forge', 'pr-monitor');
+  const commonDir = path.resolve(gitCommonDir);
+  if (path.basename(commonDir).toLowerCase() === '.git') {
+    return path.join(path.dirname(commonDir), '.forge', 'pr-monitor');
+  }
+  return path.join(commonDir, 'forge', 'pr-monitor');
+}
+
 /**
  * Resolve (and create) the per-PR journal directory.
  *
  * @param {{ root: string, repo: string, pr: string|number }} ctx
  * @returns {string} absolute directory path
  */
-function journalDir({ root, repo, pr }) {
-  const dir = path.join(root, '.forge', 'pr-monitor', `${sanitize(repo)}-${sanitize(pr)}`);
+function journalDir({ root, gitCommonDir, repo, pr }) {
+  const dir = path.join(resolveJournalRoot({ root, gitCommonDir }), `${sanitize(repo)}-${sanitize(pr)}`);
   fs.mkdirSync(dir, { recursive: true });
   return dir;
 }
@@ -278,6 +293,7 @@ function watcherRunning(dir) {
 
 module.exports = {
   sanitize,
+  resolveJournalRoot,
   journalDir,
   journalPath,
   snapshotPath,