@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/docs/DOCUMENTATION_GUIDE.md

@@ -54,11 +54,30 @@ Documentation-impact questions for integration/MCP changes:
 - Did an adapter error code change?
 - Did an integration limit or resource list change?
 
-Anti-drift invariant: every `documentation-manifest.json` entry marked
-`packaged: true` is mechanically checked against the core npm tarball
-contents (`tests/package.test.js`).
-
-Canonical phase and transition inventories must be derived from `WORK_PHASES`
+Anti-drift invariant: every packaged Markdown or harness-adapter document in
+`package.json.files` is registered in `documentation-manifest.json`, and every
+`packaged: true` manifest entry is mechanically checked against the core npm
+tarball contents (`tests/package.test.js`). The review matrix records generated
+or handwritten origin, current or historical status, package inclusion, action,
+and canonical sources for every registered document.
+
+### Documentation retention and repository hygiene
+
+Use one canonical owner for each maintained concept. Generated documentation
+must name its source, generator, freshness check, and reason for being tracked.
+Historical audits, release evidence, and completed validation records belong
+under `docs/history/`; current operating instructions must not leave those
+records loose in the repository root. One-off plans and validation reports are
+either consolidated into a canonical document and deleted or moved to the
+history index with their current owner links.
+
+Repository and npm decisions are separate. GitHub may retain reproducible
+benchmarks, PoC evidence, source-bound diagram artifacts, vendored renderer
+sources, and historical records that consumers do not need. The npm package
+ships only intentional runtime, integration, legal, harness, and canonical user
+documentation surfaces. `npm run repository:hygiene` enforces explicit root,
+tracked-state, visual-ownership, benchmark-run-set, and scratch-output policy;
+it does not guess whether an arbitrary document is useful.
 and `WORK_TRANSITIONS`; do not maintain independent hand-written transition
 enums when a generated or mechanically validated representation is available.
 
@@ -195,7 +214,7 @@ migration, or security-sensitive require `npm run docs:check` before merge.
 2. **Pinned local renderer**: Generation uses only the vendored Archify v2.15.0 source at the reviewed commit recorded in `docs/diagrams/manifest.json` and `vendor/archify/v2.15.0/PIN.json`.
 3. **Animated committed outputs**: Every active source uses `meta.animation: "trace"`. Each interactive HTML is the primary animated explorer, and each self-contained SVG fallback carries trace-capable edge/node animation while remaining usable in repository previews. Deterministic receipts are committed under `docs/assets/diagrams/`.
 4. **GitHub-safe SVG**: The SVG must not embed `<script>` or `<foreignObject>`, must expose accessible title/description metadata, and must remain visible through standard Markdown image syntax.
-5. **Fingerprint and review verification**: The generated SVG embeds a `data-forgeloop-source-sha256` attribute, the outputs expose trace markers, and the receipt binds the source, HTML, and SVG hashes. The human-owned review at `docs/diagrams/reviews/` binds the current source and SVG hashes and is never generated or overwritten. Run `npm run docs:diagrams:check` before review.
+5. **Fingerprint and review verification**: The generated SVG embeds a `data-forgeloop-source-sha256` attribute, the outputs expose trace markers, and the receipt binds the source, HTML, and SVG hashes. The review at `docs/diagrams/reviews/` binds the current source and SVG hashes as a review assertion and is never generated or overwritten; the checker does not independently authenticate the reviewer. Run `npm run docs:diagrams:check` before review.
 6. **Scoped wrapper**: The ForgeLoop Archify wrapper is intentionally documentation-scoped. It reads canonical inputs only from `docs/diagrams/` and permits deliver outputs only under `docs/assets/diagrams/`.
 
 ForgeLoop governs five documentation-diagram categories: workflow,
@@ -213,14 +232,18 @@ README hero assets are branding/conceptual architecture illustrations. They are
 not the canonical protocol diagram. The typed Archify workflow under
 `docs/diagrams/` remains the canonical lifecycle architecture source, with
 generated outputs under `docs/assets/diagrams/`; the CLI-only persistent search
-transport is explained by `docs/PERSISTENT_SEARCH_TRANSPORT.md`.
+transport is explained by `docs/PERSISTENT_SEARCH_TRANSPORT.md`. The current
+repository-only assets are `docs/assets/forgeloop-architecture.png`, the
+alternate [architecture SVG](./assets/forgeloop-architecture.svg), and
+`docs/assets/forgeloop-lifecycle-animated.svg`; none is a package file.
 
 The README hero is intentionally GitHub-repository-only:
 
-- `README.md` may reference `docs/assets/eng_readme_forgeloop.png`; GitHub
-  renders it from the repository.
-- The hero PNG is excluded from the npm package (`package.json` `files`), and
-  `tests/package.test.js` asserts that exclusion so it cannot be silently
+- `README.md` references `docs/assets/forgeloop-architecture.png` for the hero
+  and `docs/assets/forgeloop-lifecycle-animated.svg` for the looping overview;
+  both are repository-only and excluded from the npm package. The architecture
+  SVG remains available as a repository-only alternate.
+- `tests/package.test.js` asserts those exclusions so they cannot be silently
   re-included.
 - The packaged README is therefore not self-contained for that relative hero
   path; do not claim otherwise.

package/docs/GETTING_STARTED.md

@@ -6,7 +6,7 @@ This guide walks through your first complete task with ForgeLoop from initializa
 
 ## 1. What is ForgeLoop?
 
-ForgeLoop is a portable, vendor-neutral engineering protocol for AI-assisted coding and automated workflows. It turns a task outcome into:
+ForgeLoop is a vendor-neutral engineering protocol for AI-assisted coding and automated workflows. It turns a task outcome into:
 
 - **A structured contract** (`.forgeloop/task-state/<taskKey>/contract.json`);
 - **Deterministic guide routing** based on declared work type, surfaces, and risks;
@@ -108,7 +108,7 @@ and numeric limits.
 
 ## 2. Prerequisites
 
-- **Node.js**: version 20 or higher (`node -v`)
+- **Node.js**: version 24.19.0 or higher (`node -v`), with built-in `node:sqlite`
 - **npm**: standard npm toolchain
 
 ---
@@ -281,7 +281,7 @@ forgeloop route \
   --json
 ```
 
-This writes `.forgeloop/task-state/<taskKey>/routing-result.json` referencing selected guides (e.g. `clean`, `test`, `security`, `design`, `accessibility`).
+This records selected guides (e.g. `clean`, `test`, `security`, `design`, `accessibility`) in SQLite. `.forgeloop/task-state/<taskKey>/routing-result.json` is the logical artifact identity and explicit export path. Native mutations require a selected task; create one first or select an existing task.
 
 ---
 

package/docs/JEV_BENCHMARKS.md

@@ -0,0 +1,31 @@
+# Jev benchmark and calibration
+
+`npm run benchmark:jev` emits an offline deterministic baseline for model-route
+scenarios. It records the pinned engine/model, safety-floor projection, fallback
+status, Jev/cache/latency fields, context and tool dimensions, and unknown host
+telemetry. Zero counts mean that no provider request was made; `null` and
+`NOT_MEASURED` remain explicit when the host did not observe a value. It does
+not fabricate provider usage and does not authorize lifecycle, execution,
+pruning, or completion.
+
+Provider-backed calibration requires a live TypeSafe organization with credits;
+an unavailable provider is reported as unavailable rather than treated as a
+successful benchmark.
+
+`npm run benchmark:jev:live` runs bounded intake, route, and context requests
+through the pinned Jev provider and reports provider usage/latency only when the
+provider supplies it. It requires `TYPESAFE_API_KEY`, never prints that key,
+and is intentionally separate from the offline benchmark.
+
+An optional maintainer release check is available through
+`npm run jev:smoke` and `npm run benchmark:jev:live`. The current repository does
+not enforce either live command in CI or the release workflow, and the CLI does
+not bind either command to an exact candidate commit. Offline output, a missing
+credential, or a provider-unavailable result is never a substitute for live
+interoperability evidence.
+
+Dependency audit attribution for the current base and PR head is unchanged:
+one high-severity `js-yaml` advisory (`GHSA-2883-xcg3-v3hh`, CVSS 7.5, CWE-400
+and CWE-407) arrives transitively through `eslint` → `@eslint/eslintrc` →
+`js-yaml` 4.3.1. It is not introduced by the Jev dependency; the audit reports
+an available upgrade outside this correction's runtime dependency policy.

package/docs/MODEL_ROUTING.md

@@ -0,0 +1,37 @@
+# Model routing
+
+ForgeLoop exposes model routing as a bounded semantic-decision projection. It
+has `SEMANTIC_DECISION` authority only within the declared decision contract;
+it has no lifecycle, completion, evidence, ownership, installation, command, or
+publication authority. The deterministic policy establishes the safety floor:
+
+- `NONE` when no generation is required;
+- `STANDARD` for ordinary executable generation;
+- `PRIMARY` for security, architecture, migration, ambiguity, and other
+  high-risk signals.
+
+The deterministic floor currently emits `NONE`, `STANDARD`, or `PRIMARY`. The
+public vocabulary also includes `FAST`, which is available only as an advisory
+escalation and cannot lower the deterministic floor.
+
+The pinned Jev model (`jev-1.13.0`) may recommend an escalation or request an
+escalation when confidence is low. It can never lower the deterministic floor,
+select a vendor-specific model, execute a command, change lifecycle state,
+authorize ownership, or weaken verification requirements. ForgeLoop remains the
+authority for all lifecycle, evidence, safety, and completion decisions.
+
+For route execution, the same boundary applies to guide relevance: Jev can
+reorder or remove a selected non-mandatory guide only with sufficient
+confidence. Mandatory safety protection is derived from the canonical
+deterministic route reasons the router already produced (auth surface and the
+trust-boundary risks untrusted-input, personal-data, secrets, external-service,
+publication), so a `security` guide selected by `external-service` risk cannot be
+removed. Mandatory safety guides are retained and low-confidence removal
+recommendations are retained rather than treated as authority. The resulting
+guide set and profile are persisted in the route artifact, so the semantic
+recommendation materially affects routing without becoming lifecycle authority.
+
+The live Jev provider is not an authority substitute. Semantic-required
+model-routing operations consume a fresh persisted `MODEL_ROUTE` decision and
+fail closed when it is unavailable or stale; offline inspection may still
+project deterministic policy without making a network request.

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

@@ -1,6 +1,6 @@
 # Core npm package contents
 
-This page describes the intentional boundary of the published
+This page describes the intentional boundary of the privately delivered
 `@cassiomc1/forgeloop` package. The [`files`](../package.json) list in
 `package.json` is the packaging source of truth, while the repository's
 `tests/package.test.js` and clean-room `scripts/package_smoke.mjs` checks keep
@@ -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/`,
@@ -40,7 +55,7 @@ The published tarball includes the following consumer-facing groups:
   not additional package guides. The package does not install or invoke
   framework, compiler, build, package-manager, or database tooling.
 - **Initialization material:** the root protocol and integration documents,
-  legal notices, the target profile template, and every path listed by
+  the PolyForm Noncommercial license, third-party notices, the target profile template, and every path listed by
   `src/core/templates.js`. These files are read by `init` and `update`, so
   they are part of the executable consumer contract even when a document is
   marked deprecated in the documentation manifest.
@@ -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,9 +91,11 @@ 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);
+  receipts; the target `.forgeloop/.gitignore` is generated from an inline
+  runtime template and no `.forgeloop/*` files are packaged;
 - raw or aggregate benchmark results, package archives, and release train
   contracts;
 - the Ripwire retrieval benchmark runner, cases, and fixture corpus; those
@@ -77,9 +103,12 @@ 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.png`,
+  `docs/assets/forgeloop-architecture.svg`, and
+  `docs/assets/forgeloop-lifecycle-animated.svg`. The PNG and animated SVG are
+  referenced by the repository README; all three 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.
@@ -107,9 +136,8 @@ exercises the CLI, public Integration API, initialization, schemas, and the
 Structural Quality documentation's packaged diagram references. The
 package-boundary tests also assert
 that every registered guide path, including all language specialists, is
-present in the candidate. The tag-triggered publication
-workflow
-runs the same smoke gate before `npm publish --provenance --access public`.
-Publication therefore remains owned by the trusted GitHub Actions OIDC
-workflow; local package inspection proves the candidate boundary but does not
-publish it.
+present in the candidate. The manual, explicitly authorized publication workflow runs the same smoke
+gate before `npm publish --provenance --access public`.
+Publication therefore remains owned by the authorized manual GitHub Actions
+workflow and uses public npm access for the core package; local package inspection proves the
+candidate boundary but does not publish it.

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`.