@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/PROTOCOL_INTEGRATION.md

@@ -181,6 +181,16 @@ authority, provenance, and safety-floor decisions remain unchanged.
 validator-backed completion remains unchanged.
 ```
 
+The capability handshake also advertises the versioned, read-only `auditUx`
+resource feature. `task/audit-view` is a bounded presentation projection
+composed from canonical status, audit, report, history, trace, ownership,
+next-action, approval, and recovery resolvers. It exposes no lifecycle,
+evidence, completion, mutation, or external-execution authority; hosts must
+use the canonical command/API path for mutations. Timeline pagination is
+sequence-based and bounded, and the projection omits raw event payloads,
+commands, environment values, credentials, provider output, and absolute
+paths. See [`docs/AUDIT_UX.md`](./docs/AUDIT_UX.md).
+
 ## Capability negotiation
 
 The public capability handshake exposes additive capability families separately
@@ -190,6 +200,7 @@ from Protocol v1, schema v1, and Integration API v1:
 | --- | --- | --- |
 | `canonicalHandoffs` | v2 | Immutable handoff snapshots with ledger-backed exactly-once operational acceptance |
 | `advisoryContextProviders` | v1 | Lazy, opt-in, provider-neutral Integration API injection only |
+| `providerExtensions` | v1 | Experimental provider-neutral capability vocabulary; generic registry remains internal and unexported |
 
 `repositoryIndex` v1 is a mandatory provider-neutral discovery capability for
 Git repositories. ForgeLoop currently implements it with a managed, pinned
@@ -223,6 +234,40 @@ instructions. `protocol-info` may advertise the capability, but advisory
 recall remains a programmatic Integration API operation; there is no stock
 `context-recall` CLI command.
 
+<a id="FL-PROVIDER-001"></a> **FL-PROVIDER-001 — `providerExtensions` MUST remain provider-neutral and experimental and MUST NOT imply a public generic provider registry API.**
+
+<a id="FL-PROVIDER-002"></a> **FL-PROVIDER-002 — Every advertised provider kind MUST deny lifecycle, completion, and evidence authority.**
+
+<a id="FL-PROVIDER-003"></a> **FL-PROVIDER-003 — Provider results MUST cross a strict JSON snapshot boundary before consumer use.**
+
+<a id="FL-PROVIDER-004"></a> **FL-PROVIDER-004 — The generic provider registry MUST remain absent from public package subpath exports.**
+
+`providerExtensions` v1 is provider-neutral and experimental. It advertises
+five provider kinds, strict JSON result normalization, cooperative cancellation,
+and false lifecycle, completion, evidence, and auto-install authority. This
+capability advertisement does not imply a generic public provider registration
+API or a supported `./providers` package subpath. Protocol version remains 1,
+Schema version remains 1, and Integration API version remains 1.
+
+The dedicated `browserVerificationProviders` runtime-context option is a
+separate explicit Integration API boundary. It is host-injected, provider
+neutral, lazy, and inert during context construction. `runBrowserVerification`
+is the only public operation; it does not run from lifecycle commands and does
+not persist observations. ForgeLoop owns the shared deadline, cooperative
+cancellation, strict result snapshot, exact origin/redirect validation, and
+overall assertion-status derivation. Browser observations cannot directly
+create evidence, completion authority, claims, receipts, or next actions. The
+origin allowlist is not a network sandbox and no browser vendor is canonical.
+
+The dedicated `securityReviewProviders` runtime-context option is another
+explicit, host-injected Integration API boundary. `runSecurityReview` is
+lazy, inert during context construction, and observation-only: it does not
+install or discover scanners, mutate lifecycle artifacts, create evidence,
+authorize completion, or issue commands. ForgeLoop bounds and freezes the
+request, shares one deadline and cooperative abort signal across factory and
+review, and normalizes the result into a strict immutable observation. Findings
+must not be treated as canonical evidence or lifecycle authority.
+
 A consumer that understands `canonicalHandoffs` v1 but not v2 may disable the
 handoff-specific UI while keeping Protocol v1 core functionality available.
 Consumers must feature-detect the capability family and must not mark the
@@ -394,6 +439,12 @@ only a compatibility alias and has identical caller-acknowledgement semantics.
 a trusted grant reference through a boundary the active actor cannot mint or
 replace. The standalone CLI does not expose such a self-attestation option.
 
+Explicit active-task abandonment is a distinct caller-acknowledged operation:
+`task-abandon --task <id> --acknowledge-abandonment` releases validated claims
+through the same canonical ownership resolver, project/task serialization, and
+append-only recovery history. It does not change the phase or create completion,
+publication, or host authority. `clear-state` is not an abandonment substitute.
+
 Claim ownership is a validated relationship, not an artifact preference.
 <a id="FL-CLAIM-001"></a> **FL-CLAIM-001 — Every harness MUST consume the canonical claim-state resolver**
 over the descriptor, work state, recovery artifact, and complete validated
@@ -488,8 +539,10 @@ installing a package.
 
 The installed loop directs the active actor to inspect native model and harness
 capabilities. When a task requires a missing capability (e.g. multimodal vision),
-the actor may install the smallest task-scoped capability (such as `Qwen-MM-Plugins`)
-through native mechanisms or upstream installers, then verify it before use.
+a host or operator may provision the smallest task-scoped capability (such as
+`Qwen-MM-Plugins`) only when installation authority has been explicitly
+granted. Use native mechanisms or upstream installers, then verify it before
+use. Without that authority, keep it unavailable and report the limitation.
 
 API credentials, system packages, and unrelated environment changes remain
 separately gated.

package/QUALITY_SCORECARD.md

@@ -95,6 +95,7 @@ are both present:
 | --- | --- | --- |
 | Routing | `src/core/router.js`, route schemas, stable reason codes, and exclusions | `tests/router.test.js`, `tests/fixtures/routes/` |
 | Flutter project detection and routing | `src/core/project-detection.js`, `src/core/router.js`, `src/config/guides.json`, and scoped manifest evidence | `tests/project-detection.test.js`, `tests/guide-registry.test.js`, `tests/router.test.js` |
+| Rust project detection and routing | `src/core/project-detection.js`, `src/core/rust-project.js`, `src/core/router.js`, `src/config/guides.json`, and scoped Cargo evidence | `tests/rust-project-detection.test.js`, `tests/guide-registry.test.js`, `tests/router.test.js` |
 | Observability | `src/core/receipt.js`, `src/core/inspect.js`, `src/core/evidence.js`, and schema health | `tests/observability.test.js`, `tests/receipt-semantics.test.js`, `tests/schema-health.test.js` |
 | Resume/checkpoint | `src/core/work-state.js`, `EXECUTION_STATE.md`, shared loaded-state classifier, contract/artifact classifiers, and atomic writes | `tests/work-state.test.js`, `tests/checkpoint-freshness.test.js`, status, validate-state, and validate-protocol tests |
 | Delegation | `src/core/delegation.js`, delegation-set validator, and `DELEGATION_PROTOCOL.md` | `tests/delegation.test.js`, `tests/delegation-set.test.js` |

package/README.md

@@ -1,38 +1,37 @@
 # 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.svg" alt="ForgeLoop Architecture" 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)
 [![Dependency review](https://github.com/cassiomc1/forgeloop/actions/workflows/dependency-review.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/dependency-review.yml)
-[![Docs quality](https://github.com/cassiomc1/forgeloop/actions/workflows/docs-quality.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/docs-quality.yml)
 [![ForgeLoop audit](https://github.com/cassiomc1/forgeloop/actions/workflows/forgeloop-audit.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/forgeloop-audit.yml)
 [![Publish npm package](https://github.com/cassiomc1/forgeloop/actions/workflows/npm-publish.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/npm-publish.yml)
 [![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 portable, vendor-neutral protocol for AI-assisted development
-and developer workflows. It turns outcomes into contracts, deterministic routing,
-resumable state, evidence-backed verification, recovery, cross-harness
-continuity, managed repository-wide discovery, and validator-backed completion.
-It is a protocol CLI, not an agent or LLM runtime, framework, or graph orchestrator.
+ForgeLoop is the deterministic governor for AI-assisted engineering. Jev is the
+mandatory bounded System One semantic input; the host coding model is System Two
+implementation. ForgeLoop alone owns lifecycle, claims, gates, evidence,
+completion, recovery, and publication truth.
 
-The operational sources are indexed in [`DOCS_INDEX.md`](./DOCS_INDEX.md).
-[`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) is the canonical process;
-[`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) defines capability
-levels and discovery; [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md) stores
-durable project facts; and [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) selects only
-relevant guides.
+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.
 
 ## Where should I start?
 
 - **New to ForgeLoop** → [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md)
-- **Inspect a real ForgeLoop execution** → [`poc/README.md`](./poc/README.md)
+- **Inspect a real ForgeLoop execution** → [repository PoC](https://github.com/cassiomc1/forgeloop/blob/main/poc/README.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)
@@ -45,13 +44,13 @@ relevant guides.
 
 ## Real execution proof
 
-Public [execution PoC](./poc/README.md) covers workload, protocol
+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.
 
-- [Canonical technical audit](./poc/reports/poc-20260826-real-execution-technical-audit-v2.md)
-- [Evidence package](./poc/evidence/poc-20260826-real-execution/)
+- [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/)
 
 ## Catalog
 
@@ -68,13 +67,24 @@ validator-backed `COMPLETE / VALID` and preserves a later
 | Web games | [`ENG/games-code-design-web-eng.md`](./ENG/games-code-design-web-eng.md) |
 | Documentation quality | [`ENG/documentation-quality-eng.md`](./ENG/documentation-quality-eng.md) |
 | Flutter | [guide](./ENG/flutter-development-eng.md) |
+| .NET and ASP.NET Core | [guide](./ENG/dotnet-aspnetcore-development-eng.md) |
+| Node.js | [guide](./ENG/nodejs-backend-development-eng.md) |
+| Rust | [guide](./ENG/rust-development-eng.md) |
+| C | [guide](./ENG/c-development-eng.md) |
+| C++ | [guide](./ENG/cpp-development-eng.md) |
+| Java | [guide](./ENG/java-development-eng.md) |
+| SQL | [guide](./ENG/sql-development-eng.md) |
+| Go | [guide](./ENG/go-development-eng.md) |
+| TypeScript | [guide](./ENG/typescript-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) |
 
-Guide metadata is validator-checked.
-
-Parsed `pubspec.yaml` with `dependencies.flutter.sdk: flutter` selects
-Flutter; mentions, lockfiles, hosted packages, and unrelated monorepos do not.
-See [guide](./ENG/flutter-development-eng.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.
 
 ## Quickstart
 
@@ -105,20 +115,18 @@ 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
@@ -144,7 +152,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
 
@@ -170,8 +180,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
 
@@ -355,20 +365,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
@@ -387,6 +397,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:
@@ -423,12 +439,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).
@@ -441,8 +465,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),
@@ -458,9 +480,13 @@ and [visual review](./docs/diagrams/reviews/forgeloop-code-attestation-flow.revi
 show exact content binding, optional signing, and separate revision-range
 coverage.
 
-Text-only fallback: discovery creates the contract and route; parsed
-`dependencies.flutter.sdk: flutter` selects Flutter for that root; routing is
-not verification/completion evidence. Gates and
+Text-only fallback: discovery creates the contract and route; parsed project
+manifests/build metadata select the corresponding language specialist; owned
+SQL migrations overlay their host project; parsed
+`dependencies.flutter.sdk: flutter` selects Flutter for that root; a supported
+SDK-style manifest selects .NET; parsed `[package]` or `[workspace]` in
+`Cargo.toml` selects Rust for that root; ASP.NET Core and ABP remain .NET
+overlays. Routing is not verification/completion evidence. Gates and
 `PREFLIGHT_READY` authorize execution; verification creates
 structured evidence; failures enter diagnosis and correction; review precedes
 validator-backed completion. Drift reopens verification, and migration keeps
@@ -504,16 +530,16 @@ it must not infer current ownership from `task.json` or `recovery.json` alone.
 
 ## Security and dependency boundary
 
-The runtime uses Node built-ins only and does not install agents, providers,
-plugins, remote services, or telemetry. Target paths and symlinks are bounded;
-JSON is size/depth limited; manifests, schemas, receipts, and secret-like
-values are checked; and install-capable verification requires trusted host
-authority. See [`THREAT_MODEL.md`](./THREAT_MODEL.md) for the full inventory.
+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).
 
-Development tooling stays separate from runtime dependencies. The policy allows
-c8, ESLint, TypeScript, and YAML as development dependencies;
-`npm run dependency:policy` rejects runtime or unapproved dependencies. Archify
-is vendored at `vendor/archify/v2.15.0/` rather than installed as a package.
+c8, ESLint, TypeScript, and YAML remain development-only. The dependency
+policy rejects unapproved runtime or development dependencies. Archify is
+vendored at `vendor/archify/v2.15.0/` rather than installed as a package.
 
 To report vulnerabilities or contribute changes, see
 [`SECURITY.md`](./SECURITY.md) and [`CONTRIBUTING.md`](./CONTRIBUTING.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

@@ -1,8 +1,9 @@
 # Third-Party Notices
 
 This file records provenance and reuse boundaries for the external URLs cited
-by the README and guides. A citation is a reference, not a declaration that a
-resource is a dependency, bundled material, or available for reuse.
+by the README and guides. A citation is a reference, not by itself a
+declaration that a resource is a dependency, bundled material, or available
+for reuse.
 
 ## Collection license
 
@@ -100,11 +101,12 @@ dependencies, version, and distribution conditions before adoption.
 ### Runtime and validator boundary
 
 The distributed CLI and repository validators use Node.js and Python standard
-libraries plus the JSON Schema documents shipped in this repository. No
-third-party runtime package, agent, provider, plugin, remote trace service, or
-model is bundled or installed by `ForgeLoop`. A future host that adds one of
-those capabilities must review its own license, dependency tree, credentials,
-network behavior, and distribution terms separately.
+libraries plus the JSON Schema documents shipped in this repository. The core
+CLI has one approved runtime package, `smol-toml`, for structural Cargo
+manifest parsing; it is not used as an agent, provider, plugin, remote trace
+service, or model. Every future runtime capability must review its own license,
+dependency tree, credentials, network behavior, and distribution terms
+separately.
 
 ## Visual, gradient, and gallery references
 
@@ -213,6 +215,16 @@ or make its prescriptive examples universal.
 
 ## Runtime dependencies with upstream notices
 
+### smol-toml 1.8.0
+
+- Project/source: [squirrelchat/smol-toml](https://github.com/squirrelchat/smol-toml).
+- License declared by the upstream package: BSD-3-Clause.
+- Use in this collection: bounded structural parsing of Rust `Cargo.toml`
+  manifests without executing Cargo or evaluating project code.
+- Boundary: the exact version is pinned in `package.json` and
+  `package-lock.json`; the dependency has no role in routing authority beyond
+  the parser result and is not exposed as a public ForgeLoop integration.
+
 ### Microsoft tgrep
 
 - Project: [microsoft/tgrep](https://github.com/microsoft/tgrep).

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.