forgeos 0.1.0-alpha.7 → 0.1.0-alpha.71

package/.agents/skills/forge-agent-fabric/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: forge-agent-fabric
+description: Conduct or resume Forge Agent Fabric tasks and prepare repository manifests, analysis maps and source-bound context in existing projects, including Vue, Java and Docker.
+---
+
+# Forge Agent Fabric
+
+Keep the user's conversation in Codex. Prepare protocol requests yourself; the user should
+not need to write JSON or operate a second interface. Respect the user's task scope and
+existing authorization. This skill does not authorize publication, deployments or external
+messages. Use subagents for implementation/review when authorized by the user or project.
+
+## Locate and connect
+
+Resolve the current project's Git root and read its AGENTS.md. Execute with that root
+as cwd, even when the runtime is installed elsewhere. Windows and WSL copies are distinct
+projects. This workflow does not require a Forge application or project dependency.
+
+Use the absolute path to this skill's `scripts/fabric.mjs` helper:
+`node <skill-directory>/scripts/fabric.mjs --project <target-git-root> <operation> --json`.
+It reads installer-generated runtime.json or FORGE_FABRIC_CLI and falls back to an installed
+Forge runtime on PATH. Never switch to the runtime's checkout to conduct work.
+
+Run `doctor --json` and `ensure-owner --json` through that helper. Register projects with
+`project-register --project-id <stable-id> --json`; inspect registrations with `project-list --json`.
+Registration is needed for multiproject MCP routing, not for ordinary cwd-bound CLI work.
+Optional project preparation, verification and limits live in `.forge/fabric.json`;
+inspect doctor and respect the current project's profile rather than inventing config fields.
+
+Forward `capabilities --json` through the helper to distinguish accompanied tasks,
+managed SDK runs and the legacy Ollama pilot. When the user asks Fabric to execute a
+workflow or run Codex workers, select managed execution below. Choose accompanied mode
+when the task is to record work performed by the native session. Both modes need one
+owner; `ensure-owner` reuses or starts it without dispatching workers.
+Do not open the legacy PGlite database independently or kill an unrelated owner.
+
+Native MCP tools are `fabric_attached_*`, `fabric_workflow_*` and `fabric_run_*`. If unavailable, the CLI
+offers the same operations. State which transport you actually demonstrated.
+Do not register MCP or change global configuration as a side effect of using this skill.
+
+## Analyze an existing repository
+
+When asked to prepare a project for Forge maps, read
+[repository analysis](references/repository-analysis.md). Use the shared runtime through
+`scripts/repository.mjs --project <target-directory> manifest|repository|cair <operation>`.
+This helper does not require Git; managed Fabric execution still requires Git with HEAD.
+Discovery returns a proposal. Inspect it against project instructions and code, then prepare
+`forge.manifest.json` only when edits are authorized. Preserve an existing service manifest.
+Validate the repository manifest before analyzing. Maps describe static evidence and
+coverage gaps, not runtime availability or executed test coverage. Checks are suggestions;
+never execute them just because the manifesto contains them. Do not start containers,
+build Java, execute configuration scripts or install hooks/MCP during static analysis.
+Use repository queries to give each task compact context with snapshotId. Refresh analysis
+when sources change, and never reuse source snippets or handles from a stale snapshot.
+For manifests stored outside the project, keep passing the same explicit `--manifest`
+to analysis and CAIR queries; the helper binds their root from `--project`.
+Managed SDK workers receive analysis from their own prepared clone when it contains a
+valid repository manifest. This context supplements acceptance checks and does not
+change publication or review requirements.
+
+Read [managed request fields and examples](references/managed-workflows.md) before
+preparing run-start. The references travel with this skill and require no Forge checkout.
+For MCP, inspect tool schemas and select the registered target project explicitly through
+projectId when supported. A fixed-root MCP server is usable only when its root matches
+the target. Never assume a global MCP configuration follows the chat cwd.
+
+## Accompanied work
+
+1. Create an `attached-propose` with explicit acceptance criteria, relevant file scope and
+   checks. Mutations use a complete `--file` JSON request; reads use `--task-id`.
+2. Attach the actual session/agent identity, register an implementation assignment and
+   start its attempt. Use actual IDs from the host, not invented claims of verified identity.
+3. For a composed task, record `workflow-plan` and use `workflow-next` packets. Claim a
+   step before executing it, then report output digest and evidence. Before checking or
+   reviewing source, capture the current snapshot digest from `attached-status`. Successful
+   `workflow-result` and `workflow-reconcile` requests must include that actual observed
+   digest in the top-level `observedSnapshotDigest` field. Do not fetch a newer digest merely
+   to stamp an older result; if source changed, reconcile obsolete work as failed and
+   replan or execute a fresh attempt. The scheduler records
+   work; it does not invoke the host's subagent tools for you.
+4. Complete implementation and prepare a review with a distinct reviewer attempt.
+   Give that Codex subagent requirements, code and the returned exact snapshot/token.
+   Submit its report only for that version. Correct findings and obtain a new review
+   when files change. Do not mark findings resolved without corrective evidence.
+5. Run the checks relevant to the change and record their outcomes for the current
+   snapshot. Record criterion coverage with concrete artifacts or observed checks.
+6. Read `attached-status`. Address the structured unmet reasons before presenting the
+   task as ready. Agent-reported records retain that provenance; they are not authenticated
+   service executions, human acceptance or proof of production deployment.
+
+Reuse a requestId only for the exact same request, including expectedVersion. On a version
+conflict read current state and reconcile; use a new requestId for a new operation. Mutation
+responses are compact acknowledgements; status/context reads return current full state.
+
+## Resume and adapt
+
+Start with `attached-context` for the known taskId. Do not restart completed work from the
+conversation summary alone. After a host crash use `workflow-recover` for known interrupted
+attempts and reconcile their observed outcomes before dispatching them again. A missing
+result is uncertainty, not success or permission to repeat an effect.
+
+Use `workflow-replan` with the expected revision, reason and evidenceRefs. Preserve
+required obligations. Source changes make recorded results stale; the service blocks
+their reuse and replan invalidates affected steps and their dependents. The current
+release binds results conservatively to the task's whole file scope; choose a relevant
+scope and do not promise fine-grained invalidation by individual inputRefs.
+
+Keep hooks observational. Missing hook events do not prevent explicit session/tentative
+registration, but do prevent claiming that native hook integration has been demonstrated.
+The accompanied mode recovers work when Codex returns. Managed SDK runs now have a
+separate executor, but still require a live owner; neither mode installs automatic wakeup
+or guarantees execution after the App closes.
+
+## Managed execution
+
+Choose managed execution when the authorized task calls for owner-dispatched SDK or
+command workers. Keep the native chat as the interface and prepare requests yourself.
+Starting Codex workers can consume configured credits; local publication can change
+files. Use the user's existing scope and authorization, including any cost constraints.
+Do not treat the legacy proposal-only MCP contract as a limit on fabric_run_start.
+
+1. Read capabilities and the managed request example in the bundled reference. Prepare
+   run-start with requestId, goal, scope, workflow and one executor per node. Codex roles
+   are implementer/reviewer/investigator/decision; commands use explicit argv. Choose
+   relevant limits, deadlines and scope. inputDigest identifies the declared node contract;
+   the owner separately captures actual source inputs. Clones do not copy root node_modules;
+   automatic environment preparation installs locked dependencies or copies verified cache
+   into the clone, with scripts ignored by default. Optional environment accepts mode
+   auto/none, ignoreScripts, HTTPS registry without credentials/query/fragment, and timeoutMs
+   100..1800000. Use none for dependency-free steps. Do not assume ignored scripts executed.
+2. Start via `fabric run-start --file run.json --json` or fabric_run_start with
+   `{request: BODY}`. Read `run-status --run-id ID`; use run-wait with
+   `{runId,cursor,waitMs}` for bounded events, up to 30000 ms. MCP status uses `{runId}`.
+   Start and mutations return compact acks; status provides full public state and artifacts.
+3. For publication, use an implementer activity, a required distinct Codex reviewer
+   downstream of every writer, and a required command verification downstream of every
+   writer. Reviewer approval, command success and workflow completion are required.
+   publish false keeps isolated artifacts; publication applies local scoped files and
+   does not authorize commit, push or deployment. Do not claim that a model's report is
+   executor evidence: state is executor_observed, reports remain agent_reported, and
+   outputContract.requiredEvidenceKinds accepts only `executor-observed`.
+4. Steer queues instruction and pauses new dispatch; it does not message the active worker.
+   Pause allows active workers to finish. All controls use runId/requestId/expectedVersion.
+   Resume optionally adds expectedRevision/nodes/executors/reason/evidenceRefs for replan.
+   Read status after version conflicts and issue a new requestId for a changed body.
+5. After cancellation or owner restart, inspect the saved thread, workspace and effects.
+   Unknown attempts require run-reconcile with attemptId, resolution failed and reason;
+   never manufacture success or retry uncertain effects silently. A new isolated attempt
+   may use the saved SDK thread. Publication confirmation uses publication confirm only
+   when the owner can observe matching expected files. Resolve uncertainty before resume.
+   Publication retry is allowed only after observing the complete original baseline; it
+   clears the intent and pauses. Resume explicitly; preserve partial divergent writes.
+
+Distinguish implementation, command-fixture tests and actual SDK execution in the delivery
+report. Do not extend a past pilot's acceptance to a new environment or task without
+observed evidence. SDK workers are separate runs, not new chats in the sidebar. Keep the owner session
+visible in task context; do not promise App-closed execution or create a scheduler implicitly.
+
+## Program workflows v2
+
+For new finite typed workflows use the installed `docs/agent-fabric-programs.md` and
+`examples/agent-fabric-v2/`. The authoring module is `forgeos/agent-fabric/workflows`.
+`program-validate`, `program-start`, `program-status`, `program-wait` and subsequent
+`program-*` mutations use the existing owner; MCP exposes `fabric_program_*`.
+Validate source against the owner registry before dispatch. Every mutation needs a unique
+requestId; subsequent mutations pin expectedVersion. Never treat data-only completed as
+acceptance-ready or infer authority to apply from a worker's report. Preserve uncertain
+outcomes and reconcile observed effects before resume. Fenced replan uses a global barrier;
+Same-run completed output reuse happens before worker preparation; cross-run SDK caching is absent.
+Use operatorVersion 2, explicit Blocks/results, after/sequence and waiting semantics; no legacy migration is required.
+For scoped UI acceptance require item/final owner checks, current evidence and full final obligations.
+Use program-history/program-explain/program-artifact-get/program-diff for inspection.
+When avoiding LLM spending set FORGE_FABRIC_TEST_MODE=1 and use deterministic adapters/SDK stubs.
+Publication still requires the user's task authorization.
+
+## Workflow correction contract R2.2
+
+Program subworkflows inherit ancestor activity quotas and cancellation; input is explicit. Owner visualCases binds route/viewport/state/dimensions to each population member; do not promise exhaustive UI coverage beyond that catalog. Capture obligations apply by assessment scope. New program runs use program-runs-v3/format 3 with immutable linked journal; no migration of old runs. program-explain includes graph nodes, observed instances and Mermaid. Typed refs/output(operation) improve authoring, while owner schemas remain authoritative. See docs/agent-fabric-programs.md and WORKFLOW_PROGRAM_V2_CORRECTIONS.md in the Forge source. For deterministic validation keep FORGE_FABRIC_TEST_MODE=1; do not launch real providers without explicit user authority.

package/.agents/skills/forge-agent-fabric/references/managed-workflows.md

@@ -0,0 +1,95 @@
+# Managed Codex workflows
+
+Commands below are Fabric operation arguments forwarded through `scripts/fabric.mjs`.
+Use the current target Git root, not the directory containing the runtime. The owner
+captures source from that root and creates isolated Git clones. No root node_modules
+directory is shared with clones. A runtime installation is reusable across repositories.
+
+## Request shape
+
+Prepare `run-start --file <absolute-request.json> --json`; the request file must be inside
+the target Git root. Mutations use a complete JSON
+body; reads use `run-status --run-id ID --json`. The following command-only example
+needs an existing tracked `source.txt` and a working absolute Node executable. Generate
+a fresh requestId for each independent run. Replace example paths with observed paths.
+
+```json
+{
+  "requestId": "command-smoke-1",
+  "goal": "Observe a command in an isolated clone",
+  "scope": ["source.txt"],
+  "publish": false,
+  "environment": {"mode": "none"},
+  "workflow": {"workflowId": "command-smoke", "nodes": [{
+    "nodeId": "verify", "kind": "verification", "dependsOn": [],
+    "inputDigest": "sha256:2689367b205c16ce32ed4200942b8b8b1e262dfc70d9bc9fbc77c49699a4f1df",
+    "required": true,
+    "outputContract": {"requiredEvidenceKinds": ["executor-observed"]}
+  }]},
+  "executors": [{"nodeId": "verify", "type": "command",
+    "argv": ["/absolute/path/to/node", "-e", "process.stdout.write('ok')"],
+    "timeoutMs": 10000}]
+}
+```
+
+inputDigest describes the node contract, not the observed source. Calculate SHA-256
+for each actual declared contract. The example digest is SHA-256 of `ok` for this smoke.
+The owner separately captures source inputs. Evidence kind `executor-observed` means
+execution was observed; a model report's content remains `agent_reported`.
+
+For code use `implement -> review -> verify` with one executor per node:
+
+- implement: `kind: activity`, executor `{nodeId,type:"codex",role:"implementer",prompt,writeScope:[...]}`.
+- review: required activity, Codex `role:"reviewer"`, depending on every writer, prompt requesting independent review and explicit approval/findings.
+- verify: required verification, `type:"command"`, explicit `argv`, depending on every writer; use actual project tests/build checks.
+
+Scopes and writeScope are repository-relative. Ensure writeScope stays inside the run
+scope. Set timeoutMs and limits appropriate to the task. Use capabilities/doctor to check
+current constraints. Maximum supported concurrency is four; prefer a small useful fanout.
+Do not prescribe a test command without reading the project's scripts or AGENTS.md.
+
+Optional top-level run environment: mode `auto` (default) or `none`, ignoreScripts (default
+true), HTTPS registry without credentials/query/fragment, timeoutMs 100..1800000.
+Auto prepares locked dependencies or copies verified cache content into the clone.
+Ignored scripts have not executed; enable necessary preparation only within authorization.
+An optional `.forge/fabric.json` profile supplies maxConcurrency and environment defaults
+for run-start; explicit request fields win. verificationCommands are suggested argv arrays
+for the agent to select, never commands executed by doctor. Supported profile shape:
+`{schemaVersion:1,maxConcurrency:2,environment:{mode:"auto",ignoreScripts:true},verificationCommands:[["node","--test"]]}`.
+
+Publication is local file application, not npm publication. `publish:false` keeps clones
+and artifacts. `publish:true` (the default) requires approval from a distinct required
+Codex reviewer and successful required command verification downstream of all writers.
+Do not claim a model report proves a successful command, production deployment or human
+acceptance. Run with explicit publication intent matching the user's request.
+
+## Controls and recovery
+
+| Operation | Body |
+| --- | --- |
+| run-wait | `{runId,cursor?,waitMs}`; waitMs 0..30000 |
+| run-pause/run-resume/run-cancel | `{runId,requestId,expectedVersion}` |
+| run-steer | CAS fields plus `instruction`; pauses new dispatch |
+| run-reconcile | CAS fields plus `{attemptId,resolution:"failed",reason}` for uncertain attempts |
+
+Mutation acknowledgements are compact. Read run-status for full public state, source
+versions, attempts, artifacts and unmet requirements. Reuse requestId only for an exact
+body replay. After a version conflict read status and create a new requestId for a changed
+operation. Pause allows active workers to finish; steer does not inject messages into the
+active worker. Cancel requests interruption without rolling back external effects.
+
+Resume can replan with expectedRevision, nodes, executors, reason and evidenceRefs.
+Preserve required obligations, evidence requirements and limits. Source changes invalidate
+applicable results. Failed or uncertain attempts must not be represented as success.
+
+After an owner restart or interruption inspect saved workspace, SDK thread ID and effects.
+Unknown results require reconciliation before retry. New isolated attempts may reuse a
+saved SDK thread. Publication confirmation `{publication:"confirm"}` requires the owner
+to observe matching expected files. Retry `{publication:"retry"}` requires the complete
+original baseline, pauses the run, and needs explicit resume. Preserve divergent partial
+writes instead of overwriting them.
+
+MCP run mutations receive `{request: BODY}` plus projectId when routing is enabled;
+status receives `{runId}` plus projectId. Always inspect the available tool schema.
+CLI and MCP must target the same registered root. A configured MCP server being present
+does not prove its tool catalog is loaded or its owner is alive.

package/.agents/skills/forge-agent-fabric/references/repository-analysis.md

@@ -0,0 +1,102 @@
+# Repository manifests and maps
+
+Use Forge as analysis tooling in an existing project without adding the Forge application
+runtime. Shared installation is enough. Vue/Nuxt, Java/Spring, TypeScript/JavaScript and
+Docker/Compose adapters report their coverage; partial static knowledge remains partial.
+
+Run these with the absolute installed skill helper and an explicit target directory:
+
+```text
+node <skill>/scripts/repository.mjs --project <project> manifest discover --json
+node <skill>/scripts/repository.mjs --project <project> manifest validate forge.manifest.json --json
+node <skill>/scripts/repository.mjs --project <project> repository analyze --write --json
+node <skill>/scripts/repository.mjs --project <project> repository context --query routes --json
+node <skill>/scripts/repository.mjs --project <project> repository context --query coverage --json
+node <skill>/scripts/repository.mjs --project <project> repository quality --cases <absolute-reviewed-cases.json> --json
+node <skill>/scripts/repository.mjs --project <project> cair query "Q S name=<symbol>" --snapshot-id <snapshot-id> --json
+```
+
+Discovery is read-only by default: it returns a draft for the agent to review and save within the
+user's authorized scope. Confirm component roots and adapters against actual files,
+retain uncertainty, and do not overwrite a service 1.0 manifest. Repository manifests
+use `forgeProtocol: "2.0"` and `kind: "repository"`. Keep paths relative to the project.
+The manifest configures analysis; it is not a hand-maintained symbol inventory.
+
+Validate before analyzing. Analysis with `--write` saves explicit output to `.forge/repository/`
+unless a host-local cache destination is requested. Without `--write`, analysis returns
+an ephemeral snapshot and creates no cache. It does not alter
+generated application code, `.gitignore`, application dependencies or global integrations.
+Use `--help` for supported flags and current query grammar. Query results identify the
+snapshot and source evidence; a stale-source diagnostic requires fresh analysis.
+
+The helper binds `--project` explicitly for repository operations and CAIR. For a manifest
+kept outside the project, add `--manifest <absolute-file>` consistently to analysis and
+queries. Its location does not redefine the project root. Do not substitute another
+project's snapshot or leave out the external manifest when querying that snapshot.
+
+Do not read actual `.env` or secret files to resolve infrastructure. Unknown interpolation,
+dynamic URLs, Java reflection, Vue dynamic components and unresolved imports are gaps,
+not permission to infer certainty. A Compose dependency is declared topology, not observed
+traffic. A statically associated test is not proof that it ran or covered the component.
+
+For Fabric, keep analysis configuration in the project before run-start. Each SDK attempt
+analyzes its prepared clone after upstream changes and environment preparation. Clone
+snapshot IDs cannot be substituted with the original checkout's snapshot. Maps do not
+remove required reviews/checks, execute suggested checks, or authorize publication.
+Worker packets prioritize task matches and scoped symbols, include both endpoints of
+every returned edge, and declare truncation when their context budget omits facts.
+Their phase is `prepared-input`, not an assertion about later worker edits. Invalid
+configuration yields unavailable maps without echoing manifest source values in run status.
+
+Use optional `component.analysis.aliases` and `component.analysis.nuxt` to declare
+contained local resolution paths that executable config cannot establish statically.
+These paths are relative to the component root. `httpClients` may map a client ID
+(including `$api`) and file scope to a literal base path/API component. Record the
+scenario behind a mapping: a deployment default is declared evidence and never
+observed routing. Keep unknown URLs and ambiguous endpoints unresolved.
+
+Task context prioritizes exact/scoped targets, relevant consumers and case-level
+test evidence. A test-file import does not associate all sibling cases with that
+function. Included neighbors outside write scope are read-only. Suggested checks
+retain argv arrays, working directories, selection reasons, cost/category and
+unknown/missing/satisfied symbolic requirements; no check runs during map preparation.
+`ready` means the packet was prepared. Static quality is always partial and does not
+claim runtime observation.
+
+For quality review, prepare a JSON task array with `id`, `query`, `expectedFiles`
+and optionally `scope`, `expectedTests`, `forbiddenFiles` and `forbiddenTests`.
+Run `repository quality` against a current explicitly saved snapshot. It returns
+missing/forbidden associations, context size, truncation and recall/precision against
+the supplied expected file set. Require a reviewed set; do not remove failing
+expectations merely to obtain a pass. This read-only benchmark runs no models or
+application tests and cannot establish productivity improvement or executed coverage.
+
+Large v2 caches use hash-checked partitions and on-demand hydration, with complete
+integrity validation and a two-partition decoded cache. V1 compatibility is eager;
+wide queries may retain extra results. Analysis with --write maintains orphan caches
+after conservative retention; cache-gc defaults to preview and --write applies it.
+Never reclaim a foreign lock or treat serialized resident bytes as heap usage.
+Use benchmark-plan with reviewed cases and explicit model settings to prepare a paired
+experiment; benchmark-report evaluates supplied evidence without running workers/checks.
+Missing evidence is unknown, and model execution still requires authorized cost/scope.
+Matching parse facts can be reused read-only in a managed clone, but its graph,
+root, manifest/scenario connections and freshness are rebuilt. No per-project
+dependency, native hook or MCP installation is required for this flow. These features
+require a runtime containing the quality implementation; copying a newer skill onto
+an older runtime does not upgrade that runtime.
+
+Runtime observations are optional and explicit. Add reviewed `runtime.observations`
+with commands, contained cwd and generated artifact paths, then use `repository
+runtime-plan --environment-id local --json` before `runtime-observe --environment-id
+local --execute --write --json`. The latter executes trusted argv in an independent
+temporary source copy; it is not an OS/network/container security sandbox. Dependencies
+must be prepared by declared commands. Do not copy credentials or assume external
+services are authorized merely because a manifest mentions them. No model runs here.
+`runtime-context` reads sanitized bounded evidence, validates input bindings and expiry,
+and never executes. Nuxt registrations, Spring exports, Docker inspection and HTTP
+traces retain their format-specific limitations; they are not exhaustive runtime coverage.
+Exporters must close external resources they start. No hook or MCP installation is needed
+per project. Fabric can add matching saved observations to a prepared worker packet
+without running an exporter; composed input changes invalidate this reuse. Keep original
+protected repositories read-only and use the dedicated pilot copies for validation.
+See `docs/repository-runtime-observation.md` for the contract and execution examples.

package/.agents/skills/forge-agent-fabric/scripts/fabric.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync, existsSync } from 'node:fs';
+import { dirname, resolve, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+// Runtime identity is independent of the target project: no cwd from runtime config.
+const skillRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+try {
+  const args = process.argv.slice(2);
+  let project = process.cwd();
+  const index = args.indexOf('--project');
+  if (index >= 0) {
+    if (!args[index + 1]) throw new Error('--project requires a target directory');
+    project = args[index + 1];
+    args.splice(index, 2);
+  }
+  const git = spawnSync('git', ['-C', project, 'rev-parse', '--show-toplevel'], { encoding: 'utf8', windowsHide: true });
+  if (git.status !== 0) throw new Error(`Target must be a Git repository: ${project}`);
+  const cwd = realpathSync(git.stdout.trim());
+  let runtime = {};
+  const config = resolve(skillRoot, 'runtime.json');
+  if (existsSync(config)) runtime = JSON.parse(readFileSync(config, 'utf8'));
+  let cliPath = process.env.FORGE_FABRIC_CLI || runtime.cliPath;
+  if (!cliPath) {
+    const lookup = spawnSync(process.platform === 'win32' ? 'where.exe' : 'which', ['forge'], { encoding: 'utf8', windowsHide: true });
+    const candidates = lookup.stdout?.trim().split(/\r?\n/).filter(Boolean) || [];
+    for (const candidate of candidates) {
+      const bin = realpathSync(candidate);
+      const guesses = [bin, resolve(dirname(bin), 'node_modules/forgeos/bin/forge.mjs')];
+      cliPath = guesses.find((path) => path.endsWith('.mjs') && existsSync(path));
+      if (cliPath) break;
+    }
+  }
+  if (!cliPath || !isAbsolute(cliPath) || !existsSync(cliPath)) {
+    throw new Error('Forge runtime not found. Install this skill with --runtime <absolute forge.mjs>, or set FORGE_FABRIC_CLI to that absolute file.');
+  }
+  const result = spawnSync(runtime.nodeExecutable || process.execPath, [realpathSync(cliPath), 'fabric', ...args], {
+    cwd, stdio: 'inherit', windowsHide: true,
+  });
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}

package/.agents/skills/forge-agent-fabric/scripts/repository.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync, existsSync, statSync } from 'node:fs';
+import { dirname, resolve, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+// Analysis can target a directory without Git. Runtime configuration never sets cwd.
+const skillRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+try {
+  const args = process.argv.slice(2);
+  let project = process.cwd();
+  if (args.filter(arg => arg === '--project').length > 1) throw new Error('--project may be supplied only once');
+  const index = args.indexOf('--project');
+  if (index >= 0) {
+    if (!args[index + 1] || args[index + 1].startsWith('--')) throw new Error('--project requires a target directory');
+    project = args[index + 1];
+    args.splice(index, 2);
+  }
+  const cwd = realpathSync(project);
+  if (!statSync(cwd).isDirectory()) throw new Error('Analysis project must be a directory');
+  const surface = args.shift();
+  if (!['manifest', 'repository', 'cair'].includes(surface)) throw new Error('Choose manifest, repository or cair before the operation');
+  if (index >= 0 && (surface === 'repository' || surface === 'cair' || (surface === 'manifest' && args[0] === 'discover')) && !args.includes('--root')) args.push('--root', cwd);
+  let runtime = {};
+  const config = resolve(skillRoot, 'runtime.json');
+  if (existsSync(config)) runtime = JSON.parse(readFileSync(config, 'utf8'));
+  let cliPath = process.env.FORGE_FABRIC_CLI || runtime.cliPath;
+  if (!cliPath) {
+    const lookup = spawnSync(process.platform === 'win32' ? 'where.exe' : 'which', ['forge'], { encoding: 'utf8', windowsHide: true });
+    for (const candidate of lookup.stdout?.trim().split(/\r?\n/).filter(Boolean) || []) {
+      const bin = realpathSync(candidate);
+      cliPath = [bin, resolve(dirname(bin), 'node_modules/forgeos/bin/forge.mjs')].find(path => path.endsWith('.mjs') && existsSync(path));
+      if (cliPath) break;
+    }
+  }
+  if (!cliPath || !isAbsolute(cliPath) || !existsSync(cliPath)) throw new Error('Forge runtime not found. Install this skill with --runtime <absolute forge.mjs>, or set FORGE_FABRIC_CLI.');
+  // No recorder Delta side effects for repository reads; artifacts are explicit analyze outputs.
+  const result = spawnSync(runtime.nodeExecutable || process.execPath, [realpathSync(cliPath), surface, ...args, '--no-delta'], { cwd, stdio: 'inherit', windowsHide: true });
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}

package/.npmignore

@@ -5,5 +5,15 @@ node_modules/
 .forge/
 tests/
 examples/
+adapters/**/target/
+examples/**/target/
+*.class
+*.jar
+**/*.class
+**/*.jar
+src/forge/_generated/**
+!src/forge/_generated/
+!src/forge/_generated/releaseManifest.json
+!src/forge/_generated/releaseManifest.ts
 *.tgz
 npm-debug.log*