@moretea-labs/forge 1.7.2 → 1.8.1

package/supervisor/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["./**/*.ts"],
+  "exclude": []
+}

package/supervisor/types.ts

@@ -0,0 +1,255 @@
+export type WorkflowSupervisorAction = 'CONTINUE' | 'DONE' | 'NEEDS_USER';
+export type WorkflowSupervisorState = 'running' | 'done' | 'needs_user';
+export type WorkflowSupervisorTerminalState = 'DONE' | 'NEEDS_USER' | 'STOPPED';
+/** Machine receipt attached to Forge MCP calls made by an autonomous ChatGPT turn. */
+export type WorkflowSupervisorAutomationStatus = 'working' | 'continue' | 'done' | 'needs_user';
+export type WorkflowEffectKind = 'enrollment' | 'continuation' | 'correction' | 'recovery';
+export type WorkflowEffectOutcome = 'applied' | 'not_applied' | 'unknown';
+
+/** Minimal machine-readable context carried into one autonomous provider turn. */
+export interface WorkflowSupervisorTurnEnvelope {
+  schema_version: 2;
+  identity: {
+    task_id: string;
+    effect_id: string;
+    kind: WorkflowEffectKind;
+  };
+  /** Semantic outcome to pursue. It is context, not an execution-plan DSL. */
+  goal: {
+    role: 'outcome';
+    objective: string;
+  };
+  /** Prior-turn continuity is evidence for orientation, never an execution constraint. */
+  continuity?: {
+    role: 'advisory';
+    summary: string;
+  };
+  repository?: {
+    repo_id: string;
+    checkout_id?: string;
+  };
+  cognition?: {
+    role: 'advisory';
+    projection: string;
+  };
+  automation: {
+    automation_task_id: string;
+    automation_type: 'autonomous_continuation';
+    intermediate_status: 'working';
+    final_statuses: ['continue', 'done', 'needs_user'];
+  };
+}
+
+export interface WorkflowSupervisorProposal {
+  action: WorkflowSupervisorAction;
+  sourceEffectId: string;
+  checkpoint: string;
+  reason: string;
+  evidence: string[];
+  /** Required by newly-rendered prompts; optional only for already-reserved legacy effects. */
+  conversationId?: string;
+  /** Stable Supervisor task identity, distinct from lower-layer Work authority. */
+  taskId?: string;
+  /** Redundant with action by design so a response carries an explicit machine state. */
+  supervisorState?: WorkflowSupervisorState;
+  /** Exact durable lower-layer relay scope such as requirement:<id> or goal:<id>. */
+  activeScope?: string;
+}
+
+export interface WorkflowSupervisorTaskInput {
+  taskId: string;
+  conversationId: string;
+  conversationUrl: string;
+  objective: string;
+  completionContract: Record<string, unknown>;
+  continuationPolicy: Record<string, unknown>;
+  userBlockerPolicy: Record<string, unknown>;
+}
+
+export interface WorkflowSupervisorTask extends WorkflowSupervisorTaskInput {
+  createdAt: string;
+}
+
+export interface WorkflowSupervisorEffect {
+  effectId: string;
+  taskId: string;
+  kind: WorkflowEffectKind;
+  sourceCompletionFingerprint?: string;
+  prompt: string;
+  createdAt: string;
+}
+
+export interface WorkflowSupervisorCompletion {
+  completionFingerprint: string;
+  taskId: string;
+  sourceEffectId: string;
+  action: WorkflowSupervisorAction;
+  responseSha256: string;
+  controlBlockSha256: string;
+  proposal: WorkflowSupervisorProposal;
+  committedAt: string;
+}
+
+/** Read-only proof derived from the existing effect/completion ledger. */
+export interface WorkflowSupervisorContinuationProof {
+  taskId: string;
+  conversationId: string;
+  activeReleaseId: string;
+  actions: ['CONTINUE', 'CONTINUE'];
+  completionFingerprints: [string, string];
+  sourceEffectIds: [string, string];
+  runtimeInstanceIds: string[];
+  firstCommittedAt: string;
+  lastCommittedAt: string;
+}
+
+/** Ephemeral operational projection for the single native Supervisor effect consumer. */
+export interface WorkflowSupervisorConsumerStatus {
+  enabled: boolean;
+  running: boolean;
+  observedAt: string;
+  lastTickStartedAt?: string;
+  lastTickCompletedAt?: string;
+  lastCommandAttemptAt?: string;
+  nextAttemptAt?: string;
+  transportFailureStreak: number;
+  providerBackpressureMs: number;
+  stalled: boolean;
+  dueCommand?: {
+    taskId: string;
+    conversationId: string;
+    effectId: string;
+    mode: 'send' | 'reconcile';
+    kind: WorkflowEffectKind;
+    createdAt?: string;
+    ageMs?: number;
+  };
+  lastFailure?: {
+    code: string;
+    observedAt: string;
+    taskId?: string;
+    effectId?: string;
+  };
+}
+
+export interface WorkflowContractValidation {
+  valid: boolean;
+  reason: string;
+  evidence?: string[];
+}
+
+/**
+ * Derived, read-only classification of a non-terminal task's causal position.
+ * A mechanically exhausted effect used to make its task silently leave the
+ * delivery queue with no durable projection; this makes that state visible and
+ * names the exact operator action that can move the task forward.
+ */
+export type WorkflowSupervisorTaskStall =
+  | { state: 'terminal' }
+  | { state: 'deliverable'; effectId: string; mode: 'send' | 'reconcile'; generation: number }
+  | { state: 'spaced'; effectId?: string; reason: 'retry_spacing' | 'unknown_observation_spacing' | 'awaiting_completion_receipt' | 'pre_send_infrastructure_blocked' }
+  | { state: 'retryable'; effectId: string; generations: number; maxGenerations: number }
+  | { state: 'provider_resume_exhausted'; effectId: string }
+  | { state: 'inert' };
+
+export interface WorkflowSupervisorValidators {
+  completionContract(task: WorkflowSupervisorTask, proposal: WorkflowSupervisorProposal): Promise<WorkflowContractValidation>;
+  userBlockerPolicy(task: WorkflowSupervisorTask, proposal: WorkflowSupervisorProposal): Promise<WorkflowContractValidation>;
+}
+export interface WorkflowSupervisorLifecycleHooks {
+  /** Resolve the current canonical Work objective at prompt generation time. */
+  canonicalObjectiveForTask?(task: WorkflowSupervisorTask): string | undefined;
+  /** Bounded cognition only; never carries lower-layer authority or lifecycle state. */
+  advisoryCognitionForTask?(task: WorkflowSupervisorTask): string | undefined;
+  /** Derived project identity used only for browser discovery; never a lifecycle authority. */
+  projectScopeForTask?(task: WorkflowSupervisorTask): WorkflowSupervisorProjectScope | undefined;
+  /** Build the one bounded enrollment task for a newly discovered project conversation. */
+  discoveredConversationTask?(conversation: WorkflowSupervisorDiscoveredConversation, scope: WorkflowSupervisorProjectScope): WorkflowSupervisorTaskInput | undefined;
+  /** Admission for a new send only. Never suppress observation of an already-started effect. */
+  browserTaskActive?(task: WorkflowSupervisorTask): boolean;
+  /** Mechanical provenance attached to outbound effect dispatch evidence. */
+  effectDispatchEvidence?(input: { task: WorkflowSupervisorTask; effectId: string }): Record<string, unknown>;
+  /**
+   * Mechanical projection of the canonical Work the turn is meant to advance.
+   * Comparison of the value captured at dispatch with the value observed at
+   * receipt is the only structural proof that a provider turn changed anything.
+   * Absent means the lower layer exposes no such signal, which is never treated
+   * as progress or as its absence.
+   */
+  workProgressFingerprint?(task: WorkflowSupervisorTask): string | undefined;
+  /** Existing lower-layer evidence that this exact reserved effect may already have been dispatched outside Supervisor. */
+  inheritedEffectDispatch?(
+    task: WorkflowSupervisorTask,
+    effect: WorkflowSupervisorEffect,
+  ): { generation: number; dispatchId: string; evidence: Record<string, unknown> } | undefined;
+  /** Idempotent: browser delivery observation may replay the same applied effect. */
+  effectApplied?(
+    task: WorkflowSupervisorTask,
+    effect: WorkflowSupervisorEffect,
+    observation: { observationId: string; evidence?: Record<string, unknown> },
+  ): void;
+  /** Atomically project a newly-created Computer conversation into Work binding authority. */
+  bootstrapConversationBound?(
+    task: WorkflowSupervisorTask,
+    context?: { migratedFromConversationId?: string; migrationRequestId?: string },
+  ): void;
+}
+
+export interface WorkflowAssistantObservation {
+  taskId: string;
+  conversationId: string;
+  responseText: string;
+}
+
+export interface WorkflowAssistantObservationResult {
+  action: WorkflowSupervisorAction;
+  completionFingerprint: string;
+  terminal: boolean;
+  successorEffect?: WorkflowSupervisorEffect;
+  validation?: WorkflowContractValidation;
+  deduplicated: boolean;
+}
+
+export interface WorkflowSupervisorBrowserTask {
+  taskId: string;
+  conversationId: string;
+  conversationUrl: string;
+}
+
+export interface WorkflowSupervisorDiscoveredConversation {
+  conversationId: string;
+  canonicalUrl: string;
+  title?: string;
+  projectTitle?: string;
+  projectUrl?: string;
+}
+
+export interface WorkflowSupervisorDiscoverySnapshot {
+  observedAt: string;
+  conversations: WorkflowSupervisorDiscoveredConversation[];
+}
+
+export interface WorkflowSupervisorProjectScope {
+  title: string;
+  /** Additional stable names used by the external Project surface. */
+  aliases?: string[];
+  repoId?: string;
+  controllerHome?: string;
+}
+
+export interface WorkflowSupervisorBrowserCommand {
+  mode: 'send' | 'reconcile';
+  effectId: string;
+  kind: WorkflowEffectKind;
+  prompt: string;
+  dispatchGeneration: number;
+  conversationId: string;
+  conversationUrl: string;
+}
+
+export interface WorkflowSupervisorBrowserPollResult {
+  authorized: true;
+  task: WorkflowSupervisorBrowserTask;
+  terminal?: WorkflowSupervisorTerminalState;
+  command?: WorkflowSupervisorBrowserCommand;
+}

package/assets/templates/helpers/archive-architecture-request.sh

@@ -1,244 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-usage() {
-  cat <<'USAGE_EOF'
-Usage:
-  scripts/archive-architecture-request.sh --request <docs/architecture/requests/file.md> --status <resolved|superseded|rejected|no-change> [--artifact <path>] [--note <text>]
-
-Archives a handled architecture drift request without making semantic architecture decisions.
-USAGE_EOF
-}
-
-repo="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
-repo="$(cd "$repo" && pwd)"
-cd "$repo"
-
-request_file=""
-status=""
-note=""
-artifacts=()
-
-safe_token() {
-  local value="$1"
-  value="$(printf '%s' "$value" | tr '[:upper:]' '[:lower:]')"
-  value="$(printf '%s' "$value" | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//; s/-{2,}/-/g')"
-  printf '%s' "${value:-request}"
-}
-
-repo_relative_path() {
-  local value="$1"
-  value="${value#file://}"
-  case "$value" in
-    "$repo"/*)
-      value="${value#$repo/}"
-      ;;
-    /*)
-      return 1
-      ;;
-    ./*)
-      value="${value#./}"
-      ;;
-  esac
-
-  case "$value" in
-    ""|.|..|../*|*/../*|*$'\n'*|*$'\r'*)
-      return 1
-      ;;
-  esac
-
-  printf '%s' "$value"
-}
-
-canonical_status() {
-  case "$(safe_token "$1")" in
-    resolved)
-      printf 'Resolved'
-      ;;
-    superseded)
-      printf 'Superseded'
-      ;;
-    rejected)
-      printf 'Rejected'
-      ;;
-    no-change|no-architecture-change|no-arch-change)
-      printf 'No architecture change'
-      ;;
-    *)
-      return 1
-      ;;
-  esac
-}
-
-clear_contract_pending_request() {
-  local rel_request="$1"
-  local short_request="${rel_request#docs/architecture/}"
-  local file tmp
-
-  find . \
-    \( -path './.git' -o -path './node_modules' -o -path './_ref' -o -path './_ops' \) -prune -o \
-    \( -name 'AGENTS.md' -o -name 'CLAUDE.md' \) -type f -print 2>/dev/null |
-    while IFS= read -r file; do
-      if ! grep -Fq "Pending architecture request: \`${rel_request}\`" "$file" &&
-         ! grep -Fq "Pending architecture request: \`${short_request}\`" "$file"; then
-        continue
-      fi
-      tmp="$(mktemp)" || continue
-      awk -v rel="$rel_request" -v short="$short_request" '
-        index($0, "Pending architecture request: `" rel "`") > 0 ||
-        index($0, "Pending architecture request: `" short "`") > 0 {
-          print "- Pending architecture request: `(none)`"
-          next
-        }
-        { print }
-      ' "$file" > "$tmp"
-      mv "$tmp" "$file"
-      echo "[ArchitectureArchive] Cleared pending architecture request in ${file#./}"
-    done
-}
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --request)
-      [[ -n "${2:-}" ]] || { echo "archive-architecture-request: --request requires a value" >&2; exit 2; }
-      request_file="$2"
-      shift 2
-      ;;
-    --status)
-      [[ -n "${2:-}" ]] || { echo "archive-architecture-request: --status requires a value" >&2; exit 2; }
-      status="$2"
-      shift 2
-      ;;
-    --artifact)
-      [[ -n "${2:-}" ]] || { echo "archive-architecture-request: --artifact requires a value" >&2; exit 2; }
-      artifacts+=("$2")
-      shift 2
-      ;;
-    --note)
-      [[ -n "${2:-}" ]] || { echo "archive-architecture-request: --note requires a value" >&2; exit 2; }
-      note="$2"
-      shift 2
-      ;;
-    --help|-h)
-      usage
-      exit 0
-      ;;
-    *)
-      echo "archive-architecture-request: unknown argument: $1" >&2
-      usage
-      exit 2
-      ;;
-  esac
-done
-
-if [[ -z "$request_file" || -z "$status" ]]; then
-  usage >&2
-  exit 2
-fi
-
-rel_request="$(repo_relative_path "$request_file" || true)"
-if [[ -z "$rel_request" ]]; then
-  echo "archive-architecture-request: unsafe request path: $request_file" >&2
-  exit 2
-fi
-
-case "$rel_request" in
-  docs/architecture/requests/*.md)
-    ;;
-  *)
-    echo "archive-architecture-request: request must be under docs/architecture/requests/: $rel_request" >&2
-    exit 2
-    ;;
-esac
-
-case "$rel_request" in
-  docs/architecture/requests/archive/*)
-    echo "archive-architecture-request: request is already archived: $rel_request" >&2
-    exit 2
-    ;;
-esac
-
-if [[ ! -f "$rel_request" ]]; then
-  echo "archive-architecture-request: request not found: $rel_request" >&2
-  exit 1
-fi
-
-resolved_status="$(canonical_status "$status" || true)"
-if [[ -z "$resolved_status" ]]; then
-  echo "archive-architecture-request: unsupported status: $status" >&2
-  usage >&2
-  exit 2
-fi
-
-artifact_lines=()
-if [[ "${#artifacts[@]}" -gt 0 ]]; then
-  for artifact in "${artifacts[@]-}"; do
-    [[ -n "$artifact" ]] || continue
-    rel_artifact="$(repo_relative_path "$artifact" || true)"
-    if [[ -z "$rel_artifact" ]]; then
-      echo "archive-architecture-request: unsafe artifact path: $artifact" >&2
-      exit 2
-    fi
-    artifact_lines+=("- \`${rel_artifact}\`")
-  done
-fi
-
-archive_year="$(date '+%Y')"
-archive_dir="docs/architecture/requests/archive/${archive_year}"
-archive_file="${archive_dir}/$(basename "$rel_request")"
-if [[ -e "$archive_file" ]]; then
-  archive_file="${archive_dir}/$(date '+%Y%m%d-%H%M%S')-$(basename "$rel_request")"
-fi
-
-mkdir -p "$archive_dir"
-
-tmp_file="$(mktemp)"
-awk -v status="$resolved_status" '
-  BEGIN { replaced = 0 }
-  /^\> \*\*Status\*\*:/ {
-    print "> **Status**: " status
-    replaced = 1
-    next
-  }
-  { print }
-  END {
-    if (replaced == 0) {
-      print ""
-      print "> **Status**: " status
-    }
-  }
-' "$rel_request" > "$tmp_file"
-
-{
-  echo ""
-  echo "## Archive Resolution"
-  echo ""
-  echo "- Status: ${resolved_status}"
-  echo "- Archived: $(date '+%Y-%m-%dT%H:%M:%S%z')"
-  if [[ "${#artifact_lines[@]}" -gt 0 ]]; then
-    echo "- Artifacts:"
-    printf '%s\n' "${artifact_lines[@]}"
-  else
-    echo "- Artifacts: (none)"
-  fi
-  if [[ -n "$note" ]]; then
-    echo "- Note: ${note}"
-  fi
-} >> "$tmp_file"
-
-mv "$tmp_file" "$archive_file"
-rm -f "$rel_request"
-
-index_file="docs/architecture/index.md"
-if [[ -f "$index_file" ]]; then
-  index_tmp="$(mktemp)"
-  awk -v rel="$rel_request" -v short="${rel_request#docs/architecture/}" '
-    index($0, rel) == 0 && index($0, short) == 0 { print }
-  ' "$index_file" > "$index_tmp"
-  mv "$index_tmp" "$index_file"
-fi
-
-clear_contract_pending_request "$rel_request"
-
-echo "[ArchitectureArchive] Archived ${rel_request} -> ${archive_file}"
-echo "[ArchitectureArchive] status=${resolved_status}"

package/docs/architecture/history/README.md

@@ -1,7 +0,0 @@
-# Architecture History Archive
-
-Status: **Historical Evidence — Not Runtime Authority**
-
-The current Forge architecture contract is [`../CURRENT.md`](../CURRENT.md). Files in this directory preserve superseded design rationale or timestamped operational evidence and may intentionally contain old product names, machine-specific paths, historical phase/status labels, or assumptions that no longer hold.
-
-Do not update an archived page to make it look current. Fold any still-valid invariant into `CURRENT.md`, keep accepted rationale in an ADR when appropriate, and leave execution state in durable Plan/Work/evidence records.