@moretea-labs/forge 1.5.0-rc.1

package/src/cli/controller/work-mode.ts

@@ -0,0 +1,186 @@
+import type { TaskRisk } from './types';
+import {
+  decideRoute,
+  type ExplicitTaskMode,
+  type RouteDecision,
+  type RoutePolicyInput,
+} from '../../runtime/control-plane/routing/route-policy';
+
+export type WorkMode = 'direct_edit' | 'bounded_work' | 'quick_agent' | 'issue_task' | 'campaign';
+export type ExecutionPathPreference = 'fast' | 'durable' | 'campaign';
+export type EffectiveTaskMode = ExplicitTaskMode | 'bounded';
+
+export interface WorkModeAssessmentInput {
+  description: string;
+  knownPaths?: string[];
+  expectedFiles?: number;
+  expectedChangedLines?: number;
+  requiresInvestigation?: boolean;
+  requiresParallelism?: boolean;
+  requiresLongRunningChecks?: boolean;
+  needsDependencies?: boolean;
+  requiresIndependentDeliverables?: boolean;
+  independentTaskCount?: number;
+  risk?: TaskRisk;
+  requiresRemoteWrite?: boolean;
+  requiresRecovery?: boolean;
+  requiresWorkerIsolation?: boolean;
+  agentRequested?: boolean;
+  explicitMode?: ExplicitTaskMode | `-${ExplicitTaskMode}`;
+  /** Migration/testing escape hatch: adapters must return this exact policy decision. */
+  routePolicyInput?: RoutePolicyInput;
+}
+
+export interface WorkModeAssessment {
+  recommendedMode: WorkMode;
+  executionPath: ExecutionPathPreference;
+  confidence: 'high' | 'medium';
+  reasons: string[];
+  nextTools: string[];
+  issueRequired: boolean;
+  campaignRequired: boolean;
+  taskMode: EffectiveTaskMode;
+  explicitMode: ExplicitTaskMode | null;
+  modeBehavior: {
+    structuralContext: 'off' | 'required';
+    mutationPhase: 'execute' | 'plan_only' | 'diagnose_first' | 'read_only' | 'coordinate' | 'release_gate' | 'benchmark';
+    issueRequired: boolean;
+    planRequired: boolean;
+    worktreeRequired: boolean;
+    workflow: string[];
+  };
+  /** Replayable evidence from the single Route Policy authority. */
+  routeDecision: RouteDecision;
+}
+
+export function parseExplicitTaskMode(value: unknown): ExplicitTaskMode | undefined {
+  if (typeof value !== 'string') return undefined;
+  if (!value) return undefined;
+  const normalized = value.replace(/^-/, '') as ExplicitTaskMode;
+  return ['direct', 'plan', 'debug', 'review', 'campaign', 'release', 'scale'].includes(normalized)
+    ? normalized
+    : undefined;
+}
+
+function behaviorFor(mode: EffectiveTaskMode): WorkModeAssessment['modeBehavior'] {
+  switch (mode) {
+    case 'direct': return {
+      structuralContext: 'off', mutationPhase: 'execute', issueRequired: false, planRequired: false, worktreeRequired: false,
+      workflow: ['search/read exact known scope', 'edit 1-2 low-risk files', 'run focused checks', 'commit'],
+    };
+    case 'plan': return {
+      structuralContext: 'required', mutationPhase: 'plan_only', issueRequired: false, planRequired: true, worktreeRequired: false,
+      workflow: ['query CodeGraph structure', 'inspect cross-module contracts', 'write a decision-complete plan', 'do not mutate implementation'],
+    };
+    case 'debug': return {
+      structuralContext: 'required', mutationPhase: 'diagnose_first', issueRequired: false, planRequired: false, worktreeRequired: false,
+      workflow: ['reproduce', 'collect logs and traces', 'query CodeGraph callers and dependencies', 'identify root cause before mutation', 'apply focused fix and regression test'],
+    };
+    case 'review': return {
+      structuralContext: 'off', mutationPhase: 'read_only', issueRequired: false, planRequired: false, worktreeRequired: false,
+      workflow: ['read diff and affected source', 'review correctness and regressions', 'review lifecycle, concurrency, and security', 'report test gaps without mutation'],
+    };
+    case 'campaign': return {
+      structuralContext: 'off', mutationPhase: 'coordinate', issueRequired: false, planRequired: false, worktreeRequired: true,
+      workflow: ['decompose independent deliverables', 'create campaign', 'schedule isolated Tasks', 'reconcile and review campaign evidence'],
+    };
+    case 'release': return {
+      structuralContext: 'off', mutationPhase: 'release_gate', issueRequired: false, planRequired: false, worktreeRequired: false,
+      workflow: ['verify checks and changelog', 'build immutable complete release', 'run integration and deployment gates', 'activate through Recovery', 'verify rollback evidence'],
+    };
+    case 'scale': return {
+      structuralContext: 'off', mutationPhase: 'benchmark', issueRequired: false, planRequired: false, worktreeRequired: true,
+      workflow: ['model concurrency and scheduling', 'run isolated large-load execution', 'measure queue, lease, and worker phases', 'publish benchmark evidence'],
+    };
+    default: return {
+      structuralContext: 'off', mutationPhase: 'execute', issueRequired: false, planRequired: false, worktreeRequired: false,
+      workflow: ['start resumable bounded Work', 'implement within declared scope', 'verify focused checks', 'finalize durable evidence'],
+    };
+  }
+}
+
+function nextTools(decision: RouteDecision, investigation: boolean): string[] {
+  if (decision.workMode === 'campaign') return ['create_campaign', 'add_campaign_task', 'reconcile_campaign', 'get_campaign_review_packet'];
+  if (decision.workMode === 'issue_task') return ['inspect_issue_readiness', 'create_issue or append_task', 'dispatch_task', 'verify_task', 'accept_task'];
+  if (decision.workMode === 'quick_agent') return ['search_repository', 'rh_work(operation=delegate)', 'rh_work(operation=continue)', 'rh_work(operation=verify)'];
+  if (decision.workMode === 'bounded_work') return [
+    ...(investigation ? ['rh_context', 'search_repository'] : []),
+    'rh_work(operation=start)',
+    'rh_work(operation=continue)',
+    'rh_work(operation=verify)',
+    'rh_work(operation=finalize)',
+  ];
+  return [
+    ...(investigation ? ['search_repository', 'repository_workbench(operation=batch_execute reads)'] : []),
+    'repository_workbench(operation=batch_execute)',
+    'read_repository_file',
+    'begin_edit_session',
+    'apply_patch',
+    'get_edit_session_diff',
+    'verify_edit_session',
+    'finalize_edit_session',
+    'finish_edit_session',
+  ];
+}
+
+/** @deprecated Compatibility adapter. Route Policy is the sole routing authority. */
+export function assessWorkMode(input: WorkModeAssessmentInput): WorkModeAssessment {
+  if (!input.description.trim()) throw new Error('work description is required');
+  const explicitMode = parseExplicitTaskMode(input.explicitMode);
+  const investigationMode = explicitMode === 'plan' || explicitMode === 'debug' || explicitMode === 'review';
+  const readonlyMode = investigationMode;
+  const parallelMode = explicitMode === 'campaign' || explicitMode === 'scale';
+  const routeDecision = decideRoute(input.routePolicyInput ?? {
+    intent: {
+      objective: input.description,
+      scopeClear: explicitMode === 'direct' || (input.knownPaths?.length ?? 0) > 0 || input.requiresInvestigation === true || investigationMode,
+      mutation: readonlyMode ? false : input.risk !== 'readonly',
+      expectedFiles: input.expectedFiles,
+      expectedChangedLines: input.expectedChangedLines,
+      requiresInvestigation: explicitMode === 'direct' ? false : input.requiresInvestigation || investigationMode,
+      requiresParallelism: explicitMode === 'direct' ? false : input.requiresParallelism || parallelMode,
+      requiresLongRunningChecks: input.requiresLongRunningChecks || explicitMode === 'release' || explicitMode === 'scale',
+      needsDependencies: input.needsDependencies,
+      requiresIndependentDeliverables: input.requiresIndependentDeliverables || parallelMode,
+      independentTaskCount: parallelMode ? Math.max(2, input.independentTaskCount ?? 0) : input.independentTaskCount,
+      agentRequested: input.agentRequested,
+      taskIntent: explicitMode === 'plan' ? 'architecture_planning' : explicitMode === 'review' ? 'review' : explicitMode === 'debug' ? 'code_repair' : undefined,
+      explicitMode,
+    },
+    workspace: { knownPaths: input.knownPaths },
+    policy: {
+      risk: readonlyMode ? 'readonly' : input.risk,
+      remoteWrite: input.requiresRemoteWrite,
+      requiresApproval: input.requiresRemoteWrite,
+    },
+    capabilities: { requiresWorker: input.agentRequested },
+    recovery: {
+      required: input.requiresRecovery || explicitMode === 'debug' || explicitMode === 'release' || explicitMode === 'scale',
+      isolationRequired: explicitMode === 'direct' ? false : input.requiresWorkerIsolation || parallelMode,
+    },
+  });
+  const taskMode: EffectiveTaskMode = explicitMode
+    ?? (routeDecision.workMode === 'campaign' ? 'campaign' : routeDecision.workMode === 'direct_edit' ? 'direct' : 'bounded');
+  const modeBehavior = behaviorFor(taskMode);
+  return {
+    recommendedMode: routeDecision.workMode,
+    executionPath: routeDecision.executionPath,
+    confidence: input.requiresInvestigation || (input.knownPaths?.length ?? 0) === 0 ? 'medium' : 'high',
+    reasons: routeDecision.reasons.map((reason) => reason.message),
+    nextTools: explicitMode === 'plan' || explicitMode === 'debug'
+      ? ['controller_context_pack(structural_context=required)', ...modeBehavior.workflow]
+      : explicitMode === 'review'
+        ? ['repository_git_status', 'repository_diff', ...modeBehavior.workflow]
+        : explicitMode === 'release'
+          ? ['run_check', 'request_release_gate', 'capability_recovery_plan', 'capability_recovery_apply', 'controller_ready']
+          : explicitMode === 'scale'
+            ? ['create_campaign', 'process_start', 'process_wait', 'benchmark evidence']
+            : nextTools(routeDecision, input.requiresInvestigation === true || investigationMode || (input.knownPaths?.length ?? 0) === 0),
+    issueRequired: routeDecision.workMode === 'issue_task',
+    campaignRequired: routeDecision.workMode === 'campaign',
+    taskMode,
+    explicitMode: explicitMode ?? null,
+    modeBehavior,
+    routeDecision,
+  };
+}

package/src/cli/controller/worklog.ts

@@ -0,0 +1,201 @@
+import { randomBytes } from "crypto";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "fs";
+import { dirname, isAbsolute, join, relative, resolve } from "path";
+
+const WORKLOG_PATH = ".ai/harness/controller/worklog.jsonl";
+
+export const WORKLOG_CATEGORIES = [
+  "issue",
+  "task",
+  "run",
+  "verification",
+  "edit",
+  "github",
+  "local_job",
+  "system",
+] as const;
+
+export type WorklogCategory = (typeof WORKLOG_CATEGORIES)[number];
+
+export function parseWorklogCategory(value: unknown): WorklogCategory | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (typeof value === "string" && WORKLOG_CATEGORIES.includes(value as WorklogCategory)) {
+    return value as WorklogCategory;
+  }
+  throw new Error(`invalid worklog category: ${String(value)}`);
+}
+
+export interface ControllerWorklogEvent {
+  schemaVersion: 1;
+  id: string;
+  at: string;
+  category: WorklogCategory;
+  action: string;
+  summary: string;
+  actor: string;
+  issueId?: string;
+  taskId?: string;
+  runId?: string;
+  jobId?: string;
+  editSessionId?: string;
+  statusFrom?: string;
+  statusTo?: string;
+  details?: Record<string, unknown>;
+}
+
+export interface WorklogFilter {
+  category?: WorklogCategory;
+  issueId?: string;
+  taskId?: string;
+  runId?: string;
+  jobId?: string;
+  editSessionId?: string;
+  since?: string;
+  until?: string;
+  limit?: number;
+}
+
+function worklogPath(repoRoot: string): string {
+  return join(repoRoot, WORKLOG_PATH);
+}
+
+function eventId(): string {
+  return `WL-${Date.now().toString(36).toUpperCase()}-${randomBytes(3).toString("hex").toUpperCase()}`;
+}
+
+export function appendControllerWorklogEvent(
+  repoRoot: string,
+  event: Omit<ControllerWorklogEvent, "schemaVersion" | "id" | "at" | "actor"> & {
+    at?: string;
+    actor?: string;
+  },
+): ControllerWorklogEvent {
+  const record: ControllerWorklogEvent = {
+    schemaVersion: 1,
+    id: eventId(),
+    at: event.at ?? new Date().toISOString(),
+    actor: event.actor?.trim() || "forge-controller",
+    category: event.category,
+    action: event.action,
+    summary: event.summary,
+    issueId: event.issueId,
+    taskId: event.taskId,
+    runId: event.runId,
+    jobId: event.jobId,
+    editSessionId: event.editSessionId,
+    statusFrom: event.statusFrom,
+    statusTo: event.statusTo,
+    details: event.details,
+  };
+  const path = worklogPath(repoRoot);
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(record)}\n`, "utf-8");
+  return record;
+}
+
+export function tryAppendControllerWorklogEvent(
+  repoRoot: string,
+  event: Parameters<typeof appendControllerWorklogEvent>[1],
+): void {
+  try {
+    appendControllerWorklogEvent(repoRoot, event);
+  } catch (_error) {
+    // Worklog recording is evidence enrichment. It must not corrupt the source mutation.
+  }
+}
+
+export function listControllerWorklogEvents(
+  repoRoot: string,
+  filter: WorklogFilter = {},
+): ControllerWorklogEvent[] {
+  const path = worklogPath(repoRoot);
+  if (!existsSync(path)) return [];
+  const since = filter.since ? Date.parse(filter.since) : Number.NEGATIVE_INFINITY;
+  const until = filter.until ? Date.parse(filter.until) : Number.POSITIVE_INFINITY;
+  const events = readFileSync(path, "utf-8")
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .flatMap((line) => {
+      try {
+        return [JSON.parse(line) as ControllerWorklogEvent];
+      } catch (_error) {
+        return [];
+      }
+    })
+    .filter((event) => {
+      const at = Date.parse(event.at);
+      return (
+        (!filter.category || event.category === filter.category) &&
+        (!filter.issueId || event.issueId === filter.issueId) &&
+        (!filter.taskId || event.taskId === filter.taskId) &&
+        (!filter.runId || event.runId === filter.runId) &&
+        (!filter.jobId || event.jobId === filter.jobId) &&
+        (!filter.editSessionId || event.editSessionId === filter.editSessionId) &&
+        at >= since &&
+        at <= until
+      );
+    })
+    .sort((a, b) => b.at.localeCompare(a.at));
+  return events.slice(0, Math.max(1, Math.min(filter.limit ?? 200, 5000)));
+}
+
+function markdownEscape(value: unknown): string {
+  return String(value ?? "").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+
+export function exportControllerWorklog(
+  repoRoot: string,
+  options: {
+    format?: "markdown" | "json";
+    outputPath?: string;
+    filter?: WorklogFilter;
+  } = {},
+): { path: string; format: "markdown" | "json"; eventCount: number } {
+  const format = options.format ?? "markdown";
+  const events = listControllerWorklogEvents(repoRoot, {
+    ...options.filter,
+    limit: options.filter?.limit ?? 5000,
+  }).slice().reverse();
+  const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+  const defaultPath = `tasks/reports/controller-worklog-${stamp}.${format === "json" ? "json" : "md"}`;
+  const outputPath = options.outputPath?.trim() || defaultPath;
+  const absolute = resolve(repoRoot, outputPath);
+  const relativeOutput = relative(repoRoot, absolute);
+  if (!relativeOutput || relativeOutput.startsWith("..") || isAbsolute(relativeOutput)) {
+    throw new Error("worklog output path must stay inside the repository");
+  }
+  mkdirSync(dirname(absolute), { recursive: true });
+  if (format === "json") {
+    writeFileSync(absolute, `${JSON.stringify({ generatedAt: new Date().toISOString(), events }, null, 2)}\n`, "utf-8");
+  } else {
+    const lines = [
+      "---",
+      `generated_at: ${JSON.stringify(new Date().toISOString())}`,
+      'source: "forge"',
+      `event_count: ${events.length}`,
+      "---",
+      "",
+      "# Controller Worklog",
+      "",
+      "| Time | Category | Action | Scope | Summary | Actor |",
+      "| --- | --- | --- | --- | --- | --- |",
+      ...events.map((event) => {
+        const scope = [event.issueId, event.taskId, event.runId, event.jobId, event.editSessionId].filter(Boolean).join(" / ") || "project";
+        return `| ${markdownEscape(event.at)} | ${markdownEscape(event.category)} | ${markdownEscape(event.action)} | ${markdownEscape(scope)} | ${markdownEscape(event.summary)} | ${markdownEscape(event.actor)} |`;
+      }),
+      "",
+    ];
+    writeFileSync(absolute, lines.join("\n"), "utf-8");
+  }
+  return { path: relative(repoRoot, absolute).replace(/\\/g, "/"), format, eventCount: events.length };
+}
+
+export function controllerWorklogLocation(): string {
+  return WORKLOG_PATH;
+}

package/src/cli/diagnostic-entry.ts

@@ -0,0 +1,39 @@
+import { resolve } from 'path';
+import { getRepository } from './repositories/registry';
+import { executeReadOnlyDiagnostic, isReadOnlyDiagnosticTool } from '../runtime/diagnostics/read-only-tool';
+
+function requiredOption(argv: string[], name: string): string {
+  const index = argv.indexOf(name);
+  const value = index >= 0 ? argv[index + 1]?.trim() : undefined;
+  if (!value) throw new Error(`DIAGNOSTIC_OPTION_REQUIRED: ${name}`);
+  return value;
+}
+
+export async function runImmutableDiagnosticCli(argv = process.argv.slice(1)): Promise<void> {
+  const commandIndex = argv.indexOf('runtime');
+  if (commandIndex < 0 || argv[commandIndex + 1] !== 'diagnostic-read') {
+    throw new Error('DIAGNOSTIC_USAGE: runtime diagnostic-read --controller-home <path> --repo-id <id> --tool <name> --args-base64 <payload>');
+  }
+  const controllerHome = resolve(requiredOption(argv, '--controller-home'));
+  const repoId = requiredOption(argv, '--repo-id');
+  const tool = requiredOption(argv, '--tool');
+  const argsBase64 = requiredOption(argv, '--args-base64');
+  if (!isReadOnlyDiagnosticTool(tool)) throw new Error(`DIAGNOSTIC_TOOL_UNSUPPORTED: ${tool}`);
+  const repository = getRepository(repoId, controllerHome);
+  if (!repository) throw new Error(`REPOSITORY_NOT_FOUND: ${repoId}`);
+  let args: Record<string, unknown>;
+  try {
+    const decoded = JSON.parse(Buffer.from(argsBase64, 'base64url').toString('utf8')) as unknown;
+    if (!decoded || typeof decoded !== 'object' || Array.isArray(decoded)) throw new Error('arguments must be a JSON object');
+    args = decoded as Record<string, unknown>;
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`DIAGNOSTIC_ARGUMENTS_INVALID: ${detail}`);
+  }
+  process.stdout.write(JSON.stringify(await executeReadOnlyDiagnostic(tool, controllerHome, repository, args)));
+}
+
+void runImmutableDiagnosticCli().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});