@cassiomc1/forgeloop 1.13.0 → 1.14.0

package/docs/OPENSRC_ADAPTER.md

@@ -0,0 +1,241 @@
+# OpenSrc Advisory Context Adapter
+
+## Status
+
+Optional, host-injected, advisory-only. OpenSrc is an external
+host-provisioned executable ([vercel-labs/opensrc](https://github.com/vercel-labs/opensrc),
+Apache-2.0); ForgeLoop never installs, discovers, or invokes it automatically.
+
+## Purpose
+
+Give a trusted host a bounded way to recall external package/repository
+source-code snippets (npm, PyPI, crates.io, GitHub, GitLab, Bitbucket) as
+ForgeLoop advisory context through the existing `advisoryContextProviders`
+Integration API boundary.
+
+## Architecture
+
+```text
+host / coding harness
+        ↓
+createOpenSrcAdvisoryContextProvider(...)
+        ↓
+createForgeLoopContext({ advisoryContextProviders: { opensrc } })
+        ↓
+recallAdvisoryContext(...)
+        ↓
+<absolute-opensrc> --version (qualified every recall)
+        ↓
+<absolute-opensrc> path <source> --cwd <projectRoot> (one source per call)
+        ↓
+canonical realpath containment inside OPENSRC_HOME
+        ↓
+bounded deterministic Node.js search (ForgeLoop-owned)
+        ↓
+normalized advisory items
+        ↓
+NON_EVIDENCE_ADVISORY_CONTEXT
+```
+
+OpenSrc owns source acquisition, version-aware resolution, and its own cache.
+ForgeLoop owns snippet selection, normalization, and the advisory trust
+boundary. No `rg`, `grep`, embeddings, or network search are used by ForgeLoop.
+
+## Prerequisites
+
+- An OpenSrc executable provisioned by the host (ForgeLoop does not install it).
+- A host-qualified exact expected version (for example `0.7.3`).
+- A dedicated absolute cache root outside the project, passed as `OPENSRC_HOME`.
+- An explicit allowlist of source specs (at most 8).
+
+## Host Configuration
+
+```javascript
+import {
+  createForgeLoopContext,
+  createOpenSrcAdvisoryContextProvider,
+  recallAdvisoryContext,
+} from "@cassiomc1/forgeloop/integration";
+
+const opensrc = createOpenSrcAdvisoryContextProvider({
+  executablePath: "/absolute/path/to/opensrc",
+  expectedVersion: "<host-qualified-version>",
+  cacheRoot: "/absolute/path/to/opensrc-cache",
+  sources: ["zod", "vercel/next.js"],
+});
+
+const runtimeContext = createForgeLoopContext({
+  advisoryContextProviders: {
+    opensrc,
+  },
+});
+
+const context = await recallAdvisoryContext({
+  target: "/absolute/project",
+  taskId: "task-001",
+  providerName: "opensrc",
+  query: "parse error handling",
+  runtimeContext,
+});
+```
+
+Construction is inert: it validates configuration only and never spawns,
+reads source, touches the network, populates the cache, or mutates ForgeLoop
+state.
+
+## Executable Qualification
+
+Before source resolution on every recall, the adapter runs
+`<absolute-opensrc> --version` with `shell: false`, bounded output, and a
+shared deadline, then requires `actualVersion === expectedVersion` exactly.
+No semver ranges and no newer-version tolerance. Mismatch fails closed.
+
+## Source Allowlist
+
+Only configured `sources` entries are resolved, one per `opensrc path`
+invocation. Specs must be non-empty, bounded (256 chars), free of control or
+whitespace characters, must not begin with `-`, and must not contain shell
+metacharacters. Documented forms include bare npm names (with `@scope/` and
+`@version` pins), `pypi:`, `crates:` (plus `pip:`, `python:`, `cargo:`,
+`rust:` aliases), `owner/repo`, URLs, and `gitlab:` / `bitbucket:` specs.
+Automatic dependency enumeration is out of scope.
+
+## Cache Behavior
+
+`OPENSRC_HOME` is set to the configured `cacheRoot` for every OpenSrc child
+process. The cache root and the project root must be fully disjoint: neither
+may equal or contain the other, and the cache must not sit inside
+`.forgeloop`. Each relationship is checked both lexically and canonically
+(realpath), so symlinked prefixes cannot hide an overlap.
+Each printed path must canonicalize inside the cache root, exist, be a
+directory, and survive symlink-escape checks before any search runs.
+
+## Network Behavior
+
+`opensrc path` may contact registries or remotes and shallow-clone source on
+cache miss; later recalls may reuse the OpenSrc cache. This recall path is
+protocol-state side-effect-free: ForgeLoop persists no advisory result,
+writes no lifecycle state, and never auto-recalls. OpenSrc itself persists
+cache data under `OPENSRC_HOME`; that is upstream behavior, not ForgeLoop
+state.
+
+## Recall Example
+
+See Host Configuration. Only `--version` and `path` are ever invoked; `fetch`,
+`clean`, `remove`, and `rm` are never called by this adapter.
+
+## Result Shape
+
+```javascript
+{
+  title: "zod — src/types.ts",
+  summary: "L120-L126 | <bounded single-line snippet>",
+  sourceRef: "opensrc:zod:src/types.ts#L120-L126"
+}
+```
+
+Summaries are flattened to one portable line because the core advisory
+contract rejects control characters. Absolute cache paths, home directories,
+stderr, environment, credentials, and cache metadata are never emitted. The
+core service then applies `authority: ADVISORY`, `evidenceAuthority: NONE`,
+`actionability: NON_EXECUTABLE`, `trustRole: NON_EVIDENCE_ADVISORY_CONTEXT`,
+and `persisted: false`, plus item fingerprints and deep freezing.
+
+## Trust Boundary
+
+Snippets are inert source text. They satisfy no verification requirement,
+terminal requirement, gate, receipt, attestation, or run-check provenance.
+Source content is never executed, even when it contains instruction-like
+text. Provider output never advances phases, selects next actions, releases
+claims, or authorizes durable actions.
+
+## Security
+
+Threats and mitigations are tracked in `THREAT_MODEL.md` (OpenSrc rows):
+binary substitution and version drift (exact lazy qualification), malicious
+stdout paths and cache/symlink escapes (realpath containment), prompt
+injection in source (inert bounded text, non-executable trust role),
+credential leakage (no raw stderr/env/absolute-path emission), unbounded
+trees and binary ingestion (sorted traversal, size/count/byte budgets, binary
+skip), network/cache side effects (explicit host-owned `OPENSRC_HOME`,
+documented fetch-on-miss), private-repository credentials (host-owned env,
+never persisted or logged), timeouts and output overflow (shared deadline,
+64 KiB ceilings, SIGTERM/SIGKILL escalation).
+
+## Limits
+
+- Sources: at most 8 configured; one `path` call each.
+- Files read per source: 2,000; examined entries per source: 5,000
+  (skipped, oversized, and binary entries count toward traversal, never
+  bypass it).
+- Per-file: 256 KiB; total reads: 8 MiB per advisory recall across all
+  configured sources through one shared budget.
+- Matches per source: 32; snippet window: 7 lines.
+- Process stdout/stderr: 64 KiB each; kill grace: 250 ms.
+- One shared recall deadline spans version qualification, path resolution,
+  traversal, reads, matching, and normalization.
+- Ranking: exact full-query match, then token overlap, then source order,
+  relative path, and line number. Repeated runs over unchanged fixtures are
+  byte-identical, including identical stopping points under budget pressure.
+
+## Private Repositories
+
+Private sources work only through host-owned configuration (environment,
+authenticated OpenSrc cache). ForgeLoop never discovers, persists, logs, or
+returns credentials; errors never echo secret-bearing values.
+
+## Credentials Ownership
+
+Credentials belong to the host. They travel only through host-supplied process
+configuration, never through ForgeLoop artifacts, and never into advisory
+output.
+
+## No Auto-Install
+
+ForgeLoop never runs package installs, `npx`, `curl | sh`, or equivalents for
+OpenSrc. An unavailable binary maps to the standard advisory-provider
+unavailable semantics; the host provisions OpenSrc explicitly.
+
+## No PATH Discovery
+
+The executable must be absolute. `which`, `where`, `command -v`, and PATH
+resolution are never used.
+
+## No Evidence Authority
+
+See Trust Boundary. Behavioral claims still require canonical ForgeLoop
+verification with ForgeLoop-owned provenance.
+
+## No Lifecycle Authority
+
+See Trust Boundary. Advisory recall is never triggered by `next`,
+`preflight`, verification, `complete`, task creation, task discovery, or
+Agent Skill loading.
+
+## Troubleshooting
+
+| Symptom | Meaning | Action |
+| --- | --- | --- |
+| `E_ADVISORY_CONTEXT_PROVIDER_INVALID` on recall | Bad config, version mismatch, cache inside project, or malformed version output | Check absolute paths, exact version, `OPENSRC_HOME` placement |
+| `E_ADVISORY_CONTEXT_PROVIDER_UNAVAILABLE` | Missing binary or spawn failure | Provision the host executable; ForgeLoop will not install it |
+| `E_ADVISORY_CONTEXT_RESULT_INVALID` | Empty/multi-line/relative/outside-cache path, non-directory, or bad exit | Inspect host cache and source spec |
+| `E_ADVISORY_CONTEXT_TIMEOUT` | Shared deadline expired | Retry with a larger recall `timeoutMs` within core ceilings |
+| `E_ADVISORY_CONTEXT_OUTPUT_LIMIT` | 64 KiB process ceiling or item budget exceeded | Narrow sources or query |
+
+## Package Behavior
+
+`src/adapters/opensrc/**`, this guide, and the integration declarations ship
+in the core npm tarball. No OpenSrc binary, cache, fixture, credential, or
+source snapshot ships. No new runtime dependency and no new package subpath
+are added; `providerExtensions.publicRegistryApi` and
+`providerExtensions.packageSubpathExported` remain false.
+
+## Compatibility
+
+- Protocol v1, schema v1, Integration API v1 unchanged.
+- `advisoryContextProviders` v1 and `providerExtensions` v1 unchanged; the
+  `ADVISORY_CONTEXT` provider kind covers this adapter.
+- Requires Node.js 20+.
+- Upstream behaviors referenced: `opensrc path <source> [--cwd]`,
+  `OPENSRC_HOME` override, fetch-on-miss, `opensrc 0.7.3` observed at
+  authoring time (never hardcoded into behavior).

package/docs/PACKAGE_CONTENTS.md

@@ -11,12 +11,27 @@ part of the consumer tarball.
 
 The package exposes the `forgeloop` executable from `src/cli.js` and the
 `@cassiomc1/forgeloop/integration` subpath from `src/integration.js`, with its
-declaration file. The package has the approved exact `smol-toml` runtime
-dependency for bounded Cargo manifest parsing and requires Node.js 20 or
-newer.
+declaration file. The package has the approved exact `@typesafe-ai/sdk`
+dependency for the pinned semantic decision plane and `smol-toml` for bounded
+Cargo manifest parsing. It requires Node.js 20 or newer.
 
 ## Included files
 
+The public package includes the Jev decision-plane documentation and bounded
+diagnostic scripts:
+
+- `docs/JEV_BENCHMARKS.md`
+- `docs/MODEL_ROUTING.md`
+- `docs/SEMANTIC_DECISION_PLANE.md`
+- `docs/TEST_INTELLIGENCE.md`
+- `docs/TEST_PRUNING.md`
+- `scripts/jev-smoke.mjs`
+- `scripts/benchmark-jev.mjs`
+- `scripts/benchmark-test-intelligence.mjs`
+- `schemas/context-plan.schema.json`
+- `schemas/semantic-decision.schema.json`
+- `schemas/test-utility.schema.json`
+
 The published tarball includes the following consumer-facing groups:
 
 - **Runtime and protocol:** every maintained JavaScript module under `src/`,
@@ -53,8 +68,17 @@ The published tarball includes the following consumer-facing groups:
   Repository Index, Persistent Search Transport, troubleshooting, release,
   package-boundary, and related reference pages, together with the
   machine-readable documentation and protocol indexes and `CONTRIBUTING.md`.
-  The advisory-context and Ripwire adapter guides ship with the corresponding
-  public integration surface.
+   The advisory-context, Ripwire, OpenSrc, Agent Browser, and Audit UX guides ship with
+   the corresponding public integration surface.
+   Provider architecture, provider reference, and Security Review provider
+   documentation are also packaged.
+   The generated portable ForgeLoop Agent Skill and `docs/AGENT_SKILL.md` are
+   packaged as instruction/documentation content, not runtime authority.
+  Provider implementation modules ship under `src/`, but packaged source file
+  does not mean a supported public import path; the generic `./providers`
+  subpath remains unexported.
+  The lifecycle recovery surface includes the explicit `task-abandon` command;
+  it releases validated claims without asserting completion or publication.
   The typed diagram sources, generated HTML/SVG/receipt artifacts, and
   source-bound review records under `docs/diagrams/` are included together so
   the packaged documentation keeps its visual provenance.
@@ -67,6 +91,8 @@ The published tarball includes the following consumer-facing groups:
 The tarball intentionally omits repository-only material:
 
 - tests, conformance fixtures, coverage output, and secret-scanning helpers;
+  Harness-specific Agent Skill installation directories and Skill caches are
+  not packaged.
 - local `.forgeloop` state, task ledgers, locks, transactions, and execution
   receipts (the `.forgeloop/forgeloop.gitignore` template is the sole
   exception);
@@ -77,9 +103,10 @@ The tarball intentionally omits repository-only material:
   the consumer adapter surface;
 - historical release plans and retired MCP adapter sources; the MCP adapter
   is published as its own package;
-- the repository README hero PNG, which is a GitHub-only asset. The packaged
-  README remains intentionally text-first around that relative repository
-  image reference.
+- the repository-only README hero assets
+  `docs/assets/forgeloop-architecture.svg` and
+  `docs/assets/forgeloop-lifecycle-animated.svg`. They are referenced by the
+  repository README and are intentionally outside the core tarball.
 - the execution PoC, its audit, and its evidence package. Packaged README and
   index links to this repository-only material use GitHub URLs so they remain
   truthful for npm consumers.

package/docs/PROVIDERS.md

@@ -0,0 +1,126 @@
+# Provider Extension Reference
+
+## Status
+
+`providerExtensions` v1 is provider-neutral and experimental. This reference
+describes the architecture vocabulary and maintainer expectations. It does
+not document a supported import from `@cassiomc1/forgeloop/providers`.
+
+## Capability Discovery
+
+Run `node src/cli.js protocol-info --json` and inspect
+`features.providerExtensions`. The advertised capability includes the version,
+provider kinds, strict result boundary, cooperative cancellation, and explicit
+authority restrictions.
+
+## Provider Kinds
+
+- `ADVISORY_CONTEXT`: optional context, never executable or canonical.
+- `VERIFICATION_EXECUTION`: bounded execution observations, never completion truth.
+- `BROWSER_VERIFICATION`: browser observations with no canonical vendor.
+- `SECURITY_REVIEW`: bounded security observations pending any future explicit gate.
+- `PRESENTATION`: read-only rendering that cannot mutate protocol state.
+
+The canonical list is exported internally as `PROVIDER_KINDS`; public metadata
+is synchronized from that source and must not duplicate its strings.
+
+Concrete `ADVISORY_CONTEXT` adapters (Ripwire, OpenSrc) plug into the
+dedicated advisory-context Integration API (`createForgeLoopContext` with
+`advisoryContextProviders`, plus `recallAdvisoryContext`); they are not part
+of the generic internal provider registry described here.
+
+Browser verification is registered only through the runtime context option
+`browserVerificationProviders` and is invoked explicitly with
+`runBrowserVerification`. Registration is lazy and inert: it does not launch a
+browser, perform network I/O, or mutate protocol state. Its provider-neutral
+input includes task/target/requirement binding, a shared abort signal, and the
+remaining timeout. ForgeLoop validates redirects and derives overall status;
+provider output is observation only and cannot satisfy evidence or completion.
+
+The optional `agent-browser` adapter is registered through the same boundary
+with `createAgentBrowserVerificationProvider({ executablePath, expectedVersion })`.
+The executable is host-owned and absolute; no package dependency or automatic
+installation is added. The adapter returns browser observations only.
+
+The optional `vercel-labs/emulate` adapter is host-injected through
+`createEmulatedServicesProvider({ executablePath, expectedVersion })`. The
+host must provide an absolute regular executable and explicitly choose the
+services and loopback port range. ForgeLoop does not install the tool, search
+`PATH`, invoke a shell, persist service state in the target project, or treat
+service output as lifecycle, evidence, installation, or completion authority.
+The supported host tool is pinned to `0.11.2`; invocation is lazy and inert
+until `provider.start(...)` is called. Each bounded operation verifies the
+qualified version, starts with argv-only execution, observes loopback
+readiness, returns a detached observation, and cleans up its temporary state
+and child process.
+
+Security review is registered through `securityReviewProviders` and invoked
+explicitly with `runSecurityReview`. Registration is lazy and inert. The
+request accepts bounded scope, relative paths, categories, requirements, and a
+revision binding; factory resolution and review share one deadline and abort
+signal. Results are strict immutable observations with bounded findings and
+summary counts. They cannot establish evidence, lifecycle, completion,
+ownership, claims, commands, installation, or transaction authority. See
+[`SECURITY_REVIEW.md`](./SECURITY_REVIEW.md) for the complete contract.
+
+## Common Contract
+
+Providers are identified by an ID and kind, may resolve lazily, and receive a
+bounded invocation context. Results are detached, deeply frozen strict JSON
+snapshots. A provider may return an observation, never lifecycle state,
+completion truth, canonical evidence, executable instructions, or installation
+authority.
+
+## Invocation Context
+
+The context includes a shared `AbortSignal`, the provider ID, and the remaining
+timeout budget. Factories and operations consume the same deadline. Providers
+must observe abort and clean up owned resources.
+
+## Limits
+
+Invocation uses one shared timeout budget. Input and output are bounded by byte,
+depth, and node limits. Synchronous JavaScript cannot be preempted; resource
+owners remain responsible for cooperative cleanup after abort.
+
+## Error Codes
+
+Malformed providers, unavailable providers, timeouts, invalid snapshots,
+payload limits, authority escalation, and execution failures use the internal
+provider error vocabulary. Provider exceptions are normalized so a provider
+cannot spoof a ForgeLoop error code.
+
+## Trust Rules
+
+Treat provider output as untrusted input. Pass it through ForgeLoop-owned
+validation before any evidence or consumer use. Do not execute provider text,
+interpret it as a next action, or treat provider identity as a trust grant.
+
+## Maturity
+
+The public capability vocabulary is versioned at v1 but remains experimental.
+The generic registry implementation is internal and experimental. No provider
+is auto-installed or discovered by the lifecycle, and no provider CLI exists.
+
+## Internal vs Public Surfaces
+
+The public surfaces are the protocol-info capability and these documentation
+pages. The JavaScript registry under `src/providers/` ships as implementation
+source but is not a supported package subpath or public registration contract.
+
+## Future Adapter Structure
+
+An adapter proposal must specify its provider kind, bounded input/output,
+timeout and cancellation behavior, error mapping, authority restrictions,
+ForgeLoop validation boundary, tests, and documentation owner. Dedicated
+Integration API capabilities remain separate from this generic vocabulary.
+
+## Testing Checklist
+
+- Capability metadata is synchronized with `PROVIDER_KINDS`.
+- Every provider kind denies lifecycle, completion, and evidence authority.
+- Strict JSON rejects accessors, proxies, custom objects, cycles, and oversized payloads.
+- Shared timeout and cooperative cancellation are tested.
+- Provider exceptions cannot spoof ForgeLoop error codes.
+- `protocol-info --json` advertises v1 without claiming a public registry API.
+- The package does not export `./providers`.

package/docs/PROVIDER_ARCHITECTURE.md

@@ -0,0 +1,199 @@
+# Provider Extension Architecture
+
+## Status
+
+Provider extensions are a provider-neutral, experimental capability family in
+Protocol v1. The capability vocabulary is public and versioned; the generic
+provider registry is internal and is not a supported package API.
+
+## Scope
+
+This document explains the common boundary around provider observations. It
+does not add generic provider registration to `createForgeLoopContext()`; the
+dedicated runtime-only `browserVerificationProviders` and
+`securityReviewProviders` registrations are the exceptions documented by
+their dedicated contracts. They do not add CLI
+provider commands, automatic installation, lifecycle authority, or completion
+authority.
+
+## Why ForgeLoop Uses Providers
+
+Providers allow a host to connect bounded observations or execution services to
+ForgeLoop without making a vendor, model, browser, scanner, or presentation
+tool canonical. A provider result is an input to ForgeLoop-owned validation,
+not a replacement for it.
+
+## Provider-Neutral Design
+
+The public `providerExtensions` capability advertises architecture and
+compatibility semantics only. It is provider-neutral, experimental, lazy at
+the host boundary, and deliberately separate from the existing dedicated
+`advisoryContextProviders` Integration API capability.
+
+The generic registry is currently an internal implementation module. It is
+not exported as `@cassiomc1/forgeloop/providers`, and capability advertising
+does not imply a public registration or installation API.
+
+## Provider Kinds
+
+The five kinds are derived from the canonical `PROVIDER_KINDS` source:
+
+| Kind | Contract |
+| --- | --- |
+| `ADVISORY_CONTEXT` | Optional, non-authoritative context. It is never canonical state, evidence, completion authority, or executable instruction. |
+| `VERIFICATION_EXECUTION` | A bounded execution boundary that may produce observations, but never completion truth. |
+| `BROWSER_VERIFICATION` | Browser-driven observation and assertion collection. No vendor is canonical. |
+| `SECURITY_REVIEW` | Bounded security findings, observation-oriented unless a future explicit gate contract exists. |
+| `PRESENTATION` | Read-only presentation or rendering. It must never mutate protocol state. |
+
+Every kind denies lifecycle, completion, and evidence authority. Providers do
+not acquire installation authority.
+
+### Presentation vocabulary and Audit UX
+
+`PRESENTATION` remains a provider-kind vocabulary slot for future bounded
+renderers; it does not require a concrete provider in the completed roadmap.
+The current Audit UX need is already served by `task/audit-view`, a canonical
+read-only Integration API projection composed from ForgeLoop-owned resolvers.
+Audit UX is not a provider, does not register through the provider boundary,
+and cannot mutate protocol state, establish evidence, release claims, or
+authorize completion.
+
+## Invocation Lifecycle
+
+```text
+HOST
+ │
+ ▼
+provider selection
+ │
+ ▼
+registry lookup
+ │
+ ▼
+lazy factory resolution
+ │
+ ▼
+provider validation
+ │
+ ▼
+bounded invocation
+ │
+ ▼
+strict JSON normalization
+ │
+ ▼
+authority validation
+ │
+ ▼
+immutable observation
+  │
+  ▼
+  ForgeLoop consumer
+```
+
+The result boundary is:
+
+```text
+provider result
+      ↓
+normalized observation
+      ↓
+ForgeLoop-owned validation
+      ↓
+optional canonical evidence/use
+```
+
+A provider must never bypass ForgeLoop-owned validation.
+
+Browser verification is an explicit Integration API operation, not a generic
+provider command. Its registry is inert during context construction, its
+factory and verify call share one deadline and cooperative `AbortSignal`, and
+its final status is derived by ForgeLoop from the requested assertion results.
+The origin allowlist validates observations but is not a network sandbox.
+
+Security review is likewise an explicit Integration API operation through
+`runSecurityReview`. Its host-injected registry is inert during context
+construction. Requests and results are bounded strict snapshots, and provider
+findings remain observation-only, non-evidence, and non-executable.
+
+## Trust Boundary
+
+Provider output is untrusted input. It cannot establish lifecycle state,
+completion truth, canonical evidence, next-action authority, or installation
+authority. Provider identity and availability are descriptive and must not be
+treated as proof of executable identity or trust.
+
+## Strict JSON Snapshot Boundary
+
+Provider input and output use detached, deeply frozen snapshots. Allowed values
+are `null`, booleans, finite numbers, strings, arrays, and plain objects.
+
+The boundary rejects `undefined`, functions, symbols, bigints, non-finite
+numbers, dates, maps, sets, promises, proxies, custom classes, accessors,
+cycles, sparse or extended arrays, and hidden non-enumerable payload data.
+Provider payloads are bounded by byte, depth, and node limits.
+
+## Timeout and Cancellation
+
+Factory resolution and operation execution share one timeout budget and one
+invocation context. The `AbortSignal` is propagated and cancellation is
+cooperative. A late factory resolution cannot start an operation after the
+deadline. Synchronous JavaScript cannot be preempted by a timer, so providers
+that own subprocesses, browsers, requests, or sockets must clean them up when
+the signal is aborted.
+
+## Error Normalization
+
+Provider exceptions are normalized to ForgeLoop provider execution failures;
+provider-supplied ForgeLoop-shaped error codes are not trusted. Validation and
+timeout failures are generated outside the provider call boundary.
+
+## Authority Restrictions
+
+The following public capability fields remain false: `autoInstall`,
+`lifecycleAuthority`, `completionAuthority`, and `evidenceAuthority`.
+Providers observe. ForgeLoop validates, owns lifecycle transitions, and decides
+whether an observation can contribute to canonical evidence.
+
+## Evidence Conversion Boundary
+
+An observation can become usable evidence only through the relevant
+ForgeLoop-owned validation and evidence contract. Provider output is never
+itself a completion claim or canonical evidence record.
+
+## Internal vs Public Surfaces
+
+Public and versioned:
+
+- `protocol-info --json` and `features.providerExtensions`.
+- This architecture document and [`PROVIDERS.md`](./PROVIDERS.md).
+
+Internal and experimental:
+
+- `src/providers/index.js` and the generic registry implementation.
+- Provider capability implementation details not included in the public
+  Integration API contract.
+
+`@cassiomc1/forgeloop/providers` remains unexported.
+
+## Compatibility
+
+Protocol version, Schema version, and Integration API version remain `1`.
+`providerExtensions` is capability version `1`; consumers must feature-detect
+it and may continue using the core protocol when they do not understand it.
+
+## Future Provider Adapters
+
+Future adapters may implement a provider kind only after a provider-neutral
+contract defines its input, output, resource bounds, trust treatment, and
+ForgeLoop-owned validation boundary. Vendor-specific adapters remain optional
+and must not become a competing source of protocol truth.
+
+## Security Considerations
+
+Provider output can be malicious, oversized, mutable, delayed, or misleading.
+Strict JSON snapshots, bounded invocation, cooperative cancellation, error
+normalization, recursive authority checks, and no automatic installation keep
+the boundary fail-closed. See [`THREAT_MODEL.md`](../THREAT_MODEL.md) for the
+security ownership table.

package/docs/RECIPES.md

@@ -353,6 +353,10 @@ forgeloop baseline --record --policy-reset-authorized --json
 # 1. Inspect deterministic classification and structured next action
 forgeloop next --task task-001 --json
 
+# 1a. If the active task is intentionally no longer valid, explicitly abandon
+#     it; do not use clear-state or task-recover to bypass ownership
+forgeloop task-abandon --task task-001 --acknowledge-abandonment --json
+
 # 2. RECOVERABLE must use reconcile-closure; do not use task-recover
 forgeloop reconcile-closure --task task-001 --id <verification-id> \
   --requirement "<exact verification text>" -- <verification-command>
@@ -378,6 +382,11 @@ artifact against the complete ledger history. If `next` returns
 `RESOLVE_RECOVERY_INCONSISTENCY`, run `validate-protocol`; do not create, edit,
 or delete `recovery.json` manually.
 
+`task-abandon` is only for an explicit active non-terminal abandonment. It
+records `TASK_ABANDONED`, leaves the phase unchanged, and releases claims as
+`RELEASED_BY_RECOVERY`; it never proves completion. `clear-state` removes only
+the checkpoint and is not a claim-release mechanism.
+
 ---
 
 ### Recipe 16 — Execute a Durable External Action Safely