forgeos 0.1.0-alpha.67 → 0.1.0-alpha.69

package/docs/architecture/agent-fabric/PORTABLE_PROJECTS_PLAN.md

@@ -0,0 +1,136 @@
+# Agent Fabric across repositories
+
+## Outcome and boundaries
+
+The existing Codex App conversation remains the interface. One personal skill teaches
+Codex to prepare, execute, observe and resume Fabric workflows in the current project.
+The Forge runtime is shared; each Git repository has its own owner, state and isolated
+worker clones. Projects do not need a Forge application manifest or a Forge dependency.
+Windows and WSL copies are separate projects; this integration never migrates or syncs them.
+Owner startup does not start a model. Managed Codex workers use the host's configured
+Codex authentication and can consume its allowance. Local publication applies validated
+files; commit, push, npm release and deployments remain separately scoped actions.
+
+## 1. Portable skill and distribution
+
+Maintain the skill at `.agents/skills/forge-agent-fabric`, include it and its installer
+in the npm package, and make its protocol reference self-contained. Install once with
+`forge fabric install-skill --json` from any directory; add `--dry-run` to preview.
+The underlying `node scripts/install-agent-fabric-skill.mjs` also supports custom
+destination/runtime and explicit replacement; default destination is
+`~/.agents/skills/forge-agent-fabric`. Installed `runtime.json` stores the absolute
+Node executable and Forge CLI path. The helper resolves the target Git root and invokes
+the runtime with that root as cwd, without shell interpolation. An environment override
+and installed CLI fallback support different hosts. Runtime updates require reinstalling
+the skill to update the selected path/version; no implicit remote downloads occur.
+
+The installer stages changes, preserves unknown existing skills unless explicitly replaced,
+backs up replacements outside skill discovery, and reports unchanged installations.
+Installing a skill neither registers all local repositories nor installs hooks.
+
+## 2. Project identity and registration
+
+`fabric project-register [--project-id <id>] --json` resolves the current directory to
+the canonical Git toplevel and verifies HEAD. Default ids combine a readable directory
+name with a root digest, so equal names in different directories do not collide.
+`fabric project-list --json` reads the personal registry at
+`~/.forge/agent-fabric/projects.json`. Registration uses a bounded exclusive lock and
+atomic file replacement. Conflicting ids/roots and malformed or symlinked registry
+files are rejected. A registered path is resolved again before dispatch; moved/replaced
+roots cannot silently redirect an existing project id. Non-Git/empty repositories need
+initialization and an initial commit before managed cloning can run.
+
+The registry is host-local. No project credentials, owner bearer tokens or source contents
+are stored there. Registration is explicit and does not discover every directory on disk.
+
+## 3. Owner lifecycle and diagnostics
+
+`fabric doctor --json` resolves the Git root, reads optional settings, checks SDK availability,
+attempts a bounded `codex login status`, and authenticates any existing owner. It neither
+starts workers nor creates an owner. An unverified login is reported rather than inferred.
+`fabric ensure-owner --json` reuses an authenticated owner or starts `fabric serve` hidden
+and detached with cwd set to this root. Logs and endpoint metadata stay under
+`.forge/local/agent-fabric/`. Startup uses a per-project exclusive lock and bounded wait.
+Only its own newly spawned process may be stopped if startup times out; unknown live
+processes are not killed. An unreachable live endpoint requires diagnosis instead of
+starting another database owner. Startup locks surviving a crash are recovered only
+after their recorded process demonstrably exits, with serialized recovery and a byte
+readback. Live, malformed or unverified locks require inspection; they are never erased
+solely because a timer elapsed.
+If a process dies during recovery itself, its `.recovery` guard can require manual
+inspection after confirming that guard's process exited; diagnostics name both files.
+
+Authenticated health checks expose root and pid, never the endpoint token. Existing owners
+from the previous release are recognized through a read-only managed status probe.
+The owner remains an ordinary local process: restarting the machine requires starting it
+again; no OS service or periodic wakeup is installed.
+
+## 4. Optional project profile
+
+`.forge/fabric.json` is a small declarative file, not a Forge app configuration:
+
+```json
+{
+  "schemaVersion": 1,
+  "maxConcurrency": 2,
+  "environment": { "mode": "auto", "ignoreScripts": true, "timeoutMs": 120000 },
+  "verificationCommands": [["node", "--test"]]
+}
+```
+
+The shared managed request transport merges environment/concurrency defaults into
+`run-start`; explicit request values win. The profile does not change existing runs or
+silently append verification nodes. The skill reads suggested argv arrays and selects
+checks appropriate to the actual task. This avoids disguising executable project scripts
+as configuration reads. Unknown fields, excessive files, symlinks and invalid values
+are rejected. Node dependency preparation continues to use lockfiles and isolated copies;
+other stacks need explicit workflow commands and available host tooling. No universal
+Python/Go/Java provisioning is implied. Credentials and .env files are not copied merely
+because a profile exists.
+
+## 5. One MCP, multiple projects
+
+Keep the shared runtime's `mcp serve` entrypoint. Add `fabric_project_register`,
+`fabric_project_list`, `fabric_project_doctor`, and `fabric_owner_start`. Fabric tools
+accept an optional top-level `projectId`. The router resolves registered ids, removes
+the routing field before backend validation, then forwards to that root's owner.
+Explicitly routed responses include `projectContext: { id, root }` for readback.
+Calls without projectId retain the existing default workspace for compatibility.
+Hooks and non-Fabric agent-memory tools remain bound to the configured default workspace.
+Run calls cannot supply an arbitrary root. The skill must use explicit projectId outside
+the default workspace, or use CLI with the current Git root as cwd.
+
+MCP configuration remains one shared runtime entry. Restart/reconnect the Codex tool
+session to discover a changed tool catalog; use the skill's CLI helper immediately while
+the current conversation still has its old catalog. Do not claim tools are loaded until
+they appear. Do not change unrelated MCP entries or weaken authentication to add routing.
+
+## 6. Native chat flow
+
+1. User requests Agent Fabric work in a project; Codex reads its AGENTS.md and task scope.
+2. Skill helper resolves the root and runs capabilities/doctor.
+3. Register only this project when MCP routing is needed, then ensure its owner.
+4. Build a managed DAG with explicit scopes, implementers, independent reviewer and checks.
+5. Dispatch through the CLI or loaded MCP tools, using bounded waits and durable cursors.
+6. Replan from observed results while preserving required review/verification obligations.
+7. Reconcile uncertain attempts after interruption; do not repeat effects blindly.
+8. Read final project/run identity and evidence, then report actual results in the same chat.
+
+SDK worker threads are separate executions; they are not newly created Codex App sidebar
+conversations. This workflow does not require the user to operate a separate dashboard.
+
+## 7. Validation and delivery
+
+Validate registry contention, duplicate names/ids, nested cwd resolution, unknown/moved
+roots, profile defaults and explicit overrides, owner authentication/start/reuse, MCP
+routing into a second real Git repository, and hook isolation. Exercise the skill installer
+against a temporary personal directory and its helper against the real runtime. Run an
+observed command workflow in an external fixture without dispatching paid Codex models.
+Run generation/check, targeted Fabric tests, typecheck/lint and the framework verifier.
+Install the personal skill only after these checks; register Forge explicitly for current
+MCP routing. Preserve existing auth, other skills, MCP configuration and unrelated files.
+
+An external command pilot proves routing, cloning, execution and state readback. It does
+not itself prove a new paid SDK implementation/review round, production deployment or
+human acceptance. Package inclusion is checked separately from npm publication; this
+implementation task does not require publishing a new release.

package/docs/architecture/agent-fabric/README.md

@@ -0,0 +1,153 @@
+# Forge Agent Fabric — Architecture Governance
+
+This directory is the governance record for the Forge Agent Fabric architecture baseline.
+It is deliberately separate from `docs/agent-fabric.md`, which describes the executable
+P0a implementation surface.
+
+## Governance package
+
+| Record | Purpose |
+| --- | --- |
+| [`S1.0B1_DECISION_FREEZE.md`](./S1.0B1_DECISION_FREEZE.md) | Freezes the architecture decisions, vocabulary, invariants, boundaries, and deferred scope that later slices must preserve or explicitly supersede. |
+| [`S1.0B2_EVIDENCE_FREEZE.md`](./S1.0B2_EVIDENCE_FREEZE.md) | Freezes the evidence proving the accepted P0a baseline and maps evidence to the frozen decisions/invariants. |
+| [`P0A_ACCEPTANCE_RECORD.md`](./P0A_ACCEPTANCE_RECORD.md) | Records exactly what was accepted when P0a was merged, what was not accepted, and the applicability/supersession rules. |
+| [`S1.1_SCOPE_AND_GATE.md`](./S1.1_SCOPE_AND_GATE.md), [`S1.1_CONFORMANCE_PLAN.md`](./S1.1_CONFORMANCE_PLAN.md) | Adopted planning inputs for the normative kernel; historical planning assessments remain intact. |
+| [`S1.1_NORMATIVE_KERNEL.md`](./S1.1_NORMATIVE_KERNEL.md), [`S1.1_CONFORMANCE_MATRIX.md`](./S1.1_CONFORMANCE_MATRIX.md) | Adopted operation rules, invariant traceability, conformance obligations and clarification register. |
+| [`S1.1_ADOPTION_RECORD.md`](./S1.1_ADOPTION_RECORD.md) | Records the exact reviewed head, evidence and merge that adopted S1.1; explains retained candidate wording in historical artifacts. |
+| [`S1.2_SCOPE_AND_GATE.md`](./S1.2_SCOPE_AND_GATE.md), [`S1.2_DESIGN_PLAN.md`](./S1.2_DESIGN_PLAN.md) | Adopted scope and delivery plan for the reference implementation design. |
+| [`S1.2_REFERENCE_IMPLEMENTATION_DESIGN.md`](./S1.2_REFERENCE_IMPLEMENTATION_DESIGN.md), [`S1.2_IMPLEMENTATION_TRACEABILITY.md`](./S1.2_IMPLEMENTATION_TRACEABILITY.md), [`S1.2_DESIGN_DECISIONS.md`](./S1.2_DESIGN_DECISIONS.md) | Adopted reference implementation design; 24 operation mappings, 35 invariant mappings, 16 event-family mappings and preserved S12-F01/F02 history. |
+| [`S1.2_ADOPTION_RECORD.md`](./S1.2_ADOPTION_RECORD.md) | Records the exact reviewed head, checks, repair-aware evidence and merge that completed S12-D12 and adopted S1.2. |
+| [`S1.3_SCOPE_AND_GATE.md`](./S1.3_SCOPE_AND_GATE.md), [`S1.3_CONFORMANCE_PLAN.md`](./S1.3_CONFORMANCE_PLAN.md) | Adopted S1.3 Proof & Conformance planning package; S13-P08 complete. It authorized only the limited S1.3-A evidence/reproduction stage, not new tooling or P0b. |
+| [`S1.3_EVIDENCE_CATALOG.md`](./S1.3_EVIDENCE_CATALOG.md), [`S1.3_CONFORMANCE_MATRIX.md`](./S1.3_CONFORMANCE_MATRIX.md), [`S1.3_REPRODUCTION_PROTOCOL.md`](./S1.3_REPRODUCTION_PROTOCOL.md), [`S1.3_GAP_AND_TOOLING_REGISTER.md`](./S1.3_GAP_AND_TOOLING_REGISTER.md) | Adopted S1.3-A Evidence Registry & Reproduction Baseline: stable evidence/gap IDs, 24 OP / 35 I / 16 event cross-index, reproduction rules and tooling-need decisions; historical candidate wording is preserved inside the reviewed artifacts. |
+| [`S1.3_A_ADOPTION_RECORD.md`](./S1.3_A_ADOPTION_RECORD.md) | Records the exact reviewed head, exact-SHA gates, preserved FAIL/INCONCLUSIVE observations and merge that completed S13-A12 and adopted S1.3-A. |
+| [`S1.3_FINAL_CLOSURE_RECORD.md`](./S1.3_FINAL_CLOSURE_RECORD.md) | Adopted final S1.3 closure supplement. It binds post-S1.3-A evidence/repairs while preserving historical GAP-002/GAP-008 limitations and establishes the boundary to P0b. |
+| [`P0B_SCOPE_AND_GATE.md`](./P0B_SCOPE_AND_GATE.md) | Adopted planning scope for the first bounded nondeterministic P0b vertical. Historical proposal wording in that record remains as authored. |
+| [`P0B_A_MODEL_ADAPTER.md`](./P0B_A_MODEL_ADAPTER.md), [`P0B_A_ADOPTION_RECORD.md`](./P0B_A_ADOPTION_RECORD.md) | P0b-A implementation description and exact reviewed-head adoption evidence, including the authorized keyless local Ollama smoke. |
+| [`CODING_AGENT_DELIVERY_PLAN.md`](./CODING_AGENT_DELIVERY_PLAN.md) | Proposed ordered local-first delivery plan for MCP clients and a keyless coding worker; it does not adopt a new runtime capability. |
+| [`P0B_B_LOCAL_CODING_SCOPE.md`](./P0B_B_LOCAL_CODING_SCOPE.md) | Candidate scope and gates for a trusted-repository, single-owner MCP and local Ollama coding pilot; no runtime adoption claim. |
+
+## Baseline coordinates
+
+- Repository: `Stahldavid/forge`
+- Accepted implementation head: `bfd2639579e650d4ad38ec1a81dbd55a5d68865e`
+- Merge commit on `main`: `8972496f09727456b8b9f3ceafc386beab5f39d0`
+- PR: `#9 — feat: add Forge Agent Fabric P0a protocol kernel`
+- PR merged: `2026-09-08T09:26:36Z`
+- Pre-P0a base: `6f54ee728761bf91ff65465d798286d6f47fbe67`
+
+The merge commit has the reviewed P0a head as its second parent. This means the accepted
+implementation tree is traceable directly from `main` without relying on an external
+branch remaining available.
+
+## Status model
+
+| Record / stage | Adoption event | State |
+| --- | --- | --- |
+| P0a executable acceptance | [PR #9](https://github.com/Stahldavid/forge/pull/9), `8972496f09727456b8b9f3ceafc386beab5f39d0` | Accepted |
+| S1.0B1/B2 and P0a acceptance record | [PR #11](https://github.com/Stahldavid/forge/pull/11), `7a99ec5ceb2bdd51c83790fd84b23e534be52806` | Adopted |
+| S1.1 scope and conformance plan | [PR #12](https://github.com/Stahldavid/forge/pull/12), `3a0ce40ffe31555709d213bf06d674c62f28ad32` | Adopted planning input |
+| S1.1 kernel and conformance matrix | [PR #13](https://github.com/Stahldavid/forge/pull/13), `4b796f49c480d782ec7e069f8eb5f7eae841876a` | Adopted; G-14 complete |
+| S1.2 scope and gate | [PR #14](https://github.com/Stahldavid/forge/pull/14), `d1e6a1bb605527f242b7a6fb6fa05d6ff3561f92` | Adopted planning input; S12-P06 complete |
+| S12-F01 compatible resource-rejection repair | [PR #15](https://github.com/Stahldavid/forge/pull/15), `d9275f4773c1082a993ffaf7b6a58d15eb139246` | Adopted separately; reviewed head `16157c8bd59feecef6aa31692ba90a0d94f84307` |
+| S12-F02 compatible identifier-dictionary repair | [PR #17](https://github.com/Stahldavid/forge/pull/17), `2ca5ba7d261cf4001aa755581caa4b29de109b35` | FIXED_AND_ADOPTED separately; reviewed head `a832e29a3e8c757249eb8a59b7774d6521b4853e` |
+| S1.2 complete reference design | [PR #16](https://github.com/Stahldavid/forge/pull/16), `d2f426b1577d457bc6609c4d8e88ef7a055a1a23` | `ADOPTED`; S12-D12 complete; reviewed head `a2ac1769ac74fe9f7a87558a27332aa7c2a95114` |
+| S1.3 scope and conformance plan | [PR #18](https://github.com/Stahldavid/forge/pull/18), `801c2192e64652ade19a642b2f09f8660963c74f` | `ADOPTED`; S13-P08 complete; reviewed head `c694e9091bc1211b27d7e5e934ff4b9905e6ae89` |
+| Delta semantic timeline test timeout/cleanup | [PR #20](https://github.com/Stahldavid/forge/pull/20), `92c470ae2319aed9bde734d4506767677abe5a3c` | Adopted separately; reviewed head `0c8fe25d65ff5619395f3cf1f24635ba99a8e34c`; test-only, no Agent Fabric semantic change |
+| S1.3-A evidence/reproduction baseline | [PR #19](https://github.com/Stahldavid/forge/pull/19), `de9449648d821086db3d6f214c1a39cd4c659c7e` | `ADOPTED`; S13-A12 complete; reviewed head `b48a8fb4d77a1d8f5df7d9d523623a2037966da0` |
+| S1.3 final closure | [PR #43](https://github.com/Stahldavid/forge/pull/43), `f29b717f496b7edcd74e3f230c962e568fd0e5d2` | `ADOPTED`; reviewed head `36a6c75dfcc2c59e33fb04a8dfb9ce95da10f2ed`; adopted tree `49677d9979c2652c96f1cc4e0f2f82a17cb10f8e` |
+| P0b bounded model-adapter scope | [PR #46](https://github.com/Stahldavid/forge/pull/46), `490c2b54a2a354cb38b0f527c6a3f9372f703ff5` | Adopted planning input for P0b-A only |
+| P0b-A bounded model adapter | [PR #52](https://github.com/Stahldavid/forge/pull/52), `de3e1d5c97448823792bac1fcb71ab16e877ebab` | Adopted experimental runtime slice; reviewed head `ec37aeaa1c293d63e98de0b523fc2815761bc3dd` |
+
+The adopted S1.3 planning coordinate remains
+`main@801c2192e64652ade19a642b2f09f8660963c74f`. The separately adopted PR #20 moved the
+repository/reproduction baseline to `main@92c470ae2319aed9bde734d4506767677abe5a3c`; that
+movement was assessed under S13-A01. S1.3-A was subsequently adopted by PR #19 at
+`main@de9449648d821086db3d6f214c1a39cd4c659c7e`.
+
+S1.3 is formally closed by PR #43 at
+`main@f29b717f496b7edcd74e3f230c962e568fd0e5d2`. The closure preserves GAP-002 and GAP-008 as
+historical/nonblocking limitations, closes GAP-001 and GAP-009 through separately adopted
+evidence, and keeps GAP-003…007 within their previously adopted applicability boundaries.
+Candidate/planning labels in exact historical source artifacts remain preserved as authored;
+adoption merges and later supplements establish subsequent state.
+
+The P0b Scope & Gate was adopted through PR #46 over the closed S1.3 baseline. It authorized
+implementation work only for P0b-A. PR #52 separately adopted the bounded model-invocation
+adapter after exact-head CI/security checks, a keyless live Ollama smoke, independent review
+and an explicitly authorized merge. The adoption record retains those coordinates and limits.
+
+After adoption, changes must not silently rewrite history. A material change to a frozen
+architecture decision requires a new superseding decision record that identifies:
+
+1. the decision/invariant being superseded;
+2. the reason for the change;
+3. compatibility and migration impact;
+4. new evidence and conformance obligations;
+5. the exact commit at which the new decision becomes applicable.
+
+Corrections that do not alter semantics (typos, links, formatting, evidence-location
+updates) may amend these files directly, but must not change the meaning of frozen
+invariants.
+
+## Precedence
+
+For the accepted P0a baseline, use this order when sources appear to disagree:
+
+1. accepted executable behavior at `main@8972496f09727456b8b9f3ceafc386beab5f39d0`;
+2. machine-readable schema and hardened replay/validation behavior in that baseline;
+3. `P0A_ACCEPTANCE_RECORD.md`;
+4. `S1.0B1_DECISION_FREEZE.md`;
+5. `S1.0B2_EVIDENCE_FREEZE.md`;
+6. `docs/agent-fabric.md`;
+7. older design notes, handoffs, experiments, or conversation history.
+
+This precedence rule prevents an older architecture note from overriding behavior that
+was explicitly implemented, adversarially reviewed, and accepted.
+
+S1.1 supplies the adopted operation-level specification of that same accepted behavior.
+Its adoption does not reverse this precedence or authorize a discrepancy with the frozen
+invariants. S1.2 supplies the adopted source/ownership/sequence mapping of that behavior;
+it cannot override S1.1 or turn an implementation accident into a normative rule. A
+conflict among source, freeze, kernel and adopted design requires explicit classification
+under the existing change rule.
+
+S1.3 evidence describes what was observed and how it can be reproduced. Evidence metadata,
+a runner, a formal model or a signature cannot manufacture runtime authority or silently
+change an `OP-*`/`I-*` obligation. The adopted S1.3-A baseline may classify gaps and
+recommend a future decision, but it cannot itself implement a repair/tool or erase a
+historical failed or inconclusive observation.
+
+P0b planning inherits that precedence. A model/provider adapter may extend execution, but
+cannot override the accepted deterministic authority/replay semantics merely because a live
+provider behaves differently or exposes additional capabilities.
+
+## Scope boundary
+
+The freeze does **not** declare the entire future Agent Fabric implemented or
+production-ready. It distinguishes three categories:
+
+- **ACCEPTED_P0A** — implemented, tested, independently reviewed, and merged;
+- **FROZEN_DIRECTION** — architecture direction that later slices must respect but that
+  is not fully implemented by P0a;
+- **DEFERRED** — intentionally outside the accepted baseline and requiring a future slice
+  and separate acceptance evidence.
+
+S1.2 — Reference Implementation Design is adopted. S1.3 planning and S1.3-A are adopted, and
+S1.3 is now formally closed through the final closure record.
+
+The closed S1.3 evidence package organizes evidence with stable IDs, separates historical
+acceptance from current reproduction/source mapping, preserves `PASS`/`FAIL`/`SKIPPED`/
+`NOT_APPLICABLE`/`BLOCKED`/`INCONCLUSIVE`, cross-indexes all 24 OP rules, 35 invariants and
+16 persisted event families, defines exact-SHA reproduction discipline and retains historical
+limitations without converting them into false green claims.
+
+A generic conformance runner, formal model checking, proof/evidence signing, cross-language
+or JCS conformance, machine-readable evidence automation, production retention, production
+persistence/recovery, consequential effects and the broader future Agent Fabric remain
+outside the accepted P0a/S1.3 baseline.
+
+The adopted P0b-A slice is limited to one real provider-backed bounded external inference
+behind the existing P0a permit/result boundary. It excludes tools/plugins/delegation,
+consequential target mutation, production persistence/outbox, recovery epochs, adaptive
+routing, persistent governed memory and plugin/evolution promotion. P0b-B and those broader
+capabilities have no adoption claim in this record.

package/docs/architecture/agent-fabric/REPOSITORY_MANIFEST_PLAN.md

@@ -0,0 +1,272 @@
+# Forge em repositórios existentes: manifesto, mapas e Agent Fabric
+
+Data: 2026-10-06
+
+Status: proposta revisada por subagent independente; ajustes incorporados em 2026-10-06. Nenhum comando ou campo proposto neste documento implica suporte atual.
+
+## 1. Objetivo
+
+Permitir que Codex prepare um repositório existente para usar análise, mapas, consultas CAIR e contexto do Agent Fabric, preservando sua arquitetura, ferramentas e runtime. Vue/Nuxt, Java/Spring e Docker/Compose devem estar presentes no primeiro piloto integrado, além de TypeScript/JavaScript.
+
+O usuário permanece no chat do Codex e pede, por exemplo: “Prepare este projeto para usar os mapas do Forge”. O agente descobre a estrutura, gera um `forge.manifest.json`, valida o documento e solicita análise. O Forge deriva mapas do código; o agente usa os mapas para localizar funcionalidades, planejar alterações e selecionar verificações.
+
+Não é necessária migração para commands, queries, banco ou runtime Forge. Descobrir operações não as transforma em ferramentas executáveis. Esta entrega de planejamento não autoriza implementação, publicação ou instalação de integrações em outros projetos.
+
+## 2. Evidência da implementação atual
+
+Repositório analisado: `C:/Users/stahl/Projects/forge`, versão local `0.1.0-alpha.68`.
+
+| Componente | Base existente | Lacuna |
+| --- | --- | --- |
+| Manifesto externo | Serviços, entries, schemas, HTTP/stdio e registro | Não representa análise de repositório sem serviço |
+| Brownfield import | Inventário, rotas, chamadas, riscos e candidatos | Orientado a migração; análise predominantemente textual |
+| Vue/Nuxt | Dependências e algumas páginas/componentes no frontend graph | Brownfield não coleta `.vue`; frontend graph assume `web` e bindings Forge |
+| Java/Spring | Controllers por annotations e inventário Maven | Regex, sem resolução semântica; Gradle ausente no inventário examinado |
+| App graph | Símbolos, módulos, referências, hashes e parsing incremental | Parser orientado a TypeScript/TSX; tipos parcialmente ligados ao runtime |
+| Test graph | Descoberta/classificação de testes | Extensões e diretórios específicos de TypeScript |
+| CAIR | Snapshot compacto, símbolos, referências e impacto | Leitura direta de artefatos do compilador Forge |
+| Docker | Backend de sandbox | Não equivale a grafo estático de Dockerfile/Compose |
+| Agent Fabric | Runtime compartilhado, registro de projetos, owners e clones | Falta integração explícita com os mapas propostos |
+
+Fontes relativas ao checkout Forge:
+
+- `src/forge/brownfield-import/index.ts` e `types.ts`.
+- `src/forge/compiler/external-manifest/{types,validate,registry}.ts`.
+- `schemas/forge-manifest.schema.json`.
+- `src/forge/compiler/frontend-graph/build.ts`.
+- `src/forge/compiler/app-graph/parser.ts` e `compiler/types/app-graph.ts`.
+- `src/forge/compiler/test-graph/build.ts`.
+- `src/forge/cair/snapshot.ts`.
+- `docs/brownfield-import.md` e `docs/forge-protocol.md`.
+
+Detalhe a corrigir: tipos/validador externo contemplam `commandArgs`, mas o JSON Schema examinado não declara o campo. Confirmar e alinhar schema, validadores, tipos, fixtures e documentação durante a implementação.
+
+Limites adicionais confirmados na revisão: o importador atual ignora `tests` e `__tests__` e lê arquivos `.env` e `.env.local` para extrair nomes de variáveis. Isso não prova emissão dos valores, mas viola a política proposta de não abrir esses arquivos. Reutilizar classificadores úteis após introduzir scanner configurável; não reutilizar a coleta atual sem correção. CAIR consulta fonte atual diretamente em definições e usa busca textual em referências; seu snapshot não garante que a resposta consultada pertença à mesma versão.
+
+## 3. Decisões de arquitetura
+
+### 3.1 Um manifesto, modalidades distintas
+
+Preservar o nome `forge.manifest.json`. Manter suporte ao protocolo de serviço 1.0. Introduzir uma modalidade discriminada de repositório, com schema próprio dentro do mesmo sistema de manifestos. A versão `2.0` abaixo é ilustrativa: decidir o versionamento final após verificar consumidores e política de compatibilidade.
+
+Internamente, separar `ServiceManifest` e `RepositoryManifest`; nunca fazer um consumidor de serviços assumir `manifest.service.name` em um manifesto de repositório. Um projeto analisado pode referenciar contratos de serviços existentes por arquivos relativos, sem transformar seus candidatos em serviços automaticamente.
+
+Introduzir loader discriminado antes do registry atual: descoberta automática de `forge.manifest.json` deve classificar o documento; registry/runtime externos recebem somente ServiceManifest. Um root RepositoryManifest não pode quebrar a geração de uma aplicação Forge nem tornar-se serviço inválido. Quando já existir um root ServiceManifest, discovery não o sobrescreve: oferecer documento composto versionado ou configuração externa/referências explícitas. Esta escolha integra a decisão de schema de E1.
+
+Exemplo conceitual, ainda não aceito pela CLI atual:
+
+```json
+{
+  "forgeProtocol": "2.0",
+  "kind": "repository",
+  "components": [
+    { "id": "frontend", "root": "frontend", "adapters": ["vue", "typescript"] },
+    { "id": "backend", "root": "backend", "adapters": ["java", "spring", "maven"] },
+    { "id": "infra", "root": ".", "adapters": ["docker"], "files": ["compose.yaml", "backend/Dockerfile"] }
+  ],
+  "exclude": ["**/node_modules/**", "**/target/**"],
+  "checks": [
+    { "id": "frontend-tests", "component": "frontend", "argv": ["npm", "test"] }
+  ]
+}
+```
+
+O manifesto declara configuração, raízes, aliases/overrides necessários e verificações sugeridas. Não contém inventário manual de todas as funções. Contratos de APIs e integrações são opcionais. Validar IDs únicos, caminhos, limites e conflitos entre componentes sobrepostos.
+
+Usar caminhos relativos ao repositório. A localização absoluta pertence ao registro host-local do Fabric. Se o usuário não desejar arquivo no projeto, permitir um manifesto externo explicitamente associado a uma raiz registrada; não inferir raízes externas a partir de texto arbitrário.
+
+### 3.2 Descoberta determinística e complemento pelo Codex
+
+1. Resolver a raiz desejada e ler instruções do projeto.
+2. Descobrir manifests de pacotes, arquivos de build, componentes, frameworks e infraestrutura.
+3. Entregar inventário e lacunas ao agente.
+4. Codex prepara o manifesto e documenta decisões que a descoberta não resolve.
+5. Forge valida e calcula o grafo.
+6. Codex consulta o resultado e corrige configuração quando necessário.
+
+Definir um único resolvedor de raiz para todas as novas operações: raiz explícita ou projectId primeiro; descoberta ascendente limitada a marcadores reconhecidos quando omitida. Não exigir package.json para Java/infra. A CLI atual usa cwd em diversos caminhos; não assumir descoberta universal. Para análise estática, permitir diretório sem Git; preservar exigência Git+HEAD do Fabric para clones gerenciados. Relatar separadamente análise disponível e execução gerenciada disponível.
+
+Não aceitar root e projectId divergentes; se ambos forem fornecidos, exigir identidade canônica equivalente. Definir paragem de descoberta em worktrees/submódulos e diagnóstico para manifestos ancestrais ambíguos. Um manifesto externo não redefine a raiz para o diretório onde o arquivo está salvo.
+
+Registrar proveniência de declarações do agente e overrides. Não dar a essas declarações a mesma classificação de relações observadas no código. A configuração muda com a estrutura; mapas mudam com o conteúdo.
+
+### 3.3 Modelo comum de análise
+
+Criar um grafo neutro de repositório, separado das exigências do runtime Forge. Reutilizar hashing, serialização determinística, diagnósticos e primitives compatíveis. Adaptadores produzem fatos; uma fase de resolução combina fatos e identifica ambiguidades.
+
+Entidades: repository, component, package, file, symbol, page, UI component, endpoint, data model, test, container service, build stage, image, volume e network.
+
+Relações: contains, imports, references, calls, renders, routes-to, implements, tests, builds, runs, depends-on e connects-to. Distinguir ligação declarada de configuração, referência resolvida e possibilidade inferida.
+
+Cada fato inclui ID determinístico, localização, hash de fonte, adaptador/versão e referências de evidência. Definir estabilidade de IDs em edição e comportamento em renomeação. Uma mudança de ID não pode produzir referência silenciosa a uma entidade diferente.
+
+Padronizar coordenadas de fonte: offsets UTF-16 e intervalos semiabertos para integração Node, com linha/coluna e conversão explícita dos offsets de parsers em bytes. Preservar CRLF e Unicode; source mapping de blocos Vue retorna sempre posições no SFC original. IDs abreviados CAIR, como S#1, são handles locais ao snapshot: chamadas dependentes exigem snapshotId e não podem reaplicar o handle em outra ordenação.
+
+Usar categorias de evidência `declared`, `syntactic`, `resolved` e `inferred`, com resolução `complete`, `partial` ou `unresolved`. Não apresentar scores fixos como probabilidades calibradas.
+
+### 3.4 Cobertura como resultado de primeira classe
+
+Todo snapshot inclui arquivos encontrados, analisados, ignorados, com erro e sem adaptador; razões de exclusão; recursos não suportados; relações não resolvidas e diagnósticos. Mapas parciais continuam úteis, mas não podem ser apresentados como compreensão completa.
+
+## 4. Adaptadores do primeiro piloto
+
+### 4.1 TypeScript/JavaScript
+
+Reaproveitar extração existente quando independente do runtime. Identificar módulos, exports, símbolos e imports. Resolução de aliases, workspaces e imports deve seguir configurações reais, sem exigir package.json na raiz de todos os projetos. Diferenciar parsing de resolução semântica; escolher ferramentas após um spike de compatibilidade e distribuição.
+
+### 4.2 Vue/Nuxt
+
+Analisar `.vue` com entendimento de template, script, script setup e style. Preservar posições no arquivo original ao trabalhar com blocos. Identificar imports, componentes usados, props, emits, composables, stores, Vue Router e convenções Nuxt. Tratar aliases e autoimports conforme configuração.
+
+Relacionar páginas a componentes e clientes HTTP. Componentes dinâmicos, URLs construídas e autoimports não resolvidos permanecem explícitos no relatório. Não executar configuração arbitrária para apenas descobrir estrutura.
+
+Descobrir testes Vitest/Jest e uso de Vue Test Utils quando presentes. Distinguir teste encontrado, associação estática ao componente e cobertura observada por execução; nenhuma associação por nome é prova de cobertura executada.
+
+### 4.3 Java/Spring
+
+Nível inicial: parser sintático para packages, classes, interfaces, métodos, imports e annotations; endpoints, DTOs e relações Spring quando observáveis. Inventário Maven/Gradle multimódulo. Leitura estática de arquivos Gradle tem limites por ser uma DSL executável; declarar esses limites.
+
+Nível opcional: resolução semântica com ferramentas Java disponíveis, classpath e configuração explicitamente preparados. Não executar wrappers ou builds durante uma análise declarada estática. Reflection, Lombok, proxies e código gerado entram no relatório de cobertura. Chamada a interface não garante qual implementação recebe a chamada.
+
+Descobrir testes JUnit/TestNG, source sets e fixtures declarados. Reportar ligação sintática/inferida a classes separadamente de cobertura observada e de resolução semântica.
+
+### 4.4 Docker/Compose
+
+Analisar Dockerfile: FROM/estágios, contextos, COPY, referências a variáveis, entrypoint e command como informação. Analisar Compose: serviços, build contexts, imagens, portas, volumes, redes, profiles, depends_on e referências a secrets/configs/env.
+
+Cobrir arquivos adicionais e overrides por uma seleção explícita de cenário. Preservar interpolação não resolvida sem ler valores sensíveis automaticamente. Diferenciar porta interna de publicada e rede interna de endereço acessível pelo navegador. `depends_on` não prova tráfego nem disponibilidade.
+
+O cenário também identifica profiles Spring e modos Vite/Nuxt reconhecidos estaticamente, ordem de overlays e arquivos Compose selecionados. Esse conjunto e seus hashes fazem parte do snapshot; ambientes diferentes não compartilham silenciosamente a mesma resolução. Valores desconhecidos permanecem desconhecidos.
+
+Análise estática não inicia Docker, não constrói imagens e não faz pull. Inspeção observada de containers ou ferramentas externas seria operação separada e identificada.
+
+## 5. Resolução entre tecnologias
+
+Exemplo esperado:
+
+```text
+Pedidos.vue -> usePedidos -> cliente GET /api/pedidos
+            -> PedidoController -> PedidoService -> PedidoRepository
+
+Compose api -> build backend/Dockerfile -> componente backend
+```
+
+Relacionar por método HTTP, padrão de caminho, base URL, proxy, componente e cenário de configuração. Consumir OpenAPI local opcionalmente. Não usar apenas prefixos de URL: o detector atual pode gerar associação incorreta e deve ser substituído na fase integrada.
+
+Ligações sugeridas pelo modelo podem enriquecer a análise como declarações rastreáveis; não substituem resolução. Quando dois serviços oferecem o mesmo caminho, manter ambiguidade até haver contexto suficiente.
+
+## 6. Artefatos e consultas
+
+Armazenar artefatos locais em uma área dedicada, proposta `.forge/repository/`, sem escrever em `src/forge/_generated`. Manifesto pode ser versionado; cache e estado operacional são locais. Definir formato canônico, escritas atômicas e publicação de um snapshot completo somente após validação.
+
+Oferecer cache host-local explicitamente configurado quando não houver autorização ou interesse em escrever no repositório. Discovery/validate possuem modo sem escrita, inclusive sem telemetria local/recorder Delta; analyze declara seu destino de artefatos. A CLI atual pode registrar operações no Delta mesmo em comandos de leitura, com bypass existente `--no-delta`/`FORGE_DELTA=0`; a nova superfície precisa preservar o contrato sem escrita de ponta a ponta. Não editar `.gitignore` automaticamente.
+
+Separar provider de análise `forge-application` de `repository` na integração CAIR. Preservar queries atuais onde os conceitos correspondem; recursos dependentes do runtime e mutações CAIR não suportadas devem retornar capacidade indisponível em vez de fingir suporte.
+
+O provider deve cobrir snapshot, queries, resolução de referências, leitura de fontes e capabilities/actions. Alterar apenas snapshot não basta. Consultas precisam carregar snapshotId e detectar divergência com a fonte atual antes de devolver resultados. Não rotular a busca textual atual de Q REFS como referência semanticamente resolvida. No primeiro release repository, ações CAIR mutantes ficam indisponíveis; ações de leitura continuam disponíveis conforme cobertura.
+
+Consultas prioritárias: overview, locate, symbol, references, routes, dependencies, impact, tests, infrastructure e coverage. Respostas compactas, orçamento de contexto, paginação/cursor e referências ao código. Não despejar o grafo inteiro em todo prompt.
+
+Critérios de consulta incluem duas funções homônimas sem mistura, ausência de comentários/strings como referências resolvidas e rejeição de handle/snapshot obsoleto. Fonte posterior à análise não pode ser recortada usando offsets antigos.
+
+Comandos ilustrativos, não existentes nesta proposta:
+
+```text
+forge manifest discover --json
+forge manifest validate forge.manifest.json --json
+forge repository analyze --json
+forge repository context --query "autenticação" --json
+```
+
+A sintaxe final deve respeitar a CLI atual e evitar superfícies duplicadas com `import analyze` e CAIR. Definir depreciação ou aliases somente depois de verificar consumidores.
+
+## 7. Integração Agent Fabric e skill
+
+Skill conduz descoberta, geração e consultas; não exige que o usuário escreva JSON. Runtime e skill continuam compartilhados. Registro por projeto e seleção explícita de projectId mantêm isolamento CLI/MCP.
+
+Ao planejar um workflow, Fabric obtém contexto limitado à tarefa: snapshot, arquivos, relações, checks sugeridos e lacunas. Cada worker recebe contexto do seu próprio clone/snapshot; após composição de alterações upstream, renovar análise relevante. Não reutilizar o grafo do checkout original como se descrevesse um clone modificado.
+
+Maps ajudam a sugerir writeScope, dependências e revisão, mas não alteram silenciosamente obrigações de aceitação. Impacto estimado não autoriza pular verificações requeridas. Checks declarados não executam durante descoberta; execução é uma atividade do workflow com argv explícito e escopo autorizado.
+
+Hooks são opcionais para atualização; não necessários à análise. Não instalar hooks/MCP como efeito colateral. MCP pode expor queries de análise roteadas pelo registro existente.
+
+## 8. Incrementalidade, consistência e múltiplos repositórios
+
+Snapshot considera conteúdo local, incluindo mudanças não commitadas, manifesto, configs e versões dos adaptadores. Commit Git é metadado, não chave suficiente de validade.
+
+Reusar parsing por hash de arquivo. Invalidar resolução quando configuração, aliases, manifests de dependências ou contratos mudam. Detectar mudanças durante leitura; repetir o trecho necessário ou marcar snapshot inconsistente. Publicar artefatos atomicamente e serializar concorrência no cache, sem reutilizar locks de execução indiscriminadamente.
+
+Cada repositório tem identidade e snapshot próprios. Multi-repo usa referências explícitas a projetos registrados e contratos locais. Resposta identifica origem/versão de cada mapa; não afirma snapshot global atômico entre repositórios. Mudança em outro checkout não é sincronizada automaticamente.
+
+## 9. Limites de leitura e execução
+
+Respeitar raízes canônicas, exclusões explícitas e tratamento de symlinks. Não seguir referências para fora do escopo sem configuração autorizada. Limites de quantidade/tamanho/tempo aparecem nos diagnósticos, nunca como truncamento invisível.
+
+Não coletar valores de credenciais, `.env` reais, secrets ou payloads operacionais. Nomes/referências de variáveis podem ser mapeados. Sanitizar fragmentos de Docker/config quando contiverem valores sensíveis; não incluir fonte completa por padrão nos pacotes de contexto.
+
+Análise estática não executa package scripts, Gradle, Maven, arquivos de configuração JS, comandos de Docker ou adaptadores arbitrários. Adaptadores iniciais são embutidos/versionados. Provedores semânticos que exigem preparação são operações separadas, explícitas e com proveniência. A coleta de fontes precisa incluir testes conforme configuração e separar exclusões de credenciais da simples classificação de arquivos; não pode herdar cegamente o scanner brownfield atual.
+
+## 10. Entregas e critérios de aceite
+
+| Etapa | Entrega | Critério |
+| --- | --- | --- |
+| E1 | Schema discriminado, compatibilidade, root resolver e scanner configurável | Manifestos 1.0 continuam válidos; repo sem serviço/package.json validável; testes incluídos; arquivos sensíveis não abertos; caminhos e IDs verificados |
+| E2 | Grafo neutro, snapshot coerente e adaptadores iniciais | Vue + Spring + Compose presentes; hashes/cenário/IDs determinísticos; escrita atômica e mudança durante análise detectada; fixtures com fatos esperados e casos negativos |
+| E3 | CAIR/provider completo e contexto | Consultas compactas funcionam sem runtime Forge; leituras ligadas a snapshot; referências textuais diferenciadas; ações não suportadas indisponíveis |
+| E4 | Skill/Fabric | Contexto correto para checkout e clones; roteamento por projeto; zero execução implícita |
+| E5 | Otimização incremental e evolução semântica | Melhorar reutilização e resolução sobre a consistência mínima já entregue; cobertura, orçamento e custo observáveis |
+
+O primeiro piloto integrado deve usar Vue + Java/Spring + Compose, incluindo frontend/backend em diretórios independentes. Fixture hermética evita depender de produção; piloto em repositório real só com escopo escolhido e autorizado.
+
+Validação necessária:
+
+- Manifests antigos e novos; schema/tipos/validador concordantes.
+- Vue script setup, aliases, autoimports e componentes dinâmicos.
+- CLI em subdiretório, Java sem package.json, diretório sem Git analisável e execução Fabric corretamente indisponível sem Git+HEAD.
+- Scanner inclui testes declarados sem abrir `.env` reais; manifesto existente não é sobrescrito durante discovery.
+- Maven multimódulo, Gradle com lacunas explícitas e Java semântico indisponível.
+- Mesmo endpoint com métodos distintos, parâmetros, proxies e serviços ambíguos.
+- Docker multistage, Compose overrides/profiles, ports, networks e interpolação.
+- Relações frontend/backend/infra confrontadas com ground truth revisado.
+- Arquivos excluídos, symlinks, configurações sensíveis e limites.
+- Mudança não commitada, delete/rename, concurrent update e cache invalidation.
+- Q DEF/Q REFS após mudança de fonte: não devolver evidência de snapshot antigo como se atual; resultados textuais não recebem assurance semântica.
+- Homônimos, comentários/strings, handles CAIR de snapshots distintos, Unicode/CRLF e source mapping Vue.
+- Testes Vue e Java encontrados sem afirmar cobertura executada.
+- Cenários diferentes não reutilizam relações incompatíveis; discovery/validate sem escrita não criam Delta/cache nem alteram `.gitignore`.
+- Root RepositoryManifest não quebra registry/runtime de serviços; root ServiceManifest existente é preservado.
+- Independência do framework: nenhum arquivo/dependência runtime Forge exigido no projeto.
+- Fabric clones: contexto pré/pós upstream e publicação não usam evidência obsoleta.
+- Multi-repo: isolamento, IDs, raízes e snapshots distintos.
+
+Medir precisão das relações resolvidas, cobertura das relações conhecidas, proporção de ambiguidades, custo da primeira análise, custo incremental e tamanho dos pacotes de contexto. Não fixar metas numéricas antes de estabelecer baseline reproduzível; definir metas antes do aceite do piloto.
+
+## 11. Riscos e decisões pendentes
+
+- Extensão de manifestos deve evitar regressão na descoberta automática do root manifesto e nos consumers que assumem serviço.
+- Escolha de parsers/semantic providers exige spike de qualidade, Windows/Node, distribuição npm e licenças; não adicionar toolchain pesada ao caminho básico sem justificativa.
+- Vue/Nuxt e Java/Spring possuem recursos dinâmicos que impedirão completude estática.
+- Monorepos e configurações alternativas exigem descoberta por componente e seleção explícita de cenário.
+- Artefatos podem expor informação sensível se emitirem snippets sem sanitização.
+- Relação com `.forge/fabric.json`: esse arquivo continua configuração de execução; manifesto declara análise e sugestões. Definir precedência para checks sugeridos e evitar duplicar environment/maxConcurrency.
+- API de grafo e versão de manifestos devem ser escolhidas antes de ampliar consumidores.
+- Mapas de conhecimento não habilitam operações executáveis; adaptadores externos atuais preservam seu contrato separado.
+
+## 12. Resultado esperado
+
+Codex gera e mantém a configuração; Forge calcula mapas verificáveis e informa lacunas; CAIR fornece navegação compacta; Agent Fabric usa contexto atualizado para trabalhar. Vue, Java e Docker fazem parte da cobertura inicial, sem migração do projeto para o framework.
+
+## 13. Revisão independente
+
+Concluída pelo subagent `review_repository_manifest_plan` em 2026-10-06, por leitura do código atual, sem testes/builds/containers/CI. Parecer: arquitetura adequada com oito ajustes recomendados, incorporados neste documento:
+
+1. Provider CAIR completo, fonte vinculada a hash e referências com assurance correta.
+2. Resolvedor de raiz e distinção análise sem Git versus execução Fabric Git+HEAD.
+3. Scanner configurável incluindo testes, sem abertura de `.env` reais.
+4. Loader discriminado e coexistência de manifestos sem regressão de serviços.
+5. Consistência mínima em E2/E3 antes do Fabric; otimização incremental em E5.
+6. Descoberta de testes Vue/Java e convenção de coordenadas/handles.
+7. Modo sem escrita incluindo recorder Delta e opção de cache host-local.
+8. Cenário de configuração como parte da identidade do snapshot.
+
+Evidências detalhadas e relatório em `FORGE_REPOSITORY_MANIFEST_REVIEW.md`, no mesmo diretório. A revisão é documental e não constitui validação da implementação futura. Versionamento definitivo, escolha de parsers e metas de desempenho permanecem decisões explicitamente pendentes.

package/docs/changelog.md

@@ -4,6 +4,38 @@ Release history for the `forgeos` npm package.
 
 The canonical source file in the repository is `CHANGELOG.md`.
 
+## Unreleased
+
+- Explicit repository runtime plans, isolated-copy command execution and bounded Nuxt,
+  Spring, Docker and HTTP artifact context, with current-source/manifest/scenario binding
+  and expiration. CLI and MCP share execution opt-in; prepared Fabric workers consume
+  matching saved observations without starting exporters.
+
+- Lazy large-map hydration, compatible streaming fingerprints, automatic retained
+  cache cleanup and source-bound paired agent benchmark planning/reporting. The
+  benchmark evaluates supplied evidence without implicit model/check execution.
+
+- Deterministic scoped repository retrieval, precise case-level test associations,
+  static Nuxt/HTTP resolution, declared client mappings and informative check requirements.
+- Validated partitions for large maps and root-neutral facts, prepared-clone parse
+  reuse and the read-only `repository quality --cases` benchmark. Static quality remains
+  partial; suggested checks and models are not executed by analysis.
+
+## 0.1.0-alpha.69
+
+- Repository manifests and static maps for existing TypeScript/JavaScript, Vue/Nuxt,
+  Java/Spring/Maven/Gradle and Docker/Compose projects without adopting the Forge runtime.
+- Snapshot-bound CAIR queries, incremental parsing, bounded project-routed MCP context
+  and validated cache identity/source provenance.
+- Agent Fabric workers receive the map of their own prepared clone; the shared personal
+  skill also supports analysis in projects without Git.
+- Static local TypeScript configuration inheritance, Vue conditional branches and
+  multiline Dockerfile instructions; ambiguous and dynamic behavior remains explicit.
+- Local release staging preserves npm exclusions; the installed-package smoke checks
+  external Vue + Spring + Compose maps in addition to the application quickstart.
+- Patched transitive dependency resolutions for provider utilities, PostCSS, Nano ID
+  and URI parsing remove the advisories reported by the checked-in lockfile audit.
+
 ## 0.1.0-alpha.63
 
 - `forge status` now verifies generated output deterministically instead of