@moretea-labs/forge 1.7.2 → 1.8.0

package/src/cli/commands/brain.ts

@@ -1,6 +1,6 @@
 /**
  * `agentic-dev brain` / `forge brain` — explicit external knowledge
- * sync and archive promotion surface.
+ * sync and terminal-workflow promotion surface.
  *
  * Hooks only emit [BrainPromote] advisories. This command owns the deliberate
  * write boundary from repo files into ~/brain/<project>/*.
@@ -11,6 +11,10 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { execFileSync } from 'child_process';
 import { configuredBrainRoot } from './brain-root';
+import { addBrainAssistantCommands } from './brain-assistant';
+import { resolveRepoPreferredControllerHome } from '../repositories/controller-home';
+import { findRegisteredRepositoryByCheckoutRoot } from '../repositories/registry';
+import { getWorkContract, validateWorkSemantics } from '../../../packages/kernel/work/api/index';
 
 export type BrainLifecycle = 'always-sync' | 'archive-only' | 'never-sync';
 export type BrainCategory = 'decisions' | 'runbooks' | 'patterns' | 'references';
@@ -89,6 +93,9 @@ export interface BrainPromoteOptions {
   repo?: string;
   slug: string;
   category: BrainCategory;
+  workId?: string;
+  controllerHome?: string;
+  legacyGitHistory?: boolean;
   dryRun?: boolean;
   json?: boolean;
 }
@@ -426,20 +433,98 @@ export function runBrain(mode: 'status' | 'check' | 'sync', opts: BrainCommandOp
   return { repoRoot, manifestPath, brainRoot: root, project: manifest.project || path.basename(repoRoot), mode, scope, selected: items, synced, skipped, issues, dryRun: opts.dryRun === true };
 }
 
-function findArchiveSources(repoRoot: string, slug: string): string[] {
+interface HistoricalBrainSource {
+  sourcePath: string;
+  gitRef: string;
+  content: string;
+  terminalAt: string;
+}
+
+function gitText(repoRoot: string, args: string[]): string {
+  return execFileSync('git', ['-C', repoRoot, ...args], {
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    maxBuffer: 16 * 1024 * 1024,
+  });
+}
+
+function terminalSourceKind(sourcePath: string): 'plan' | 'notes' | null {
+  const normalized = normalizeSlashes(sourcePath);
+  const base = path.posix.basename(normalized);
+  if ((/^plans\/plan-[^/]+\.md$/).test(normalized) || (normalized.startsWith('plans/archive/') && base.startsWith('plan-') && base.endsWith('.md'))) {
+    return 'plan';
+  }
+  if ((/^tasks\/notes\/[^/]+\.notes\.md$/).test(normalized) || (normalized.startsWith('tasks/archive/') && base.startsWith('notes-') && base.endsWith('.md'))) {
+    return 'notes';
+  }
+  return null;
+}
+
+function findTerminalHistorySources(repoRoot: string, slug: string): HistoricalBrainSource[] {
   const safeSlug = slug.replace(/[^A-Za-z0-9._-]+/g, '-');
-  const sources: string[] = [];
-  for (const dir of ['plans/archive', 'tasks/archive']) {
-    const fullDir = path.resolve(repoRoot, dir);
-    if (!fs.existsSync(fullDir)) continue;
-    for (const file of fs.readdirSync(fullDir).sort()) {
-      if (!file.endsWith('.md')) continue;
-      if (dir === 'plans/archive' && !file.startsWith('plan-')) continue;
-      if (dir === 'tasks/archive' && !file.startsWith('notes-')) continue;
-      if (file.includes(safeSlug)) sources.push(`${dir}/${file}`);
+  let log = '';
+  try {
+    log = gitText(repoRoot, [
+      'log',
+      '--all',
+      '--date=iso-strict',
+      '--format=@@FORGE_COMMIT@@%H%x09%aI',
+      '--diff-filter=DR',
+      '-M',
+      '--name-status',
+      '--',
+      'plans',
+      'tasks',
+    ]);
+  } catch {
+    return [];
+  }
+
+  let commit = '';
+  let terminalAt = '';
+  const selected = new Map<'plan' | 'notes', HistoricalBrainSource>();
+  for (const rawLine of log.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    if (line.startsWith('@@FORGE_COMMIT@@')) {
+      const [nextCommit, nextTerminalAt = ''] = line.slice('@@FORGE_COMMIT@@'.length).split('\t');
+      commit = nextCommit || '';
+      terminalAt = nextTerminalAt || '';
+      continue;
+    }
+    if (!commit || !line.includes(safeSlug)) continue;
+    const fields = line.split('\t');
+    const status = fields[0] ?? '';
+    let sourcePath = '';
+    let gitRef = '';
+    if (status === 'D' && fields[1]) {
+      sourcePath = normalizeSlashes(fields[1]);
+      gitRef = `${commit}^:${sourcePath}`;
+    } else if (status.startsWith('R') && fields[1] && fields[2]) {
+      const oldPath = normalizeSlashes(fields[1]);
+      const newPath = normalizeSlashes(fields[2]);
+      if (terminalSourceKind(newPath)) {
+        sourcePath = newPath;
+        gitRef = `${commit}:${newPath}`;
+      } else {
+        sourcePath = oldPath;
+        gitRef = `${commit}^:${oldPath}`;
+      }
+    } else {
+      continue;
     }
+    const kind = terminalSourceKind(sourcePath);
+    if (!kind || selected.has(kind)) continue;
+    try {
+      const content = gitText(repoRoot, ['show', gitRef]);
+      selected.set(kind, { sourcePath, gitRef, content, terminalAt });
+    } catch {
+      // A transition without a readable Git snapshot is not safe promotion
+      // evidence. Continue looking for an older durable terminal transition.
+    }
+    if (selected.size === 2) break;
   }
-  return sources;
+  return Array.from(selected.values());
 }
 
 function frontmatterValue(content: string, label: string): string {
@@ -452,39 +537,112 @@ function yamlQuote(value: string): string {
   return JSON.stringify(value);
 }
 
+function modernBrainPromotionSource(repoRoot: string, opts: BrainPromoteOptions, issues: BrainIssue[]): {
+  sources: string[]; sections: string[]; relatedPlan: string; terminalAt: string; outcome: string; sourceWork: string; completionReceipt: string; workScope: string;
+} {
+  const workId = opts.workId?.trim();
+  if (!workId) {
+    issue(issues, 'error', 'Modern Brain promotion requires --work-id; use --legacy-git-history only for retired Git delete/rename imports.');
+    return { sources: [], sections: [], relatedPlan: '', terminalAt: '', outcome: '', sourceWork: '', completionReceipt: '', workScope: '' };
+  }
+  const controllerHome = resolveRepoPreferredControllerHome(repoRoot, opts.controllerHome);
+  const repository = findRegisteredRepositoryByCheckoutRoot(repoRoot, controllerHome);
+  if (!repository) {
+    issue(issues, 'error', `Repository is not registered in Controller Home; cannot resolve Work evidence for ${workId}.`);
+    return { sources: [], sections: [], relatedPlan: '', terminalAt: '', outcome: '', sourceWork: workId, completionReceipt: '', workScope: '' };
+  }
+  const work = getWorkContract({ controllerHome, repoId: repository.repoId }, workId);
+  if (!work) {
+    issue(issues, 'error', `Work not found in registered repository: ${workId}`);
+    return { sources: [], sections: [], relatedPlan: '', terminalAt: '', outcome: '', sourceWork: workId, completionReceipt: '', workScope: '' };
+  }
+  if (!work.scopeRef) {
+    issue(issues, 'error', `Modern Brain promotion requires a portable Work scope: ${workId}; use --legacy-git-history only for retired unscoped imports.`);
+    return { sources: [], sections: [], relatedPlan: work.planId ?? '', terminalAt: '', outcome: '', sourceWork: workId, completionReceipt: '', workScope: '' };
+  }
+  const workScope = `${work.scopeRef.kind}:${work.scopeRef.id}`;
+  if (work.status !== 'completed' || !work.completionReceipt) {
+    issue(issues, 'error', `Brain promotion requires a completed Work with a durable completion receipt: ${workId}`);
+    return { sources: [], sections: [], relatedPlan: work.planId ?? '', terminalAt: '', outcome: '', sourceWork: workId, completionReceipt: '', workScope };
+  }
+  try {
+    validateWorkSemantics(work);
+  } catch (error) {
+    issue(issues, 'error', `Work completion evidence is invalid for Brain promotion: ${error instanceof Error ? error.message : String(error)}`);
+    return { sources: [], sections: [], relatedPlan: work.planId ?? '', terminalAt: '', outcome: '', sourceWork: workId, completionReceipt: work.completionReceipt.receiptId, workScope };
+  }
+  const receipt = work.completionReceipt;
+  const repositoryDetails = ('targetRevision' in receipt)
+    ? [`- Target revision: ${receipt.targetRevision}`, `- Changed paths: ${receipt.changedPaths.length}`]
+    : [];
+  const section = [
+    `## Source: work:${work.workId}`,
+    '',
+    `- Objective: ${work.objective}`,
+    `- Completion outcome: ${work.completionOutcome ?? 'completed'}`,
+    `- Completion receipt: ${receipt.receiptId}`,
+    `- Completion authority: ${receipt.source}`,
+    `- Work scope: ${workScope}`,
+    ...repositoryDetails,
+    '',
+    'This entry is promoted from validated durable Work metadata. Raw process logs, credentials, and chat history are not copied into Brain.',
+    '',
+  ].join('\n');
+  return {
+    sources: [`work:${work.workId}`, `completion:${receipt.receiptId}`],
+    sections: [section], relatedPlan: work.planId ?? '', terminalAt: receipt.recordedAt,
+    outcome: work.completionOutcome ?? 'completed', sourceWork: work.workId,
+    completionReceipt: receipt.receiptId, workScope,
+  };
+}
+
 export function runBrainPromote(opts: BrainPromoteOptions): BrainPromoteResult {
   if (!VALID_CATEGORIES.has(opts.category)) {
     throw new Error(`invalid category "${opts.category}" (expected: ${Array.from(VALID_CATEGORIES).join(', ')})`);
   }
+  if (opts.legacyGitHistory && opts.workId?.trim()) throw new Error('BRAIN_PROMOTION_MODE_CONFLICT');
   const repoRoot = resolveRepoRoot(opts.repo);
   const { manifest } = readManifest(repoRoot);
   const project = manifest.project || path.basename(repoRoot);
   const root = brainRoot();
   const issues: BrainIssue[] = [];
-  const sources = findArchiveSources(repoRoot, opts.slug);
   const brainPath = logicalBrainPath(project, opts.category, `${opts.slug}.md`);
   const targetPath = safeBrainPath(root, brainPath, `promote:${opts.slug}`, issues) || path.resolve(root, project, opts.category, `${opts.slug}.md`);
 
-  if (sources.length === 0) {
-    issue(issues, 'error', `No archived plan or notes found for slug: ${opts.slug}`);
+  let sources: string[] = [];
+  let sections: string[] = [];
+  let relatedPlan = '';
+  let terminalAt = '';
+  let outcome = '';
+  let sourceWork = '';
+  let completionReceipt = '';
+  let workScope = '';
+
+  if (opts.legacyGitHistory) {
+    const historicalSources = findTerminalHistorySources(repoRoot, opts.slug);
+    sources = historicalSources.map((source) => `git:${source.gitRef}`);
+    if (historicalSources.length === 0) issue(issues, 'error', `No terminal plan or notes found in Git history for slug: ${opts.slug}`);
+    sections = historicalSources.map((source) => `## Source: git:${source.gitRef}\n\n${source.content.trim()}\n`);
+    const firstContent = historicalSources[0]?.content ?? '';
+    const relatedPlanSource = historicalSources.find((source) => terminalSourceKind(source.sourcePath) === 'plan');
+    relatedPlan = relatedPlanSource ? `git:${relatedPlanSource.gitRef}` : frontmatterValue(firstContent, 'Related Plan');
+    terminalAt = historicalSources[0]?.terminalAt || frontmatterValue(firstContent, 'Archived') || new Date().toISOString();
+    outcome = frontmatterValue(firstContent, 'Outcome') || 'Promoted';
+  } else {
+    const modern = modernBrainPromotionSource(repoRoot, opts, issues);
+    ({ sources, sections, relatedPlan, terminalAt, outcome, sourceWork, completionReceipt, workScope } = modern);
   }
 
-  const sections = sources.map((sourcePath) => {
-    const content = fs.readFileSync(path.resolve(repoRoot, sourcePath), 'utf-8');
-    const title = sourcePath;
-    return `## Source: ${title}\n\n${content.trim()}\n`;
-  });
-  const firstContent = sources.length > 0 ? fs.readFileSync(path.resolve(repoRoot, sources[0]), 'utf-8') : '';
-  const relatedPlan = sources.find((source) => source.startsWith('plans/archive/')) || frontmatterValue(firstContent, 'Related Plan');
-  const archivedAt = frontmatterValue(firstContent, 'Archived') || new Date().toISOString();
-  const outcome = frontmatterValue(firstContent, 'Outcome') || 'Promoted';
   const body = [
     '---',
     `slug: ${yamlQuote(opts.slug)}`,
     `category: ${yamlQuote(opts.category)}`,
     `source_plan: ${yamlQuote(relatedPlan || '')}`,
-    `archived_at: ${yamlQuote(archivedAt)}`,
-    `outcome: ${yamlQuote(outcome)}`,
+    ...(sourceWork ? [`source_work: ${yamlQuote(sourceWork)}`] : []),
+    ...(completionReceipt ? [`completion_receipt: ${yamlQuote(completionReceipt)}`] : []),
+    ...(workScope ? [`work_scope: ${yamlQuote(workScope)}`] : []),
+    `terminal_at: ${yamlQuote(terminalAt || '')}`,
+    `outcome: ${yamlQuote(outcome || '')}`,
     `repo: ${yamlQuote(repoRoot)}`,
     '---',
     '',
@@ -500,17 +658,8 @@ export function runBrainPromote(opts: BrainPromoteOptions): BrainPromoteResult {
   }
 
   return {
-    repoRoot,
-    brainRoot: root,
-    project,
-    slug: opts.slug,
-    category: opts.category,
-    targetPath,
-    brainPath,
-    sources,
-    issues,
-    dryRun: opts.dryRun === true,
-    written: !hasErrors && !opts.dryRun,
+    repoRoot, brainRoot: root, project, slug: opts.slug, category: opts.category, targetPath, brainPath,
+    sources, issues, dryRun: opts.dryRun === true, written: !hasErrors && !opts.dryRun,
   };
 }
 
@@ -551,7 +700,8 @@ function exitCodeFor(issues: BrainIssue[]): number {
 }
 
 export function buildBrainCommand(): Command {
-  const brain = new Command('brain').description('Manage explicit repo-to-brain sync and archive promotion');
+  const brain = new Command('brain').description('Manage explicit repo-to-brain sync and terminal-workflow promotion');
+  addBrainAssistantCommands(brain);
 
   brain
     .command('status')
@@ -593,10 +743,13 @@ export function buildBrainCommand(): Command {
 
   brain
     .command('promote')
-    .description('Promote archived plan/notes by slug into ~/brain/<project>/<category>/')
-    .requiredOption('--slug <slug>', 'Archived workflow slug')
+    .description('Promote one validated terminal Work into ~/brain/<project>/<category>/; Git-history import is explicit legacy compatibility only')
+    .requiredOption('--slug <slug>', 'Brain entry slug')
     .requiredOption('--category <category>', 'Target category: decisions|runbooks|patterns|references')
     .option('--repo <path>', 'Repository root to inspect')
+    .option('--work-id <id>', 'Completed Work identity for modern promotion')
+    .option('--controller-home <path>', 'Override Controller Home used to resolve the registered repository and Work')
+    .option('--legacy-git-history', 'Explicitly use retired Git delete/rename promotion compatibility')
     .option('--dry-run', 'Show planned promotion without writing files')
     .option('--json', 'Output JSON instead of human-readable text')
     .action((rawOpts: BrainPromoteOptions) => {

package/src/cli/commands/chatgpt.ts

@@ -18,6 +18,7 @@ import {
   type ChatgptAutomationReasoning,
   type ChatgptAutomationTabPolicy,
 } from '../../runtime/control-plane/launcher/chatgpt-work-continuation';
+import { closeChatgptControllerRoundFromSource, continueChatgptControllerRoundFromSource, openChatgptControllerRoundFromSource } from '../../runtime/control-plane/launcher/chatgpt-round-continuation';
 
 interface BrowserCommonOptions {
   repo?: string;
@@ -92,6 +93,45 @@ interface WorkChatgptContinueOptions extends BrowserCommonOptions {
   reasoning?: string;
   tabPolicy?: string;
   timeoutMs?: string;
+  controllerAuthorityId?: string;
+  relayScopeId?: string;
+}
+
+interface SourceRoundOpenOptions extends BrowserCommonOptions {
+  controllerHome?: string;
+  repoId: string;
+  workId: string;
+  controllerId: string;
+  principalId: string;
+  controllerInstanceId?: string;
+  continuationPrompt?: string;
+  timeoutMs?: string;
+}
+
+interface SourceRoundContinueOptions extends BrowserCommonOptions {
+  controllerHome?: string;
+  repoId: string;
+  workId: string;
+  controllerAuthorityId: string;
+  relayScopeId: string;
+  reason?: string;
+  timeoutMs?: string;
+}
+
+interface SourceRoundCloseOptions extends BrowserCommonOptions {
+  controllerHome?: string;
+  repoId: string;
+  workId: string;
+  controllerAuthorityId: string;
+  relayScopeId: string;
+  disposition: string;
+  handoffId?: string;
+  reason?: string;
+}
+
+function sourceRoundCloseDisposition(value: string): 'wait' | 'wait_for_user' | 'goal_complete' {
+  if (value === 'wait' || value === 'wait_for_user' || value === 'goal_complete') return value;
+  throw new Error(`CONTROLLER_RELAY_DISPOSITION_INVALID: ${value}`);
 }
 
 interface BrowserFollowupOptions extends BrowserCommonOptions {
@@ -409,6 +449,8 @@ export function buildChatgptCommand(): Command {
     .option('--reasoning <level>', 'Reasoning level: medium|high|xhigh', 'high')
     .option('--tab-policy <policy>', 'Browser tab policy: auto|reuse|new', 'auto')
     .option('--timeout-ms <ms>', 'Assistant timeout in milliseconds')
+    .option('--controller-authority-id <id>', 'Durable ControllerRound authority for source-mode continuation')
+    .option('--relay-scope-id <id>', 'Durable ControllerRound relay scope paired with controller authority')
     .action((rawOpts: WorkChatgptContinueOptions) => {
       void runChatgptAction(async () => {
         const result = await runWorkChatgptContinuation({
@@ -417,6 +459,8 @@ export function buildChatgptCommand(): Command {
           repoRoot: resolveRepoRoot(rawOpts.repo),
           workId: rawOpts.workId,
           prompt: rawOpts.prompt,
+          controllerAuthorityId: rawOpts.controllerAuthorityId,
+          relayScopeId: rawOpts.relayScopeId,
           title: rawOpts.title,
           browserSessionId: rawOpts.session,
           conversationUrl: rawOpts.conversationUrl,
@@ -443,6 +487,89 @@ export function buildChatgptCommand(): Command {
     });
   chatgpt.addCommand(workContinue, { hidden: true });
 
+  const roundOpen = new Command('round-open')
+    .description('Internal: open and dispatch one ChatGPT ControllerRound from current source')
+    .option('--repo <path>', 'Repository root used by the ChatGPT Browser delivery host', '.')
+    .option('--controller-home <path>', 'Explicit Controller Home containing ControllerRound authority; defaults to canonical user-level Forge Controller Home')
+    .requiredOption('--repo-id <repo-id>', 'Stable Forge repository id')
+    .requiredOption('--work-id <work-id>', 'Forge Work id to dispatch')
+    .requiredOption('--controller-id <id>', 'Authenticated ChatGPT controller id/principal identity')
+    .requiredOption('--principal-id <id>', 'Authenticated ChatGPT principal id')
+    .option('--controller-instance-id <id>', 'Source launcher instance identity')
+    .option('--continuation-prompt <text>', 'Bounded source-mode continuation instruction')
+    .option('--timeout-ms <ms>', 'Assistant dispatch timeout in milliseconds')
+    .action((rawOpts: SourceRoundOpenOptions) => {
+      void runChatgptAction(async () => {
+        const result = await openChatgptControllerRoundFromSource({
+          controllerHome: durableControllerHome(rawOpts.controllerHome),
+          repoId: rawOpts.repoId,
+          repoRoot: resolveRepoRoot(rawOpts.repo),
+          workId: rawOpts.workId,
+          controllerId: rawOpts.controllerId,
+          principalId: rawOpts.principalId,
+          controllerInstanceId: rawOpts.controllerInstanceId,
+          continuationPrompt: rawOpts.continuationPrompt,
+          timeoutMs: parsePositiveInteger('timeout-ms', rawOpts.timeoutMs),
+        });
+        console.log(JSON.stringify(result, null, 2));
+      });
+    });
+  chatgpt.addCommand(roundOpen, { hidden: true });
+
+  const roundContinue = new Command('round-continue')
+    .description('Internal: close one claimed ChatGPT ControllerRound and immediately dispatch its successor from current source')
+    .option('--repo <path>', 'Repository root used by the ChatGPT Browser delivery host', '.')
+    .option('--controller-home <path>', 'Explicit Controller Home containing ControllerRound authority; defaults to canonical user-level Forge Controller Home')
+    .requiredOption('--repo-id <repo-id>', 'Stable Forge repository id')
+    .requiredOption('--work-id <work-id>', 'Currently claimed Forge Work id')
+    .requiredOption('--controller-authority-id <id>', 'Exact durable ControllerRound authority')
+    .requiredOption('--relay-scope-id <id>', 'Exact durable ControllerRound relay scope')
+    .option('--reason <text>', 'Bounded semantic continuation reason')
+    .option('--timeout-ms <ms>', 'Assistant dispatch timeout in milliseconds')
+    .action((rawOpts: SourceRoundContinueOptions) => {
+      void runChatgptAction(async () => {
+        const result = await continueChatgptControllerRoundFromSource({
+          controllerHome: durableControllerHome(rawOpts.controllerHome),
+          repoId: rawOpts.repoId,
+          repoRoot: resolveRepoRoot(rawOpts.repo),
+          workId: rawOpts.workId,
+          controllerAuthorityId: rawOpts.controllerAuthorityId,
+          relayScopeId: rawOpts.relayScopeId,
+          reason: rawOpts.reason,
+          timeoutMs: parsePositiveInteger('timeout-ms', rawOpts.timeoutMs),
+        });
+        console.log(JSON.stringify(result, null, 2));
+      });
+    });
+  chatgpt.addCommand(roundContinue, { hidden: true });
+
+  const roundClose = new Command('round-close')
+    .description('Internal: reconcile and close one claimed ChatGPT ControllerRound from current source without dispatching a successor')
+    .option('--controller-home <path>', 'Explicit Controller Home containing ControllerRound authority; defaults to canonical user-level Forge Controller Home')
+    .requiredOption('--repo-id <repo-id>', 'Stable Forge repository id')
+    .requiredOption('--work-id <work-id>', 'Currently claimed Forge Work id')
+    .requiredOption('--controller-authority-id <id>', 'Exact durable ControllerRound authority')
+    .requiredOption('--relay-scope-id <id>', 'Exact durable ControllerRound relay scope')
+    .requiredOption('--disposition <value>', 'Terminal semantic disposition: wait, wait_for_user, or goal_complete')
+    .option('--handoff-id <id>', 'Required active Handoff id when disposition is wait_for_user')
+    .option('--reason <text>', 'Bounded semantic close reason')
+    .action((rawOpts: SourceRoundCloseOptions) => {
+      void runChatgptAction(() => {
+        const result = closeChatgptControllerRoundFromSource({
+          controllerHome: durableControllerHome(rawOpts.controllerHome),
+          repoId: rawOpts.repoId,
+          workId: rawOpts.workId,
+          controllerAuthorityId: rawOpts.controllerAuthorityId,
+          relayScopeId: rawOpts.relayScopeId,
+          disposition: sourceRoundCloseDisposition(rawOpts.disposition),
+          handoffId: rawOpts.handoffId,
+          reason: rawOpts.reason,
+        });
+        console.log(JSON.stringify(result, null, 2));
+      });
+    });
+  chatgpt.addCommand(roundClose, { hidden: true });
+
   chatgpt
     .command('browser-open')
     .description('Print a saved ChatGPT browser session conversation URL; pass --launch to open it in the system browser')