@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/README.md

@@ -1,7 +1,7 @@
 # ForgeLoop — Verifiable Engineering Protocol
 
 <p align="center">
-  <img src="./docs/assets/eng_readme_forgeloop.png" alt="ForgeLoop — Loop Engineering for AI Agents" width="100%">
+  <img src="./docs/assets/forgeloop-architecture.png" alt="ForgeLoop architecture infographic" width="100%">
 </p>
 
 [![CodeQL](https://github.com/cassiomc1/forgeloop/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/codeql.yml)
@@ -11,16 +11,9 @@
 [![Package smoke](https://github.com/cassiomc1/forgeloop/actions/workflows/package-smoke.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/package-smoke.yml)
 [![Release notes](https://github.com/cassiomc1/forgeloop/actions/workflows/release-notes.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/release-notes.yml)
 
-ForgeLoop is a protocol CLI for AI-assisted development.
-It turns outcomes into contracts, deterministic routing, resumable state,
-evidence-backed verification, recovery, cross-harness continuity, repository
-discovery, and validator-backed completion—not an agent or LLM runtime.
+ForgeLoop is the deterministic governor for AI-assisted engineering. Jev provides bounded System One semantic input; the host coding model provides System Two implementation. ForgeLoop owns lifecycle, claims, gates, evidence, completion, recovery, and publication truth.
 
-Operational sources are indexed in [`DOCS_INDEX.md`](./DOCS_INDEX.md).
-[`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) is canonical;
-[`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) defines discovery,
-[`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md) stores project facts, and
-[`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) selects relevant guides.
+Operational sources: [`DOCS_INDEX.md`](./DOCS_INDEX.md); [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) is canonical; [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) defines discovery; [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md) stores project facts; [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) selects guides.
 
 ## Where should I start?
 
@@ -29,7 +22,9 @@ Operational sources are indexed in [`DOCS_INDEX.md`](./DOCS_INDEX.md).
 - **Full protocol specification** → [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md)
 - **Integrating an AI harness** → [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md)
 - **Optional advisory context providers** → [`docs/ADVISORY_CONTEXT.md`](./docs/ADVISORY_CONTEXT.md)
+- **Provider extension architecture** → [`docs/PROVIDER_ARCHITECTURE.md`](./docs/PROVIDER_ARCHITECTURE.md) and [`docs/PROVIDERS.md`](./docs/PROVIDERS.md)
 - **Agent bootstrap summary** → [`docs/AGENT_PROTOCOL_SUMMARY.md`](./docs/AGENT_PROTOCOL_SUMMARY.md)
+- **Portable ForgeLoop Agent Skill** → [`skills/forgeloop/SKILL.md`](./skills/forgeloop/SKILL.md) and [`docs/AGENT_SKILL.md`](./docs/AGENT_SKILL.md)
 - **Continuing another harness's task** → [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md)
 - **CLI command reference** → [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md)
 - **Artifact & schema reference** → [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md)
@@ -42,10 +37,7 @@ Operational sources are indexed in [`DOCS_INDEX.md`](./DOCS_INDEX.md).
 
 ## Real execution proof
 
-The repository-only [execution PoC](https://github.com/cassiomc1/forgeloop/blob/main/poc/README.md) covers workload, protocol
-artifacts, trusted provenance, receipts, evidence, and audit. It reached
-validator-backed `COMPLETE / VALID` and preserves a later
-`E_RECEIPT_PATH_MISMATCH` after publication changed the repository.
+The repository-only [execution PoC](https://github.com/cassiomc1/forgeloop/blob/main/poc/README.md) demonstrates workload, protocol artifacts, trusted provenance, receipts, evidence, audit, and validator-backed `COMPLETE / VALID`.
 
 - [Canonical technical audit](https://github.com/cassiomc1/forgeloop/blob/main/poc/reports/poc-20260826-real-execution-technical-audit-v2.md)
 - [Evidence package](https://github.com/cassiomc1/forgeloop/tree/main/poc/evidence/poc-20260826-real-execution/)
@@ -74,29 +66,38 @@ validator-backed `COMPLETE / VALID` and preserves a later
 | SQL | [guide](./ENG/sql-development-eng.md) |
 | Go | [guide](./ENG/go-development-eng.md) |
 | TypeScript | [guide](./ENG/typescript-development-eng.md) |
+| Python | [guide](./ENG/python-development-eng.md) |
 | PHP | [guide](./ENG/php-development-eng.md) |
 | Swift | [guide](./ENG/swift-development-eng.md) |
 | Structural quality feedback | [`docs/STRUCTURAL_QUALITY.md`](./docs/STRUCTURAL_QUALITY.md) |
 
-Routing uses bounded structural evidence for Flutter, .NET, Node.js, Rust, C,
-C++, Java, Go, TypeScript, PHP, and Swift; SQL is a scoped schema/query/
-migration overlay. Source extensions, build tooling, lockfiles, compiler/JDK/
-runtime images, and prose alone fail where the specialist contract requires
-stronger project identity. The public project-evidence schema remains v1.
+Routing uses bounded structural evidence; SQL remains a schema/query/migration
+overlay. Extensions, tool files, lockfiles, runtime images, and prose alone do
+not establish project identity. Public project evidence remains v1.
+
+## Distribution and license
+
+GitHub hosts source and issues. The core npm package is publicly available;
+the MCP companion retains restricted distribution.
+ForgeLoop-owned source and documentation are licensed under the
+[PolyForm Noncommercial License 1.0.0](./LICENSE). Commercial use is not granted
+by this license. Third-party notices are documented in
+[`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md).
 
 ## Quickstart
 
 ### Installation
 
-Install the ForgeLoop CLI globally to make the `forgeloop` command available
-in your terminal:
+After your organization grants access, configure npm authentication and install:
 
 ```bash
 npm install --global @cassiomc1/forgeloop
 forgeloop --version
 ```
 
-Then, inside your project repository:
+Requires Node 24.19.0+ with `node:sqlite`. Migrate legacy state explicitly.
+
+Inside your project:
 
 ```bash
 forgeloop init
@@ -104,29 +105,20 @@ forgeloop doctor
 forgeloop search "example"
 ```
 
-If you prefer not to install globally, use `npx`:
-
-```bash
-npx @cassiomc1/forgeloop init
-npx @cassiomc1/forgeloop doctor
-```
-
 ### 60-second demonstration
 
-In a disposable directory, initialize the kit and create an isolated task. The
-result is deterministic and can be inspected by any compatible harness:
+In a disposable directory, initialize the kit and create an isolated task.
+Semantic checkpoints require a host-configured `TYPESAFE_API_KEY`; ForgeLoop never persists it.
 
 ```bash
 npx @cassiomc1/forgeloop init
 forgeloop task-create --task demo --claim src --json
-forgeloop route --task demo --work clean-code --json
+forgeloop contract-create --task demo --preset documentation --json
+forgeloop route --task demo --work code --json
 forgeloop preflight --task demo --json
 forgeloop next --task demo --json
 ```
 
-The last command reports the next safe action; it does not execute code or
-schedule agents.
-
 ### Optional code attestation
 
 Projects may opt into source-content attestation after a valid completion. The
@@ -152,7 +144,9 @@ results. Provider output is never lifecycle state, evidence, authority,
 completion truth, or next-action authority, and it is never executable as a
 protocol command. The optional Ripwire adapter follows the same boundary; see
 [`docs/ADVISORY_CONTEXT.md`](./docs/ADVISORY_CONTEXT.md) and
-[`docs/RIPWIRE_ADAPTER.md`](./docs/RIPWIRE_ADAPTER.md).
+[`docs/RIPWIRE_ADAPTER.md`](./docs/RIPWIRE_ADAPTER.md). The optional OpenSrc
+adapter exposes external package source context through the same boundary; see
+[`docs/OPENSRC_ADAPTER.md`](./docs/OPENSRC_ADAPTER.md).
 
 ### Optional task boundaries and differential verification
 
@@ -178,8 +172,8 @@ raising `VERIFIED` to `ATTESTED`. See [`docs/REVISION_PROVIDERS.md`](./docs/REVI
 
 Generic CI provides a platform-neutral revision-range boundary; thin GitHub,
 GitLab, local, or enterprise adapters may translate revisions without adding
-trust rules to the protocol core. The CLI and integration API remain usable
-across supported platforms, with MCP as an optional local adapter.
+trust rules to the protocol core. CLI and Integration API remain cross-platform;
+MCP is optional.
 
 ### Durable external actions
 
@@ -209,20 +203,18 @@ forgeloop protocol-info --json
 | Validate completion | Yes | Provides real work and evidence |
 | Schedule agents or LLM inference | No | External to the protocol |
 
-For a concrete exchange between tools, see
-[cross-harness continuity](./docs/CROSS_HARNESS_CONTINUITY.md).
-
-From a published package, initialize a target project with:
+From the privately delivered package, initialize a target project with:
 
 ```bash
 npx @cassiomc1/forgeloop init
 npx @cassiomc1/forgeloop doctor
 ```
 
-The CLI installs canonical documents under `.forgeloop/kit/`, keeps small
-native discovery shims at the project root, stores project-scoped
-configuration under `.forgeloop/`, and stores task-scoped protocol artifacts
-under `.forgeloop/task-state/<taskKey>/`.
+The CLI installs canonical documents under `.forgeloop/kit/`, keeps native
+discovery shims at the project root, and stores project configuration under
+`.forgeloop/`. Task artifacts use `.forgeloop/task-state/<taskKey>/` as their
+logical portable export path; SQLite mode stores mutable records in
+`.forgeloop/state.sqlite`.
 `update` preserves target-specific profile facts and locally modified files.
 
 ForgeLoop adapts protocol depth to task risk and scope, preserving verifiable
@@ -254,8 +246,7 @@ host-reported or `UNKNOWN`; values are never estimated.
 capability, but advisory recall remains Integration API only. The stock CLI
 does not auto-recall providers and does not expose a `context-recall` command.
 
-Before npm publication, the same source checkout can be exercised without a
-network or package lookup:
+Validate the source checkout offline before any private release:
 
 ```bash
 node src/cli.js init
@@ -363,20 +354,20 @@ ForgeLoop supports isolated, concurrent tasks within the same repository via det
 # Create an isolated task claiming specific directories
 forgeloop task-create --task auth-feature --claim src/auth --claim tests/auth --json
 
-# List active and completed tasks
 forgeloop task-list --json
 
-# Ask for deterministic conflict/recovery guidance
 forgeloop next --task auth-feature --json
 
-# Only for a task classified STALE or ABANDONED: release effective claims
+# Release claims only for a STALE or ABANDONED task
 forgeloop task-recover --task auth-feature --acknowledge-recovery --json
 
-# Reacquire conflict-free claims before mutating a recovered task again
+# Explicitly abandon an active non-terminal task when its objective is no longer valid
+forgeloop task-abandon --task auth-feature --acknowledge-abandonment --json
+
+# Reacquire conflict-free claims before mutating a recovered task
 forgeloop task-resume --task auth-feature --json
 
-# Run standard lifecycle commands targeting the task
-forgeloop route --task auth-feature --work clean-code --surface backend
+forgeloop route --task auth-feature --work code --surface backend
 forgeloop preflight --task auth-feature --json
 forgeloop advance --task auth-feature --to EXECUTING
 forgeloop complete --task auth-feature --json
@@ -395,6 +386,12 @@ disabled. The standalone acknowledgement flag is not host-attested authority.
 settlement, normal claim-overlap, and clean-checkout checks succeed. Never
 create, edit, or delete `recovery.json` manually.
 
+`task-recover` is reserved for canonical `STALE`/`ABANDONED` classification.
+`task-abandon` is the separate explicit path for an active non-terminal task:
+it records `TASK_ABANDONED`, releases claims as `RELEASED_BY_RECOVERY`, keeps
+the phase unchanged, and never implies completion or publication. `clear-state`
+only removes a checkpoint and is not a claim-release or abandonment mechanism.
+
 ### Executable policy verification & brownfield baselines
 
 ForgeLoop enforces automated, non-interactive verification rules (`rules.json`) with zero interactive dependencies:
@@ -431,12 +428,20 @@ See [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) and [`LOOP_SYSTEM_DESIGN.
 
 ## Architecture flow
 
+<a href="./docs/assets/diagrams/forgeloop-engineering-flow.html">
+  <img src="./docs/assets/forgeloop-lifecycle-animated.svg" alt="Animated ForgeLoop evidence-first loop: Contract, Route, Preflight, Execute, Evidence, Review, VALID, with an evidence-only correction loop" width="100%">
+</a>
+
+*Animation: the rail pulses through each step in order. It loops forever and
+respects reduced-motion settings. Select the image to open the full animated
+interactive explorer.*
+
 The canonical source is the typed Archify workflow
 [`docs/diagrams/forgeloop-engineering-flow.workflow.json`](./docs/diagrams/forgeloop-engineering-flow.workflow.json).
 The committed animated interactive explorer is
 [`docs/assets/diagrams/forgeloop-engineering-flow.html`](./docs/assets/diagrams/forgeloop-engineering-flow.html),
 which traces it. The
-animated, self-contained SVG fallback is
+detailed, self-contained SVG fallback is
 [`docs/assets/diagrams/forgeloop-engineering-flow.svg`](./docs/assets/diagrams/forgeloop-engineering-flow.svg),
 and the deterministic hash receipt is
 [`docs/assets/diagrams/forgeloop-engineering-flow.receipt.json`](./docs/assets/diagrams/forgeloop-engineering-flow.receipt.json).
@@ -449,8 +454,6 @@ The broader architecture and the CLI-only search boundary are in
 
 [Open the animated ForgeLoop evidence-first engineering flow](./docs/assets/diagrams/forgeloop-engineering-flow.html)
 
-![ForgeLoop evidence-first engineering flow (animated SVG fallback)](./docs/assets/diagrams/forgeloop-engineering-flow.svg)
-
 Two focused, source-bound workflow
 diagrams complement it. The [Verification Trust Flow source](./docs/diagrams/forgeloop-verification-trust-flow.workflow.json),
 [animated explorer](./docs/assets/diagrams/forgeloop-verification-trust-flow.html),
@@ -516,8 +519,9 @@ it must not infer current ownership from `task.json` or `recovery.json` alone.
 
 ## Security and dependency boundary
 
-Runtime uses Node built-ins and approved exact `smol-toml`; it installs no
-agents, providers, plugins, services, or telemetry. Paths, symlinks, JSON,
+Runtime uses Node built-ins and the approved exact `@typesafe-ai/sdk` and
+`smol-toml` dependencies; it installs no agents, providers, plugins, services,
+or telemetry. Paths, symlinks, JSON,
 manifests, schemas, receipts, and secret-like values are bounded or checked.
 Install-capable verification requires trusted host authority; see
 [`THREAT_MODEL.md`](./THREAT_MODEL.md).

package/TERMINOLOGY.md

@@ -33,6 +33,8 @@
 | Integration level | The capability tier of an execution environment (`INSTRUCTION_DISCOVERED`, `PROTOCOL_CAPABLE`, `PROTOCOL_LIMITED`, `CONFORMANCE_VERIFIED`). |
 | Recovered task | A non-terminal task whose ordinary mutation authority is suspended and whose effective write claims are released by durable `recovery.json` state. |
 | Recovery acknowledgement | A caller declaration that it intends to recover a task classified `STALE` or `ABANDONED`; it is not a host-attested authority grant. |
+| Active-task abandonment | An explicit caller-acknowledged `task-abandon` operation that releases validated claims for a non-terminal active task without changing its phase or asserting completion. |
+| Abandonment event | The append-only `TASK_ABANDONED` recovery boundary and its transaction witness; it is distinct from automatic stale-task recovery and from completion. |
 | Historical claims | The write claims retained in `task.json` as task history, including while recovery releases their active ownership. |
 | Effective claims | The claims currently enforced for ownership conflicts: descriptor claims for an active task, or an empty set after validator-backed completion or active recovery. |
 | Claim reacquisition | The serialized `task-resume` operation that rechecks conflicts and checkout cleanliness before removing recovery state and restoring mutation authority. |

package/THIRD_PARTY_NOTICES.md

@@ -7,10 +7,9 @@ for reuse.
 
 ## Collection license
 
-The CLI and validator code are licensed under the MIT License in `LICENSE`.
-Original documentation is offered under CC BY 4.0 as described in
-`LICENSE-DOCS.md`. Those notices do not apply to adapted or external material;
-review the applicable source terms before redistributing such material.
+ForgeLoop-owned source and documentation are licensed under the
+[PolyForm Noncommercial License 1.0.0](./LICENSE). The notices below apply only to third-party
+components, adapted sources, vendored tools, and external references.
 
 ## Adapted and editorial sources
 

package/THREAT_MODEL.md

@@ -79,6 +79,7 @@ index location, process lifecycle, and normalized result boundary.
 | Chronology rewrite | Hides execution before route, gates, or verification | `.forgeloop/events.ndjson` | Append-only local ledger, sequence numbers, hash chaining, and chronology validation without prompts or hidden reasoning | A privileged process can still replace the ledger after validation | `tests/lifecycle.test.js` |
 | Concurrent protocol mutation | Two writers read the same state or ledger tail and silently overwrite each other | Task state, task event ledger, and transaction journal | Mutations acquire a lease-bearing task lock, stage writes in `.forgeloop/.txn/`, preserve a recovery manifest, and publish only after the callback completes; state mutators use an expected revision, while ledger appends validate a tail checkpoint and stage only a synchronized suffix | The filesystem does not provide a multi-file atomic commit primitive; a process killed during append is recovered by truncating to the journaled pre-append size rather than treated as complete | `tests/state-revision.test.js`, `tests/concurrent-ledger.test.js`, `tests/scale-ledger.test.js`, `tests/transaction.test.js` |
 | Stale lock theft | A live process loses exclusive ownership because another process removes or replaces its lock | `.forgeloop/locks/<taskKey>.lock` | Locks record hostname, owner instance ID, heartbeat, and lease; inspection distinguishes `NONE`, `LIVE`, `STALE`, `UNKNOWN`, and `CORRUPT`; stale-only release quarantines the observed inode and compares lock ID, heartbeat, and owner instance before deletion | A malicious or separately privileged actor can still delete local locks; an expired lease remains a recovery heuristic rather than remote liveness proof | `tests/task-lock.test.js`, `tests/task-recover.test.js` |
+| Active-task abandonment used to release another task's claims | A caller targets the wrong active task or races a lifecycle mutation to steal/release its write scope | Task identity, descriptor, work state, ledger, recovery artifact, project claims lock, and task transaction | `task-abandon` requires an explicit task ID and acknowledgement, validates canonical ownership and ledger integrity, serializes project/task mutation, revalidates phase/revision/ledger sequence/claims, and records append-only `TASK_ABANDONED` evidence without completion authority | A caller with legitimate local mutation authority can intentionally abandon its own task; that is the intended authority boundary | `tests/task-abandon.test.js`, `tests/task-recovery-concurrency.test.js` |
 | Forged recovery tombstone | A schema-valid fake `recovery.json` makes historical claims disappear without an official recovery event | Task descriptor, recovery artifact, and complete event ledger | The canonical claim-state resolver releases claims only when every artifact field matches one unresolved recovery history cycle; a tombstone alone is `INCONSISTENT`, retains historical claims, and disables mutation | A privileged actor can replace every linked local artifact; validation proves consistency, not remote attestation | `tests/task-claim-state.test.js`, `tests/task-claim-ownership-integration.test.js`, `tests/task-recovery-invariants.test.js` |
 | Forged completion claim release | An actor changes `work-state.phase` to `COMPLETE` to make write claims disappear without canonical completion | Work state, canonical completion event, and the complete validated event ledger | Claim ownership releases COMPLETE claims only when state and a validated lifecycle ledger prove canonical completion (`COMPLETION_VALIDATED` bound to the task, coherent state/ledger, no contradicting later lifecycle event); otherwise ownership is `INCONSISTENT` with historical claims retained, mutation disabled, and overlapping acquisition blocked (`E_COMPLETION_OWNERSHIP_UNPROVEN`) | A separately privileged actor can rewrite all local artifacts consistently; ForgeLoop provides consistency verification, not external cryptographic attestation | `tests/completion-claim-ownership.test.js`, `tests/task-claim-state.test.js` |
 | Incomplete task-lock identity theft | A structurally incomplete persisted task lock (missing lockId, owner instance, operation, or lease) with plausible timestamps is classified LIVE/STALE and removed as stale | `.forgeloop/locks/<taskKey>.lock` identity validation | Task lock identity requires `taskId`, `lockId`, `ownerInstanceId`, `operation`, heartbeat, and a positive integer lease; incomplete metadata classifies `UNKNOWN` (never stale-releasable), lease values are never defaulted at validation time, and CAS release additionally requires `lock.taskId === requested taskId` plus unchanged observed identity | A privileged writer can still forge a fully identified lock; classification proves structure, not liveness | `tests/task-lock.test.js` |
@@ -86,6 +87,7 @@ index location, process lifecycle, and normalized result boundary.
 | Forged legacy-migration authority | A forged `LEGACY_RECOVERY_MIGRATION_RECORDED` claims `HOST_ATTESTED` authority to impersonate a host grant | Migration event authority validation | Legacy migration v1 accepts only `CALLER_ACKNOWLEDGED`; any other authority kind makes the event invalid and the ledger INCONSISTENT | Normal recovery events retain their own host-attestation boundary with trusted grant references | `tests/task-repair-legacy-recovery.test.js` |
 | MCP project-root substitution | A tool call supplies a different project root to read or mutate an unintended target | Immutable server-pinned project context | The ForgeLoop MCP server realpaths the project root once at startup and freezes it; project root is never a tool input | A privileged local process can still target other roots by launching its own server | `integrations/mcp/tests/` |
 | MCP claim-projection fork | An adapter derives claim ownership from raw artifacts (task.json, recovery.json) and disagrees with the canonical resolver | Canonical ownership resource | The `task/ownership` resource is derived exclusively from `resolveTaskClaimState()`; forged COMPLETE stays INCONSISTENT with retained claims through the resource surface | Presentation bugs could still mislabel values; the resolver remains the single authority | `integrations/mcp/tests/ownership.test.js`, `tests/integration-resources.test.js` |
+| Audit UX authority confusion or disclosure | A presentation consumer treats a read model as lifecycle authority or receives raw commands, paths, environment values, credentials, or provider output | Versioned bounded `task/audit-view` resource | The projection is read-only, resolver-backed, sequence-bounded, sanitized, and explicitly marks every authority dimension false | Presentation consumers must still preserve the canonical command/API boundary | `tests/audit-ux.test.js`, `tests/integration-capabilities.test.js` |
 | MCP capability escalation via tool input | Tool input (e.g. `force: true`, `acknowledgeRecovery: true`) elevates a server started without the matching capability | Launch-level capability gates re-checked per invocation | Risk classification is invocation-level; disabled capabilities refuse with `E_MCP_CAPABILITY_DISABLED`; recovery acknowledgement never upgrades launch policy; legacy repair stays hidden by default; deprecated `operatorAuthorized` is absent from schemas | A separately authorized local actor can restart the server in full mode | `integrations/mcp/tests/policy.test.js`, `integrations/mcp/tests/safety.test.js` |
 | MCP HTTP unauthenticated remote bind | A network-bound MCP endpoint exposes ForgeLoop operations to any reachable client without authentication | Loopback-only bind policy | The HTTP transport refuses every non-loopback bind with `E_MCP_REMOTE_NOT_SUPPORTED`; Host/Origin validation is defense against DNS rebinding, not authentication; remote access stays disabled until a separately designed authenticated boundary exists | A same-host process can still reach the loopback endpoint | `integrations/mcp/tests/http.test.js` |
 | MCP protocol downgrade / legacy fallback | Legacy-era traffic is silently served, weakening the declared 2026 security posture | Strict modern mode | The HTTP handler is constructed with the SDK strict-modern setting (`legacy: "reject"`); legacy handshakes are answered with an unsupported-protocol-version rejection instead of being served | Stdio remains available for clients that only speak older protocol generations | `integrations/mcp/tests/http.test.js` |
@@ -160,6 +162,13 @@ treated as trusted protocol input.
 | Provider identity substitution | Registry key and resolved provider `id` must match the declared identity | A host that controls the runtime registry can replace its own provider before the call | `tests/advisory-context-runtime.test.js` |
 | Unbounded provider retrieval | Query, item, total-output, raw-result, and timeout budgets are normalized and enforced before/while provider execution | The host controls provider resource usage outside the bounded call | `tests/advisory-context-service.test.js`, `tests/advisory-context-provider.test.js` |
 | Historical command replay from advisory text | Advisory output cannot satisfy command input, evidence, state, or next-action authority; recall is never automatic | A receiving host must still avoid copying untrusted text into its own command runner | `tests/advisory-context-security.test.js` |
+| OpenSrc executable substitution or version drift | Absolute host-selected path with exact lazy `--version` qualification on every recall; no PATH discovery | A host that swaps the binary and version together defeats qualification by definition | `tests/opensrc-advisory-provider.test.js` |
+| Malicious OpenSrc stdout path or cache escape | Exactly-one-line absolute-path rule, realpath canonicalization, cache containment, directory check, and symlink-escape rejection | A host-controlled cache root outside the project is assumed | `tests/opensrc-advisory-provider.test.js` |
+| Prompt injection in fetched source | Inert bounded snippet text under `NON_EXECUTABLE` advisory trust; never executed or converted to authority | A host may still display advisory text outside ForgeLoop | `tests/opensrc-advisory-provider.test.js` |
+| Credential or path leakage in errors and results | No raw stderr, environment, absolute cache path, or credentialed URL in public errors, items, sourceRefs, or transport metadata | Unknown encodings outside scanned fields remain host responsibility | `tests/opensrc-advisory-provider.test.js` |
+| Unbounded source tree or binary ingestion | Sorted traversal, generated directories skipped at any depth, symlink discipline, per-source entry ceiling (5,000, counting skipped entries), per-source read cap, one shared 8 MiB recall read budget, shared recall deadline, and binary skip enforced before further reads | The host controls cache size outside the bounded recall | `tests/opensrc-search.test.js` |
+| OpenSrc network and cache side effects | Explicit host-owned `OPENSRC_HOME`, documented fetch-on-miss, protocol-state side-effect-free recall | Registry access and cache writes are upstream OpenSrc behavior | `docs/OPENSRC_ADAPTER.md` |
+| OpenSrc timeout or output overflow | Shared recall deadline, 64 KiB process ceilings, and SIGTERM/SIGKILL escalation | A hung child holds OS resources until the grace timers fire | `tests/opensrc-process.test.js` |
 | Handoff acceptance replay | Acceptance is keyed by the immutable handoff and consumer identity and is checked against the append-only ledger | External systems may still deliver duplicate messages; callers must surface the canonical rejection | `tests/handoff-acceptance.test.js` |
 | Handoff double-consumption race | Serialized ledger append and exactly-once acceptance projection permit one consumer; same-consumer retry is idempotent | Filesystem privilege outside ForgeLoop can still corrupt local artifacts | `tests/handoff-acceptance.test.js`, `tests/concurrent-ledger.test.js` |
 | Stale Git checkout acceptance | Acceptance compares the handoff snapshot with the current branch and HEAD, work-state, contract, route, and changed paths | A separately privileged process can change the checkout immediately after validation | `tests/handoff-acceptance.test.js` |
@@ -169,6 +178,90 @@ treated as trusted protocol input.
 ForgeLoop does not make advisory text trusted. It makes the boundary explicit,
 bounded, and fail-closed where protocol-owned interpretation is required.
 
+## Provider extension boundary
+
+Provider output is untrusted input and the generic provider registry is an
+internal experimental surface. The public `providerExtensions` capability does
+not grant lifecycle, completion, evidence, or installation authority.
+
+| Threat | Mitigation |
+| --- | --- |
+| Malicious provider output | Strict JSON snapshot |
+| Mutable result after validation | Detached deep-frozen copy |
+| Getter/accessor execution | Reject accessors |
+| Proxy behavior | Reject proxies |
+| Custom object semantics | Plain JSON boundary |
+| Authority escalation | Reserved authority validation |
+| Error spoofing | Normalize provider exceptions |
+| Hanging factory | Shared deadline |
+| Hanging operation | Shared deadline |
+| Resource leak after timeout | Cooperative abort cleanup |
+| Payload amplification | Byte, depth, and node budgets |
+| Auto-install surprise | No installation authority |
+| Public API confusion | No `./providers` export |
+| False completion | Completion authority false |
+| False evidence | ForgeLoop validation required |
+
+## Security Review provider boundary
+
+Security Review is an optional host-injected observation surface. It does not
+install or discover scanners, execute provider text, persist task state, or
+grant lifecycle, evidence, completion, claim, ownership, command, or
+transaction authority. Requests and results are bounded strict snapshots and
+the factory/review pair shares one deadline and cooperative cancellation.
+
+| Threat | Mitigation |
+| --- | --- |
+| Malicious finding or fake completion claim | Reserved authority fields are rejected and trust metadata is stamped as observation-only, non-evidence, and non-executable. |
+| Oversized or mutable request/result | Relative-path, string, finding, diagnostic, byte, depth, node, and result-size limits plus detached deep-frozen snapshots fail closed. |
+| Provider hang or late completion | One shared deadline and `AbortSignal` cover lazy factory and review; late results cannot become observations. |
+| Scanner auto-install or ambient execution | Registration is explicit and lazy; ForgeLoop does not discover `PATH`, install tools, invoke shells, or own provider credentials. |
+| Sensitive output or path escape | Findings require bounded project-relative paths and reject secret-like content and absolute/file URLs. |
+
+## Browser verification boundary
+
+Browser verification is host-injected and explicit. It is not a browser
+sandbox, lifecycle adapter, or completion bridge.
+
+| Threat | Mitigation |
+| --- | --- |
+| Malicious provider or fake PASS/COMPLETE | Provider results cross a strict allowlist and authority-field rejection boundary; ForgeLoop derives status and stamps observation-only trust. |
+| Factory or verify hang | One ForgeLoop-owned deadline covers factory resolution, validation, verify, and normalization; expiry aborts the shared signal and applies bounded cleanup. |
+| Redirect escape or origin confusion | HTTP(S)-only, credential-free `finalUrl` and every reported navigation are checked against exact normalized allowed origins. |
+| Cookie, token, authorization, signed URL, or path leakage | Public provider failures are generic; portable observation fields and artifact refs reject sensitive patterns and absolute/file URLs. |
+| Prompt injection or malicious snapshots | Snapshot and diagnostic text is bounded portable observation only and has no executable or lifecycle semantics. |
+| Screenshot metadata abuse | Artifacts are bounded structured metadata with positive byte length, canonical SHA-256, portable refs, and no raw bytes. |
+| Oversized DOM or output | Bounded steps, assertions, snapshots, diagnostics, artifacts, URLs, and result size limits fail closed. |
+| Arbitrary JavaScript, file/data URLs, upload/download, or credentials | Strict request allowlists reject unsupported fields and non-HTTP(S)/credential-bearing URLs. |
+| Provider session reuse or browser network access | Providers own session cleanup and network behavior; ForgeLoop makes no sandbox claim and does not install or discover browsers. |
+
+The optional Agent Browser adapter adds a concrete process boundary without
+changing those claims:
+
+| Threat | Mitigation | Residual limitation | Test evidence |
+| --- | --- | --- | --- |
+| Executable substitution or shell injection | Absolute regular executable, `shell:false`, argv arrays, lazy exact-version check, and no PATH discovery | A privileged host can replace its executable between checks | `tests/agent-browser-process.test.js`, `tests/agent-browser-provider.test.js` |
+| Session/profile or ambient credential reuse | Fresh random session, adapter-owned cwd, filtered profile/restore/state/CDP/auto-connect/plugin/auth variables, and close in `finally` | Host-level browser state outside the adapter remains host responsibility | `tests/agent-browser-provider.test.js` |
+| Origin escape or malicious redirect | ForgeLoop exact-origin validation plus Agent Browser hostname allowlist | Host/browser networking is not a general sandbox | `tests/agent-browser-provider.test.js` |
+| Screenshot or process-output leakage | Temporary screenshot bytes, portable digest refs, bounded stdout/stderr, and generic errors | Host process and filesystem policy remain outside ForgeLoop | `tests/agent-browser-process.test.js`, core normalization tests |
+| Incomplete or spoofed command observations | Strict `{success:true,data}` envelopes, typed scalar observations, derived assertion status, and observation-only normalization | A real browser remains an external host capability | `tests/agent-browser-process.test.js`, `tests/agent-browser-provider.test.js` |
+| Temporary workspace overlap | Adapter-owned cwd and rejection of a configured temp root inside the verification target | Symlink and host filesystem policy remain host responsibilities | `tests/agent-browser-provider.test.js` |
+
+## Emulated Services provider boundary
+
+The optional Emulated Services adapter is a host-owned observation boundary for
+`vercel-labs/emulate` `0.11.2`. It is explicit and lazy: ForgeLoop neither
+installs nor discovers the executable and never grants the provider lifecycle,
+evidence, installation, or completion authority.
+
+| Threat | Mitigation | Residual limitation | Test evidence |
+| --- | --- | --- | --- |
+| Executable substitution or shell injection | Absolute regular executable, exact version qualification, argv-only spawn with `shell:false`, and no PATH discovery | A privileged host can replace its executable between checks | `tests/emulated-services.test.js` |
+| Ambient credential or secret leakage | Minimal environment allowlist, no raw stdout/stderr in public results, and no provider-controlled environment fields | Host process policy remains host responsibility | `tests/emulated-services.test.js` |
+| State overlap or project mutation | Random adapter-owned temporary cwd, target-root separation, and forced recursive cleanup | Host filesystem policy and symlink races remain host responsibilities | `tests/emulated-services.test.js` |
+| Unbounded child, output, or readiness | Bounded timeout, cancellation, stdout/stderr ceilings, readiness polling, SIGTERM/SIGKILL escalation, and fail-closed cleanup | A hostile child may consume resources until the OS releases it | `tests/emulated-services.test.js` |
+| Remote endpoint or authority confusion | Adapter constructs and validates loopback-only HTTP endpoints and returns detached observation-only results | The host controls the local service implementation | `tests/emulated-services.test.js` |
+
 ## Structural-quality provider boundary
 
 Structural-quality observations are untrusted external data. The built-in
@@ -193,6 +286,30 @@ context.
 ForgeLoop never changes Sentrux analytics preferences, installs the provider,
 or treats Sentrux Free diagnostics as necessary for score correctness.
 
+## Semantic decision safety floor
+
+Jev (the pinned TypeSafe `jev-1.13.0` model) is a non-authoritative semantic
+plane: it may rank or exclude only deterministically eligible, non-mandatory
+route guides, and it may raise but never lower the execution-profile safety
+floor. Mandatory safety protection is derived from canonical deterministic route
+reasons (`MANDATORY_SAFETY_REASONS` in `src/core/router.js`: auth surface plus
+the untrusted-input, personal-data, secrets, external-service, and publication
+trust-boundary risks), so a high-confidence semantic exclusion can never remove
+the `security` guide the router selected for a trust boundary; retained
+mandatory guides carry an explicit `MANDATORY_SAFETY_GUIDE` reason and
+low-confidence exclusions are retained as `JEV_LOW_CONFIDENCE_RETAINED`.
+Semantic decisions consume only sanitized bounded state, and credential material
+is excluded from state, artifacts, diagnostics, and logs. A semantic decision
+that cannot be obtained fails closed rather than silently weakening routing.
+
+| Threat | Mitigation |
+| --- | --- |
+| High-confidence Jev exclusion removes a deterministic mandatory safety guide | Protection derives from the router's own canonical safety reason set; `external-service` and other trust-boundary reasons retain `security` with `MANDATORY_SAFETY_GUIDE` |
+| Semantic plane drifts from deterministic eligibility | Jev operates only on deterministically eligible guides; it never creates eligibility, lowers the profile floor, or bypasses fail-closed cutover |
+
+`tests/execution-profile.test.js`, `tests/jev-decision-enforcement.test.js`,
+`tests/decision-cutover.test.js`.
+
 ## Boundary rules
 
 - Safe paths are checked before reading or writing; no protocol field is a
@@ -215,4 +332,26 @@ point at misleading files, claim verification/publication occurred, encode
 secret material, attempt path traversal, or imply authority. Mitigations are a
 bounded strict schema, secret-free writes, relative safe paths, task/contract/
 work-state fingerprint binding, current-checkout reconciliation, explicit
-non-evidence semantics, and complete separation from authority grants.
+non-evidence semantics, optional absence handling, and complete separation from
+authority grants. A missing continuity artifact is `NOT_APPLICABLE`; a present
+but malformed artifact remains fail-closed and continuity never supplies
+completion evidence.
+
+## Bootstrap Gate And Contract Provenance
+
+Built-in contract preset references are limited to the canonical
+`contract-preset:documentation`, `contract-preset:bug`, `contract-preset:feature`,
+and `contract-preset:release` namespace. Unknown values in that namespace are
+rejected, while mixed contracts still require external source-registry entries.
+
+The `gate-record` command accepts only route- or policy-required gates before
+execution. ForgeLoop computes referenced artifact hashes and rejects absolute,
+traversal, missing, directory, and symlink-escaping paths. Gate decisions are
+caller-recorded observations and cannot claim host attestation or ForgeLoop
+execution provenance.
+
+The same boundary prevents fake caller digests, stale artifact approval,
+post-execution gate rewrites, and task substitution: digests are computed from
+bytes, preflight revalidates them, mutation freezes at execution, and persisted
+gate task IDs are checked against the active contract. Unknown preset names are
+rejected rather than becoming a spoofable built-in source namespace.