forgeos 0.1.0-alpha.22 → 0.1.0-alpha.23

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.22 input=d8837238db9cf8868eceae3e3cc5a7d9bb46a0955c55f0143caa802597d5a3a5 content=0d493cf0e41b71cb652d5e0e1b0c1f83d2a1281b748321f0b00f0773ba93074e
+// @forge-generated generator=0.1.0-alpha.23 input=43fbd897d0f0a003e2f63e7048eb3281a5871034827653640e010161c0385d44 content=0d493cf0e41b71cb652d5e0e1b0c1f83d2a1281b748321f0b00f0773ba93074e
 # AGENTS.md
 
 <!-- forge-generated:start -->

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 0.1.0-alpha.23
+
+### Patch Changes
+
+- Tighten the post-alpha.22 release surface and package evidence.
+
+  - Add a dedicated Nuxt template smoke workflow that installs `nuxt-web`, runs Forge generation/checks, runs Nuxt typecheck, and probes `forge dev --once`.
+  - Include `nuxt-web` in the default field-test template matrix.
+  - Add explicit `scopeTarget` metadata and human-readable target output for `forge agent context --change`, `--proof`, and `--handoff`.
+  - Teach `forge explain` to fall back to the current generated agent contract when DeltaDB has no runtime history, while marking the result as contract-defined instead of executed.
+  - Downgrade read-only observation commands such as `forge status`, `forge changed`, `forge handoff`, `forge explain`, `forge timeline`, and CAIR queries to low-confidence context-gathering sessions in DeltaDB.
+  - Package `docs/cair-protocol.md` in the npm tarball and expand the public security/threat-model docs for DeltaDB, agent memory, CAIR, Studio bridge, brownfield import, and Nuxt surfaces.
+
 ## 0.1.0-alpha.22
 
 ### Patch Changes

package/docs/cair-protocol.md

@@ -0,0 +1,103 @@
+# CAIR Protocol
+
+CAIR is ForgeOS' compact agent interface for reading code structure, querying symbols, and planning safe edits without loading the whole repository into an agent context window.
+
+CAIR is intentionally CLI-first. It does not add a second mutating tool surface. Agents should use CAIR to inspect structure and create reviewable plans, then apply those plans through the ForgeOS CLI with hash checks and rollback journals.
+
+## Read Workflow
+
+Start with a compact snapshot:
+
+```bash
+forge cair snapshot
+forge cair query "Q STATUS"
+forge cair query "Q ST"
+```
+
+Use symbol, definition, reference, impact, and dependency API queries before opening large files:
+
+```bash
+forge cair query "Q S name=createTicket"
+forge cair query "Q D S#1"
+forge cair query "Q R S#1"
+forge cair query "Q I S#1"
+forge cair query "Q DEP.API package=zod symbol=object"
+```
+
+The goal is to make agent navigation evidence-backed: CAIR gives stable ids for modules, symbols, packages, APIs, and tests so an agent can select a small file set instead of scanning the whole project.
+
+## Action Safety
+
+Mutating CAIR actions should be planned first:
+
+```bash
+forge cair action --plan "A RN t=S#1 nn=openTicket"
+```
+
+The plan lives under `.forge/cair/plans/` and records the target files and expected hashes. Applying a plan checks those hashes before editing:
+
+```bash
+forge cair action "A APPLY plan=<P#|.forge/cair/plans/...json>"
+```
+
+Applied plans write rollback journals under `.forge/cair/journal/`:
+
+```bash
+forge cair action "A ROLLBACK journal=.forge/cair/journal/<journal>.json"
+```
+
+Use `--dry-run` when exploring an action shape without creating a plan:
+
+```bash
+forge cair action --dry-run "A CREATE.SYMBOL path=src/example.ts kind=function name=example export=true createFile=true"
+```
+
+Generated files stay protected by default. Use `--include-generated` only when the edit is intentionally about generated artifacts.
+
+## DeltaDB Evidence
+
+Successful CAIR CLI runs are recorded in DeltaDB as sanitized operational events:
+
+| CAIR command | Delta event |
+|--------------|-------------|
+| `forge cair snapshot` | `cair.snapshot.created` |
+| `forge cair query ...` | `cair.query.run` |
+| `forge cair action --plan ...` | `cair.plan.created` |
+| `forge cair action "A APPLY ..."` | `cair.plan.applied` |
+| `forge cair action --dry-run ...` | `cair.action.previewed` |
+
+The recorder stores compact verbs such as `Q ST` or `A APPLY`; it does not need to store full action bodies as first-class timeline data. Use:
+
+```bash
+forge timeline cair:protocol --json
+forge timeline --kind cair.plan.applied --json
+```
+
+This makes CAIR navigation and guarded edits visible beside file changes, proofs, and agent activity.
+
+## Compact Aliases
+
+| Long form | Compact |
+|-----------|---------|
+| `Q STATUS` | `Q ST` |
+| `Q SYMBOL` | `Q S` |
+| `Q DEF` | `Q D` |
+| `Q REFS` | `Q R` |
+| `Q IMPACT` | `Q I` |
+| `A RENAME.SYMBOL target=S#1 newName=x` | `A RN t=S#1 nn=x` |
+
+## Agent Posture
+
+Use this loop for code work:
+
+```bash
+forge cair snapshot
+forge cair query "Q ST"
+forge cair query "Q S name=<symbol>"
+forge cair query "Q I S#1"
+forge cair action --plan "A RN t=S#1 nn=<newName>"
+forge cair action "A APPLY plan=<P#|path>"
+forge check --json
+```
+
+Do not use CAIR as a bypass around ForgeOS rules. Commands remain transactional writes, queries and liveQueries remain read-only, side effects still belong in actions and workflows, and generated artifacts remain derived.

package/docs/changelog.md

@@ -6,6 +6,23 @@ The canonical source file in the repository is `CHANGELOG.md`.
 
 ## Unreleased
 
+## 0.1.0-alpha.23
+
+- Tightened the post-alpha.22 release surface and package evidence:
+  added a dedicated Nuxt template smoke workflow, included `nuxt-web` in the
+  default field-test template matrix, packaged `docs/cair-protocol.md`, and
+  expanded the security/threat-model docs for DeltaDB, agent memory, CAIR,
+  Studio bridge, brownfield import, and Nuxt surfaces.
+- `forge agent context` now returns explicit `scopeTarget` metadata and prints
+  the resolved context target for entry, change, proof, and handoff packs.
+- `forge explain` now falls back to the current generated agent contract when
+  DeltaDB has no runtime history, marking the entry as contract-defined rather
+  than executed.
+- DeltaDB work-session inference now treats read-only observation commands such
+  as `forge status`, `forge changed`, `forge handoff`, `forge explain`,
+  `forge timeline`, and CAIR queries as low-confidence context-gathering
+  sessions.
+
 ## 0.1.0-alpha.22
 
 - Added focused post-alpha.21 workflow improvements without expanding MCP tools:

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "forgeos",
-  "version": "0.1.0-alpha.22",
+  "version": "0.1.0-alpha.23",
   "description": "Agent-native application framework and compiler for building Forge apps without a mandatory dashboard.",
   "type": "module",
   "files": [
     "adapters/",
     "bin/",
+    "docs/cair-protocol.md",
     "docs/forge-protocol.md",
     "examples/go-billing/",
     "examples/java-billing/",

package/src/forge/_generated/releaseManifest.json

@@ -1 +1 @@
-{"defaultProvider":"local","diagnostics":[],"env":{"deployEnv":"FORGE_DEPLOY_ENV","deployId":"FORGE_DEPLOY_ID","publicReleaseId":"NEXT_PUBLIC_FORGE_RELEASE_ID","releaseId":"FORGE_RELEASE_ID"},"gitSha":"unknown","optionalProviders":["local","sentry-compatible","sentry","glitchtip","bugsink","otel","custom"],"packageName":"forgeos","packageVersion":"0.1.0-alpha.22","releaseId":"forgeos@0.1.0-alpha.22+unknown","schemaVersion":"0.1.0"}
+{"defaultProvider":"local","diagnostics":[],"env":{"deployEnv":"FORGE_DEPLOY_ENV","deployId":"FORGE_DEPLOY_ID","publicReleaseId":"NEXT_PUBLIC_FORGE_RELEASE_ID","releaseId":"FORGE_RELEASE_ID"},"gitSha":"unknown","optionalProviders":["local","sentry-compatible","sentry","glitchtip","bugsink","otel","custom"],"packageName":"forgeos","packageVersion":"0.1.0-alpha.23","releaseId":"forgeos@0.1.0-alpha.23+unknown","schemaVersion":"0.1.0"}

package/src/forge/_generated/releaseManifest.ts

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.22 input=d8837238db9cf8868eceae3e3cc5a7d9bb46a0955c55f0143caa802597d5a3a5 content=bb05ee3635ddeea2d84168f8bf728e07f82e896061e8494b17f56dea26000770
+// @forge-generated generator=0.1.0-alpha.23 input=43fbd897d0f0a003e2f63e7048eb3281a5871034827653640e010161c0385d44 content=8b537f90580f28c1630850bc7b7199e17d0bc62d05e9565fdf84da4bdbf9f6dc
 export const releaseManifest = {
   "defaultProvider": "local",
   "diagnostics": [],
@@ -19,7 +19,7 @@ export const releaseManifest = {
     "custom"
   ],
   "packageName": "forgeos",
-  "packageVersion": "0.1.0-alpha.22",
-  "releaseId": "forgeos@0.1.0-alpha.22+unknown",
+  "packageVersion": "0.1.0-alpha.23",
+  "releaseId": "forgeos@0.1.0-alpha.23+unknown",
   "schemaVersion": "0.1.0"
 } as const;

package/src/forge/agent-memory/bridge.ts

@@ -1021,6 +1021,7 @@ function formatAgentMemoryContextHuman(result: AgentMemoryContextPack): string {
   const lines = [
     `Forge Agent Context (${result.scope}${result.entry ? `: ${result.entry}` : ""})`,
     "",
+    `target: ${formatAgentContextTarget(result)}`,
     `events: ${summary.events}`,
     `sources: ${summary.sources.length > 0 ? summary.sources.join(", ") : "none"}`,
     `tools: ${summary.tools.length > 0 ? summary.tools.join(", ") : "none"}`,
@@ -1067,6 +1068,21 @@ function formatAgentMemoryContextHuman(result: AgentMemoryContextPack): string {
   return `${lines.join("\n")}\n`;
 }
 
+function formatAgentContextTarget(result: AgentMemoryContextPack): string {
+  const target = result.scopeTarget;
+  const parts: string[] = [target.kind];
+  if (target.value) {
+    parts.push(target.value);
+  }
+  if (target.semanticTarget && target.semanticTarget !== target.value) {
+    parts.push(`semantic=${target.semanticTarget}`);
+  }
+  if (target.currentSessionId) {
+    parts.push(`session=${target.currentSessionId}`);
+  }
+  return parts.join(" ");
+}
+
 function formatAgentMemoryEventsHuman(events: AgentMemoryEventRecord[]): string {
   const sources = uniqueStrings(events.map((event) => event.sourceName));
   const tools = uniqueStrings(events.flatMap((event) => {

package/src/forge/agent-memory/context-pack.ts

@@ -48,6 +48,7 @@ export async function buildAgentMemoryContext(input: {
     return {
       ok: true,
       scope,
+      scopeTarget: contextScopeTarget(input, scope, target, currentSession?.id),
       entry: input.entry,
       change: input.change,
       proof: input.proof,
@@ -117,6 +118,33 @@ function contextTarget(
   return undefined;
 }
 
+function contextScopeTarget(
+  input: { entry?: string; change?: string; proof?: string; handoff?: boolean },
+  scope: AgentMemoryContextPack["scope"],
+  semanticTarget: string | undefined,
+  currentSessionId: string | undefined,
+): AgentMemoryContextPack["scopeTarget"] {
+  if (scope === "entry") {
+    return { kind: "entry", value: input.entry, semanticTarget };
+  }
+  if (scope === "proof") {
+    return { kind: "proof", value: input.proof, semanticTarget };
+  }
+  if (scope === "change") {
+    const value = input.change ?? "current";
+    return {
+      kind: "change",
+      value,
+      ...(semanticTarget ? { semanticTarget } : {}),
+      ...(value === "current" && currentSessionId ? { currentSessionId } : {}),
+    };
+  }
+  if (scope === "handoff") {
+    return { kind: "handoff", value: "handoff", currentSessionId };
+  }
+  return { kind: "current-session", value: "current", currentSessionId };
+}
+
 function eventTarget(
   input: { entry?: string; change?: string; proof?: string },
   scope: AgentMemoryContextPack["scope"],

package/src/forge/agent-memory/types.ts

@@ -93,6 +93,12 @@ export interface AgentMemoryContextEvent {
 export interface AgentMemoryContextPack {
   ok: true;
   scope: "current" | "entry" | "change" | "proof" | "handoff";
+  scopeTarget: {
+    kind: "current-session" | "entry" | "change" | "proof" | "handoff";
+    value?: string;
+    semanticTarget?: string;
+    currentSessionId?: string;
+  };
   entry?: string;
   change?: string;
   proof?: string;

package/src/forge/delta/explain.ts

@@ -1,3 +1,5 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { DeltaStore } from "./store.ts";
 
 export interface DeltaExplainResult {
@@ -13,10 +15,11 @@ export async function runDeltaExplain(input: {
 }): Promise<DeltaExplainResult> {
   const store = await DeltaStore.open(input.workspaceRoot, { access: "read" });
   try {
+    const explanation = await store.explain(input.thing);
     return {
       ok: true,
       thing: input.thing,
-      explanation: await store.explain(input.thing),
+      explanation: enrichWithCurrentAgentContract(input.workspaceRoot, input.thing, explanation),
       exitCode: 0,
     };
   } finally {
@@ -68,6 +71,9 @@ export function formatDeltaExplainHuman(result: DeltaExplainResult): string {
     lines.push("Runtime:");
     lines.push(`  kind: ${String(runtime.entry_kind ?? "unknown")}`);
     lines.push(`  result: ${String(runtime.result ?? "unknown")}`);
+    if (runtime.source) {
+      lines.push(`  source: ${String(runtime.source)}`);
+    }
     if (runtime.diagnostic_code) {
       lines.push(`  diagnostic: ${String(runtime.diagnostic_code)}`);
     }
@@ -94,6 +100,22 @@ export function formatDeltaExplainHuman(result: DeltaExplainResult): string {
       }
     }
   }
+  const currentContract = explanation.currentContract as Record<string, unknown> | null | undefined;
+  if (currentContract) {
+    lines.push("");
+    lines.push("Current contract:");
+    lines.push(`  kind: ${String(currentContract.kind ?? "unknown")}`);
+    lines.push(`  name: ${String(currentContract.name ?? result.thing)}`);
+    if (currentContract.auth) {
+      lines.push(`  auth: ${String(currentContract.auth)}`);
+    }
+    if (currentContract.policy) {
+      lines.push(`  policy: ${String(currentContract.policy)}`);
+    }
+    if (currentContract.sourceFile) {
+      lines.push(`  file: ${String(currentContract.sourceFile)}`);
+    }
+  }
   lines.push("");
   lines.push("Introduced in:");
   if (workSessions.length === 0) {
@@ -124,3 +146,93 @@ export function formatDeltaExplainHuman(result: DeltaExplainResult): string {
 export function formatDeltaExplainJson(result: DeltaExplainResult): string {
   return `${JSON.stringify(result, null, 2)}\n`;
 }
+
+function enrichWithCurrentAgentContract(
+  workspaceRoot: string,
+  thing: string,
+  explanation: Record<string, unknown>,
+): Record<string, unknown> {
+  const currentContract = currentContractForThing(workspaceRoot, thing);
+  if (!currentContract) {
+    return explanation;
+  }
+  const runtime = explanation.runtime && typeof explanation.runtime === "object"
+    ? explanation.runtime as Record<string, unknown>
+    : null;
+  return {
+    ...explanation,
+    type: explanation.type === "unknown" ? "runtime-entry" : explanation.type,
+    runtime: runtime ?? {
+      entry_name: currentContract.name,
+      entry_kind: currentContract.kind,
+      result: "defined",
+      source: "agentContract",
+      ...(currentContract.policy ? { policy: currentContract.policy } : {}),
+      ...(typeof currentContract.tenantScoped === "boolean" ? { tenant_scoped: currentContract.tenantScoped } : {}),
+      ...(typeof currentContract.needsApproval === "boolean" ? { needs_approval: currentContract.needsApproval } : {}),
+    },
+    currentContract,
+  };
+}
+
+function currentContractForThing(workspaceRoot: string, thing: string): Record<string, unknown> | undefined {
+  const contractPath = join(workspaceRoot, "src", "forge", "_generated", "agentContract.json");
+  if (!existsSync(contractPath)) {
+    return undefined;
+  }
+  try {
+    const contract = JSON.parse(readFileSync(contractPath, "utf8")) as Record<string, unknown>;
+    const collections: Array<[keyof typeof runtimeKinds, string]> = [
+      ["commands", "command"],
+      ["queries", "query"],
+      ["liveQueries", "liveQuery"],
+      ["actions", "action"],
+      ["workflows", "workflow"],
+    ];
+    for (const [collection, kind] of collections) {
+      const entries = Array.isArray(contract[collection]) ? contract[collection] as Record<string, unknown>[] : [];
+      for (const entry of entries) {
+        const name = runtimeEntryName(entry);
+        if (!name) {
+          continue;
+        }
+        if (name === thing || `${kind}:${name}` === thing || entry.id === thing || entry.exportName === thing) {
+          return {
+            source: "src/forge/_generated/agentContract.json",
+            kind,
+            name,
+            ...(stringValue(entry.auth) ? { auth: stringValue(entry.auth) } : {}),
+            ...(stringValue(entry.policy) ? { policy: stringValue(entry.policy) } : {}),
+            ...(typeof entry.tenantScoped === "boolean" ? { tenantScoped: entry.tenantScoped } : {}),
+            ...(typeof entry.needsApproval === "boolean" ? { needsApproval: entry.needsApproval } : {}),
+            ...(stringValue(entry.risk) ? { risk: stringValue(entry.risk) } : {}),
+            ...(stringValue(entry.file) ? { sourceFile: stringValue(entry.file) } : {}),
+            ...(stringValue(entry.path) ? { sourceFile: stringValue(entry.path) } : {}),
+          };
+        }
+      }
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+const runtimeKinds = {
+  commands: "command",
+  queries: "query",
+  liveQueries: "liveQuery",
+  actions: "action",
+  workflows: "workflow",
+} as const;
+
+function runtimeEntryName(entry: Record<string, unknown>): string | undefined {
+  return stringValue(entry.name)
+    ?? stringValue(entry.exportName)
+    ?? stringValue(entry.id)
+    ?? stringValue(entry.entryName);
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/src/forge/delta/store.ts

@@ -2809,6 +2809,12 @@ function scoreWorkSessionCandidate(
 ): { score: number; signals: DeltaWorkSessionSignal[] } {
   const signals: DeltaWorkSessionSignal[] = [];
   const metadata = candidate.metadata;
+  if (isObservationOnlyContext(context) && !isObservationOnlyWorkSession(metadata)) {
+    return {
+      score: 0.15,
+      signals: [{ signal: "observation-only", weight: 0.15, value: context.commands[0] }],
+    };
+  }
   addSignalIfOverlap(signals, "sameTraceId", 0.4, context.traces, metadata.traces);
   addSignalIfOverlap(signals, "sameManifestService", 0.35, context.services, metadata.services);
   addSignalIfOverlap(signals, "sameRuntimeEntry", 0.3, context.entries, metadata.entries);
@@ -2951,6 +2957,9 @@ function normalizeWorkSessionMetadata(value: Record<string, unknown>): DeltaWork
 }
 
 function inferWorkSessionTitle(context: DeltaOperationContext, metadata: DeltaWorkSessionMetadata): string {
+  if (isObservationOnlyWorkSession(metadata)) {
+    return "Observe project context";
+  }
   if (context.kind === "manifest.imported" && metadata.services[0]) {
     return `Import ${metadata.services[0]} external service`;
   }
@@ -2979,6 +2988,9 @@ function inferWorkSessionTitle(context: DeltaOperationContext, metadata: DeltaWo
 }
 
 function inferIntent(context: DeltaOperationContext, metadata: DeltaWorkSessionMetadata): string {
+  if (isObservationOnlyWorkSession(metadata)) {
+    return "context-gathering";
+  }
   if (context.kind === "manifest.imported" || metadata.fileClusters.includes("manifest.change")) {
     return "external-runtime-import";
   }
@@ -2999,6 +3011,9 @@ function inferIntent(context: DeltaOperationContext, metadata: DeltaWorkSessionM
 
 function summarizeWorkSession(metadata: DeltaWorkSessionMetadata): string {
   const parts: string[] = [];
+  if (isObservationOnlyWorkSession(metadata)) {
+    return `Observed project context with ${metadata.commands.slice(0, 3).join(", ")}.`;
+  }
   if (metadata.services[0]) {
     parts.push(`worked on ${metadata.services[0]}`);
   }
@@ -3018,6 +3033,9 @@ function summarizeWorkSession(metadata: DeltaWorkSessionMetadata): string {
 }
 
 function initialWorkSessionConfidence(context: DeltaOperationContext): number {
+  if (isObservationOnlyContext(context)) {
+    return 0.36;
+  }
   if (context.kind === "manifest.imported") {
     return 0.78;
   }
@@ -3043,6 +3061,65 @@ function isDiagnosticRepairChain(context: DeltaOperationContext, metadata: Delta
   );
 }
 
+const OBSERVATION_COMMAND_PREFIXES = [
+  "agent context",
+  "agent print-context",
+  "agent timeline",
+  "cair query",
+  "cair snapshot",
+  "changed",
+  "delta status",
+  "doctor",
+  "explain",
+  "handoff",
+  "inspect",
+  "live status",
+  "status",
+  "timeline",
+];
+
+function isObservationOnlyContext(context: DeltaOperationContext): boolean {
+  return (
+    context.commands.length > 0 &&
+    context.files.length === 0 &&
+    context.entries.length === 0 &&
+    context.diagnostics.length === 0 &&
+    context.proofs.length === 0 &&
+    context.services.length === 0 &&
+    context.traces.length === 0 &&
+    context.commands.every(isObservationCommand)
+  );
+}
+
+function isObservationOnlyWorkSession(metadata: DeltaWorkSessionMetadata): boolean {
+  return (
+    metadata.commands.length > 0 &&
+    metadata.files.length === 0 &&
+    metadata.entries.length === 0 &&
+    metadata.diagnostics.length === 0 &&
+    metadata.proofs.length === 0 &&
+    metadata.services.length === 0 &&
+    metadata.traces.length === 0 &&
+    metadata.commands.every(isObservationCommand)
+  );
+}
+
+function isObservationCommand(command: string): boolean {
+  const normalized = normalizeForgeCommand(command);
+  return OBSERVATION_COMMAND_PREFIXES.some((prefix) => normalized === prefix || normalized.startsWith(`${prefix} `));
+}
+
+function normalizeForgeCommand(command: string): string {
+  return command
+    .trim()
+    .replace(/^node\s+(?:\.\/)?bin\/forge\.mjs(?:\s+|$)/u, "")
+    .replace(/^bun\s+run\s+forge(?:\s+|$)/u, "")
+    .replace(/^npm\s+run\s+forge\s+--(?:\s+|$)/u, "")
+    .replace(/^forge(?:\s+|$)/u, "")
+    .replace(/\s+/gu, " ")
+    .trim();
+}
+
 function hasAnyOverlap(...groups: string[][]): boolean {
   for (let index = 0; index < groups.length; index += 2) {
     if (intersects(groups[index] ?? [], groups[index + 1] ?? [])) {

package/src/forge/version.ts

@@ -1,3 +1,3 @@
-export const FORGEOS_VERSION = "0.1.0-alpha.22";
+export const FORGEOS_VERSION = "0.1.0-alpha.23";
 export const GENERATOR_VERSION = FORGEOS_VERSION;
 export const CLI_VERSION = FORGEOS_VERSION;