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

package/lib/npm-publish-workflow.js

@@ -0,0 +1,465 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { secureExecFileSync } = require('./shell-utils');
+
+const {
+	createProtectedStateAuditRecord,
+	recordProtectedStateAuditEvent,
+	removeProtectedFile,
+	writeProtectedFile,
+} = require('./protected-state-surfaces');
+const {
+	completeNpmPublishWorkflowAuthorization,
+	issueNpmPublishWorkflowAuthorization,
+} = require('./protected-state-authority');
+
+const NPM_PUBLISH_WORKFLOW_PATH = '.github/workflows/npm-publish.yml';
+const FULL_COMMIT_SHA = /^[0-9a-f]{40}$/;
+const BUN_VERSION = /^bun@(\d+\.\d+\.\d+)$/.exec(require('../package.json').packageManager)?.[1];
+if (!BUN_VERSION) throw new Error('package.json must pin an exact stable Bun version.');
+
+function resolveCurrentHead(projectRoot, execGit = secureExecFileSync) {
+	return execGit('git', ['rev-parse', '--verify', 'HEAD^{commit}'], {
+		cwd: projectRoot,
+		encoding: 'utf8',
+		stdio: ['ignore', 'pipe', 'pipe'],
+		windowsHide: true,
+	}).trim();
+}
+
+function readNpmPublishWorkflow(projectRoot, revision, execGit = secureExecFileSync) {
+	const options = {
+		cwd: projectRoot,
+		encoding: 'utf8',
+		stdio: ['ignore', 'pipe', 'pipe'],
+		windowsHide: true,
+	};
+	const indexed = revision === ':';
+	const entry = execGit('git', indexed
+		? ['ls-files', '--stage', '--', NPM_PUBLISH_WORKFLOW_PATH]
+		: ['ls-tree', revision, '--', NPM_PUBLISH_WORKFLOW_PATH], options).trim();
+	const expected = indexed
+		? /^100(?:644|755) [0-9a-f]+ 0\t\.github\/workflows\/npm-publish\.yml$/
+		: /^100(?:644|755) blob [0-9a-f]+\t\.github\/workflows\/npm-publish\.yml$/;
+	if (!expected.test(entry)) {
+		throw new Error(`${NPM_PUBLISH_WORKFLOW_PATH} is not one regular file ${indexed ? 'in the Git index' : `at ${revision}`}.`);
+	}
+	return Buffer.from(execGit('git', ['show', `${revision}${indexed ? '' : ':'}${NPM_PUBLISH_WORKFLOW_PATH}`], {
+		...options,
+		encoding: 'buffer',
+	}));
+}
+
+function readSourceNpmPublishWorkflow(projectRoot, sourceHead, execGit = secureExecFileSync) {
+	return readNpmPublishWorkflow(projectRoot, sourceHead, execGit);
+}
+
+function readIndexedNpmPublishWorkflow(projectRoot, execGit = secureExecFileSync) {
+	return readNpmPublishWorkflow(projectRoot, ':', execGit);
+}
+
+function verifyExpectedHead(projectRoot, expectedHead, resolveHead = resolveCurrentHead) {
+	if (!expectedHead) {
+		return { success: false, error: '--expect-head is required for protected workflow generation.' };
+	}
+	if (!FULL_COMMIT_SHA.test(expectedHead)) {
+		return { success: false, error: '--expect-head must be a full 40-character lowercase commit SHA.' };
+	}
+
+	let currentHead;
+	try {
+		currentHead = resolveHead(projectRoot);
+	} catch (error) {
+		return { success: false, error: `Could not resolve current HEAD: ${error.message}` };
+	}
+	if (!FULL_COMMIT_SHA.test(currentHead)) {
+		return { success: false, error: 'Current HEAD did not resolve to a full 40-character lowercase commit SHA.' };
+	}
+	if (currentHead !== expectedHead) {
+		return {
+			success: false,
+			error: `Expected HEAD ${expectedHead} does not match current HEAD ${currentHead}.`,
+		};
+	}
+	return { success: true, sourceHead: currentHead };
+}
+
+function renderNpmDistTagResolverScript() {
+	return `CORE_RE='(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)'
+NUMERIC_ID_RE='(0|[1-9][0-9]*)'
+BUILD_RE='(\\+[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?'
+BETA_RE="^\${CORE_RE}-beta(\\.\${NUMERIC_ID_RE})*\${BUILD_RE}$"
+RC_RE="^\${CORE_RE}-rc(\\.\${NUMERIC_ID_RE})*\${BUILD_RE}$"
+STABLE_RE="^\${CORE_RE}\${BUILD_RE}$"
+
+if [[ "$VERSION" =~ $BETA_RE ]]; then
+  echo "tag=beta" >> "$GITHUB_OUTPUT"
+elif [[ "$VERSION" =~ $RC_RE ]]; then
+  echo "tag=rc" >> "$GITHUB_OUTPUT"
+elif [[ "$VERSION" =~ $STABLE_RE ]]; then
+  echo "tag=latest" >> "$GITHUB_OUTPUT"
+elif [[ "$VERSION" == *-* ]]; then
+  echo "::error::Unsupported npm prerelease: $VERSION"
+  exit 1
+else
+  echo "::error::Invalid npm version: $VERSION"
+  exit 1
+fi`;
+}
+
+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 sameSnapshot(expected, actual) {
+	if (!expected || typeof expected !== 'object' || Array.isArray(expected)) return false;
+	if (typeof expected.existed !== 'boolean') return false;
+	if (expected.existed && !Buffer.isBuffer(expected.content)) return false;
+	if (!expected.existed && expected.content !== null) return false;
+	return expected.existed === actual.existed
+		&& (!expected.existed || expected.content.equals(actual.content));
+}
+
+function recoverWorkflow(snapshot, projectRoot, generatedContent, protectedWriter, protectedRemover, writeOptions) {
+	const recoveryOptions = {
+		...writeOptions,
+		operation: 'recover_npm_workflow',
+		expectedContent: generatedContent,
+	};
+	if (!snapshot.existed) {
+		return protectedRemover(projectRoot, NPM_PUBLISH_WORKFLOW_PATH, recoveryOptions);
+	}
+	if (!Buffer.isBuffer(snapshot.content)) {
+		return { allowed: false, reason: 'Previous workflow was not a regular file' };
+	}
+	return protectedWriter(
+		projectRoot,
+		NPM_PUBLISH_WORKFLOW_PATH,
+		snapshot.content,
+		recoveryOptions,
+	);
+}
+
+async function prepareWorkflowAuthorization(prepareAuthorization, projectRoot, params, authorizationOptions) {
+	try {
+		return await prepareAuthorization(projectRoot, params, authorizationOptions);
+	} catch (error) {
+		return { success: false, error: error.message };
+	}
+}
+
+function recordWorkflowAudit(auditWriter, auditRecord, projectRoot) {
+	try {
+		return auditWriter(auditRecord, { cwd: projectRoot });
+	} catch (error) {
+		return { success: false, error: error.message };
+	}
+}
+
+function renderNpmPublishWorkflow(bunVersion = BUN_VERSION) {
+	if (!/^\d+\.\d+\.\d+$/.test(bunVersion)) throw new Error('npm workflow requires an exact stable Bun version.');
+	const distTagResolver = renderNpmDistTagResolverScript()
+		.split('\n')
+		.map(line => line ? `          ${line}` : '')
+		.join('\n');
+	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
+    timeout-minutes: 10
+    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
+    timeout-minutes: 25
+    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: ${bunVersion}
+      - 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
+    timeout-minutes: 20
+    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: ${bunVersion}
+      - 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: Resolve npm dist-tag
+        id: dist-tag
+        shell: bash
+        run: |
+          set -euo pipefail
+          VERSION="$(node -p "require('./package.json').version")"
+${distTagResolver}
+      - name: Publish to npm
+        shell: bash
+        run: |
+          set -euo pipefail
+          DIST_TAG="\${{ steps.dist-tag.outputs.tag }}"
+          case "$DIST_TAG" in
+            beta)
+              npm publish --provenance --tag beta
+              ;;
+            rc)
+              npm publish --provenance --tag rc
+              ;;
+            latest)
+              npm publish --provenance
+              ;;
+            *)
+              echo "::error::Unsupported npm dist-tag: $DIST_TAG"
+              exit 1
+              ;;
+          esac
+`;
+}
+
+async function generateNpmPublishWorkflow(projectRoot, options = {}) {
+	const head = verifyExpectedHead(projectRoot, options.expectedHead, options.resolveHead);
+	if (!head.success) return head;
+	const sourceHead = head.sourceHead;
+	let targetBunVersion;
+	try {
+		targetBunVersion = options.targetBunVersion
+			|| require('./bun-workflow-pins').resolveBunVersionTarget(projectRoot, options).version;
+	} catch (error) {
+		return { success: false, error: error.message };
+	}
+	const bunVersion = options.bunVersion || targetBunVersion;
+	if (bunVersion !== targetBunVersion) {
+		return { success: false, error: 'npm workflow Bun version must match the staged package.json Bun pin.' };
+	}
+	const content = renderNpmPublishWorkflow(bunVersion);
+	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 protectedRemover = options.removeProtectedFile || removeProtectedFile;
+	const auditWriter = options.recordProtectedStateAuditEvent || recordProtectedStateAuditEvent;
+	const prepareAuthorization = options.prepareNpmPublishWorkflowAuthorization || issueNpmPublishWorkflowAuthorization;
+	const activateAuthorization = options.activateNpmPublishWorkflowAuthorization || completeNpmPublishWorkflowAuthorization;
+	const snapshot = snapshotWorkflow(projectRoot);
+	if (options.expectedSnapshot && !sameSnapshot(options.expectedSnapshot, snapshot)) {
+		return {
+			success: false,
+			error: `${NPM_PUBLISH_WORKFLOW_PATH} changed after Bun pin batch preflight.`,
+		};
+	}
+	const writeOptions = {
+		actor,
+		operation: 'generate_npm_workflow',
+		viaForgeApi: true,
+		surface: 'workflows',
+	};
+	const trustedAuthorization = await prepareWorkflowAuthorization(
+		prepareAuthorization,
+		projectRoot,
+		{ actor, sourceHead, bunVersion, targetBunVersion },
+		{ deps: options.kernelDeps, capabilityId: options.capabilityId },
+	);
+	if (!trustedAuthorization.success) {
+		return {
+			success: false,
+			error: `Could not record trusted protected-state authorization: ${trustedAuthorization.error}`,
+			trustedAuthorization,
+		};
+	}
+
+	let write;
+	try {
+		write = protectedWriter(projectRoot, NPM_PUBLISH_WORKFLOW_PATH, content, {
+			...writeOptions,
+			expectedContent: snapshot.existed ? snapshot.content : null,
+			...(options.beforeAtomicCommit ? { beforeAtomicCommit: options.beforeAtomicCommit } : {}),
+		});
+	} 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',
+		viaForgeApi: true,
+		sourceHead,
+	});
+	const audit = recordWorkflowAudit(auditWriter, auditRecord, projectRoot);
+	if (!audit.success) {
+		let recovery;
+		try {
+			recovery = recoverWorkflow(snapshot, projectRoot, content, protectedWriter, protectedRemover, writeOptions);
+		} catch (error) {
+			recovery = { allowed: false, reason: error.message };
+		}
+		return {
+			success: false,
+			error: `Could not record protected-state authorization: ${audit.error}`,
+			audit,
+			recovery,
+		};
+	}
+
+	let writeCompletion;
+	try {
+		writeCompletion = await activateAuthorization(
+			projectRoot,
+			{ actor, sourceHead, capabilityId: trustedAuthorization.capabilityId, bunVersion, targetBunVersion },
+			{ deps: options.kernelDeps },
+		);
+	} catch (error) {
+		writeCompletion = { success: false, error: error.message };
+	}
+	if (!writeCompletion.success) {
+		let recovery;
+		try {
+			recovery = recoverWorkflow(snapshot, projectRoot, content, protectedWriter, protectedRemover, writeOptions);
+		} catch (error) {
+			recovery = { allowed: false, reason: error.message };
+		}
+		return {
+			success: false,
+			error: `Could not complete trusted protected-state authorization: ${writeCompletion.error}`,
+			audit,
+			trustedAuthorization,
+			writeCompletion,
+			recovery,
+		};
+	}
+
+	return {
+		success: true,
+		path: NPM_PUBLISH_WORKFLOW_PATH,
+		sourceHead,
+		bunVersion,
+		contentHash: write.contentHash,
+		write,
+		audit,
+		trustedAuthorization,
+		writeCompletion,
+	};
+}
+
+module.exports = {
+	NPM_PUBLISH_WORKFLOW_PATH,
+	readIndexedNpmPublishWorkflow,
+	readSourceNpmPublishWorkflow,
+	renderNpmDistTagResolverScript,
+	renderNpmPublishWorkflow,
+	resolveCurrentHead,
+	verifyExpectedHead,
+	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/package-root.js

@@ -67,8 +67,10 @@ const ASSET_ROOTS = Object.freeze([
   'skills',
   'rules',
   'AGENTS.md',
+  'CODING_STANDARDS.md',
   '.claude/scripts',
   '.forge/hooks',
+  'lib/kernel/windows-private-acl.js',
   'scripts',
 ]);
 

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',