@cassiomc1/forgeloop 2.0.0-rc.4 → 2.0.0

package/docs/GUIDE_MAINTENANCE.md

@@ -0,0 +1,106 @@
+# Engineering guide maintenance
+
+ForgeLoop's [guide registry](../src/config/guides.json) contains 23 guides.
+The [router](../GUIDE_ROUTER.md) selects relevant context; a catalog entry is
+not evidence that its toolchain is installed, its examples were executed, or
+its target application is ready for release.
+
+## Review scope and authority
+
+The catalog consistency review dated 2026-10-17 covered every registered guide
+for activation claims, precedence, optional-tool boundaries, verification
+language, version handling, and related documentation. Local source and
+validators govern routing, metadata, packaging, and evidence. Official
+version-matched sources govern language/platform semantics. This review is
+not a new certification of every API, release, framework, device, or external
+link, and it does not execute consumer applications.
+
+Use this precedence when maintaining guidance:
+
+1. Preserve platform rules, the user's request, repository constraints, and
+   the canonical ForgeLoop protocol.
+2. Derive activation from `src/core/project-detection.js`, its specialist
+   parsers, `src/core/router.js`, and the public project-evidence schemas.
+3. Read guide gates and completion requirements from registered frontmatter;
+   prose examples do not create extra lifecycle gates or protocol enums.
+4. Preserve project versions and architecture. Dated release examples are
+   reference material, not permission to upgrade a compiler or framework.
+5. Treat named tools and aesthetic defaults as contextual choices. Do not
+   install a missing optional tool or introduce a user-approval gate for a
+   reversible local choice. Reuse scoped authority already given.
+6. Keep unavailable checks and observations separate from passing evidence,
+   legal compliance, publication, deployment, and production readiness.
+
+## Catalog maintenance map
+
+The focus column records the boundary inspected and retained, or the
+substantive correction made. All rows remain subject to the review limits
+above; retained guidance does not imply a fresh external release audit.
+
+| ID | Guide | Maintenance focus |
+| --- | --- | --- |
+| `premium` | [Premium websites](../ENG/premium-sites-studio-eng.md) | Clarified production stages versus runtime gates and genuine client/publication authority |
+| `clean` | [Clean code](../ENG/clean-code-eng.md) | Retained cohesion, public contracts, cancellation, observability, and risk-based dependency guidance; clarified existing installation authority |
+| `test` | [Testing](../ENG/test-code-eng.md) | Retained proportional tests, protected checks, unavailable-tool reporting, and observed evidence; clarified existing installation authority |
+| `security` | [Security](../ENG/sec-code-eng.md) | Retained threat-boundary gate, negative tests, and advisory Cloudflare companion boundary; clarified existing installation authority |
+| `design` | [Design](../ENG/design-code-eng.md) | Preserved product tokens, made example styling and Impeccable contextual, and removed install-capable verifier examples |
+| `taste` | [Taste frontend](../ENG/taste-frontend-eng.md) | Retained contextual v2 adaptation, source/asset provenance, no aesthetic authority, and screenshot-based review |
+| `performance` | [Performance](../ENG/perf-code-eng.md) | Clarified async I/O versus CPU offloading; retained measured baselines, field/lab separation, and bounded resources |
+| `accessibility` | [Accessibility](../ENG/accessibility-eng.md) | Defaulted missing profile to AA without an artificial approval gate; corrected contrast and native-control keyboard guidance |
+| `games` | [Web games](../ENG/games-code-design-web-eng.md) | Retained bounded fixed-step simulation, authoritative resync, validated procedural generation, capability fallback, and deployment checks; clarified installation authority |
+| `documentation` | [Documentation](../ENG/documentation-quality-eng.md) | Added guide-specific checks for factual activation, gates, defaults, optional tools, and release claims |
+| `flutter` | [Flutter](../ENG/flutter-development-eng.md) | Replaced prospective routing instructions with implemented manifest detection and task-specific verification semantics |
+| `dotnet` | [.NET](../ENG/dotnet-aspnetcore-development-eng.md) | Retained structural SDK project detection, scoped ASP.NET/ABP overlays, version compatibility, and build/release distinctions |
+| `nodejs` | [Node.js](../ENG/nodejs-backend-development-eng.md) | Retained bounded backend evidence, module/runtime compatibility, cancellation, resource controls, and operational verification |
+| `rust` | [Rust](../ENG/rust-development-eng.md) | Grounded the release review in primary Rust sources and narrowed safety/API claims; retained Cargo/MSRV and ownership boundaries |
+| `c` | [C](../ENG/c-development-eng.md) | Retained bounded native build/source identity, pointer/ABI contracts, cleanup, sanitizers, and missing-tool limits |
+| `cpp` | [C++](../ENG/cpp-development-eng.md) | Retained native identity, RAII/lifetime/ABI policy, bounded concurrency, and exact-standard verification |
+| `java` | [Java](../ENG/java-development-eng.md) | Retained static Maven/Gradle/Bazel evidence, scoped topology, runtime/build separation, and bounded executor policy |
+| `sql` | [SQL](../ENG/sql-development-eng.md) | Retained host-project overlay, dialect/version discovery, transaction/retry policy, and separate migration authority |
+| `go` | [Go](../ENG/go-development-eng.md) | Retained bounded module/workspace topology, language/toolchain distinction, goroutine ownership, and race/fuzz evidence limits |
+| `typescript` | [TypeScript](../ENG/typescript-development-eng.md) | Retained JSONC/config ownership, runtime-neutral identity, erased-type/runtime validation distinction, and compiler API migration boundary |
+| `php` | [PHP](../ENG/php-development-eng.md) | Aligned the source fallback description with both `<?php` and `<?=` recognized by the parser |
+| `swift` | [Swift](../ENG/swift-development-eng.md) | Retained SwiftPM/native target composition, source-backed identity, concurrency/FFI policy, and signing/platform evidence limits |
+| `python` | [Python](../ENG/python-development-eng.md) | Explicitly documented reference-only status: automatic structural Python routing is not implemented |
+
+## Revalidation procedure
+
+For a guide change, inspect the registered path, frontmatter, related router
+rules, representative valid/invalid fixtures, and affected consumer docs.
+Check an external version-sensitive claim against the project's pinned
+version and the relevant official source before revising it. Update
+`last-reviewed` when that guide is materially revalidated; do not change dates
+on untouched guides merely to make the catalog look fresh.
+
+For policy changes, compare related guides as well: a safe default in one
+document must not become a mandatory tool, approval, rewrite, or installation
+in another. Preserve explicit user requirements and real blocking decisions.
+
+Run proportional checks, including the existing documentation suite:
+
+```bash
+npm run docs:check
+python3 scripts/validate_markdown.py
+npm run pack:check
+npm run security-skill:check
+```
+
+Use `npm run verify:fast` while editing and `npm run verify:prepush` before a
+PR. Those commands verify repository consistency and applicable code/package
+behavior; they do not run all 23 consumer toolchains. New documentation must
+be registered in the documentation manifest and review matrix. Add
+consumer-facing pages to the package allowlist, and derive generated content
+through its existing generator.
+
+## Primary reference points for changed guidance
+
+- [WCAG contrast](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)
+  and [ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/).
+- [Node.js event-loop guidance](https://nodejs.org/en/learn/asynchronous-work/dont-block-the-event-loop).
+- [Official Rust 1.99.0 announcement](https://blog.rust-lang.org/2026/10/01/Rust-1.99.0/).
+- ForgeLoop's [project detector](../src/core/project-detection.js),
+  [PHP recognizer](../src/core/php-project.js),
+  [guide registry](../src/config/guides.json), and
+  [project-evidence schema](../schemas/routing-input.schema.json).
+- [Repository dependency policy](https://github.com/cassiomc1/forgeloop/blob/main/scripts/check-dependency-policy.mjs) and
+  [package metadata](../package.json) for runtime dependencies and versions.

package/docs/OPENSRC_ADAPTER.md

@@ -235,7 +235,7 @@ are added; `providerExtensions.publicRegistryApi` and
 - 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+.
+- The ForgeLoop host requires Node.js 24.19.0+ with built-in `node:sqlite`.
 - 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 privately delivered
+This page describes the intentional boundary of the publicly distributed
 `@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
@@ -13,7 +13,9 @@ 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 `@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.
+Cargo manifest parsing. It requires Node.js 24.19.0 or newer with built-in
+`node:sqlite`, matching `package.json#engines`. The MCP companion retains
+restricted distribution.
 
 ## Included files
 
@@ -54,6 +56,9 @@ The published tarball includes the following consumer-facing groups:
   ASP.NET Core and ABP are conditional routing overlays on the `dotnet` guide,
   not additional package guides. The package does not install or invoke
   framework, compiler, build, package-manager, or database tooling.
+  `docs/GUIDE_MAINTENANCE.md` ships the full catalog maintenance map and
+  revalidation boundaries; it does not add automatic Python routing or new
+  lifecycle gates.
 - **Initialization material:** the root protocol and integration documents,
   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
@@ -74,6 +79,12 @@ The published tarball includes the following consumer-facing groups:
    documentation are also packaged.
    The generated portable ForgeLoop Agent Skill and `docs/AGENT_SKILL.md` are
    packaged as instruction/documentation content, not runtime authority.
+   The optional Cloudflare companion at `skills/security-audit/` also ships,
+   including its upstream references, schema, validators and tests, MIT
+   license, and `PIN.json`. Its usage guide at `docs/SECURITY_AUDIT_SKILL.md`
+   and offline `scripts/verify-security-audit-skill.mjs` checker are packaged.
+   It adds no runtime dependency or automatic scan and is not copied by
+   `init`/`update` into host skill directories.
   Provider implementation modules ship under `src/`, but packaged source file
   does not mean a supported public import path; the generic `./providers`
   subpath remains unexported.
@@ -90,6 +101,9 @@ The published tarball includes the following consumer-facing groups:
 
 The tarball intentionally omits repository-only material:
 
+- the `ForgeLoopAudit/` application source, dependencies, builds, and application
+  package; maintaining it inside the repository does not add it to the core
+  package's `files` allowlist;
 - tests, conformance fixtures, coverage output, and secret-scanning helpers;
   Harness-specific Agent Skill installation directories and Skill caches are
   not packaged.
@@ -141,3 +155,12 @@ 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.
+
+## Optional product design companion
+
+The generated ForgeLoop skill includes the maintained
+`skills/forgeloop/references/revenue-centric-design/` reference tree. It ships
+a focused skill, local journey playbook, complete custom source-available
+license and integrity pin. `docs/REVENUE_CENTRIC_DESIGN.md` and
+`scripts/verify-revenue-design-skill.mjs` describe and verify it. Upstream media
+and updater scripts are excluded; external theme references are pinned links.

package/docs/RELEASE_CHECKLIST.md

@@ -4,6 +4,44 @@ This is the current release checklist for the PolyForm Noncommercial-licensed
 `@cassiomc1/forgeloop` package. It is a preparation and verification checklist;
 it does not authorize publication.
 
+## Stable 2.0.0 candidate — 2026-10-18
+
+The core package version is `2.0.0`, targeting npm `latest`, with Node.js
+24.19.0+ and built-in `node:sqlite`. The MCP companion retains restricted
+distribution and admits the stable core peer. Canonical SQLite is the sole
+supported operational writer; configuration, portable exports, immutable
+attachments and owner-bound maintenance evidence retain explicit file roles.
+
+The [release acceptance record](STABLE_2_ACCEPTANCE.md) identifies source-bound
+writer review, full verification, native user checks and recovery/exclusion
+receipts. A fresh hosted pair on the final release source and exact-head PR
+checks remain mandatory before publication. Do not bypass the release guard,
+reuse an earlier-source benchmark as final evidence, or infer publication from
+package metadata. Physical power-loss and production cutover are separate claims.
+
+Verify the live registry and immutable release identity after publication:
+
+```bash
+npm view @cassiomc1/forgeloop version dist-tags --json
+npm view @cassiomc1/forgeloop@2.0.0 gitHead dist.integrity --json
+npm run release:identity -- --version 2.0.0 --release-commit <release-tag-commit>
+```
+
+## Historical RC4 release evidence
+
+- [RC4 verification and publication](https://github.com/cassiomc1/forgeloop/actions/runs/38629809865)
+  passed full release checks and published with provenance.
+- [Exact-version npm audit](https://github.com/cassiomc1/forgeloop/actions/runs/38638055749)
+  passed 15/15 checks on each native Windows, macOS and Linux host.
+- [Default latest-install audit](https://github.com/cassiomc1/forgeloop/actions/runs/38669237414)
+  installed the unversioned public package with a fresh npm cache,
+  configuration, install prefix and project; all 15 checks passed on each OS.
+  Those results describe RC4, not a later stable package.
+
+The published RC4 npm `gitHead` and immutable `v2.0.0-rc.4` tag identify
+`d05c17cddda6a09581d526732b08eb0789b9734f`. The RC3 tag is retained; its
+publication was cancelled before npm publication.
+
 ## Runtime corrections after RC2
 
 RC3 and later candidates with runtime changes require fresh full repository
@@ -13,16 +51,22 @@ acceptance remains separate; a passing new-user audit does not change
 `soleSQLiteWriter` or authorize a stable 2.x release. Candidates publish to
 `next` under the existing release-channel policy.
 
-The `Published npm new-user SQLite audit` workflow supports `candidate` and
-`npm` package sources. Before a PR, test the packed candidate in an isolated
+The `Published npm new-user SQLite audit` workflow supports `candidate`, `npm` and
+`latest` package sources. Before a PR, test the packed candidate in an isolated
 installation, home directory and project on each platform. After publication,
-dispatch the same workflow with source `npm` and the exact new version. Require
-every check to pass, including live Jev health, concurrent task creation,
-SQLite integrity and a completed-task backup restored to a fresh directory.
+dispatch the same workflow with source `latest` and the exact expected new version.
+The `latest` mode installs the unversioned package with fresh home, cache, npm
+configuration, install prefix and project directories. It retains registry
+metadata alongside the observed audit report. Use `npm` for a separate exact-version
+control. Require
+every check to pass, including both bundled companion integrity checks, live
+Jev health, concurrent task creation,
+SQLite integrity, current-cycle review diagnosis/correction, and a completed-task
+backup restored to a fresh directory.
 Supply `FORGELOOP_NPM_AUDIT_JEV_KEY` through GitHub Actions secrets and remove
 temporary credentials after the runs finish.
 
-## Bounded 2.0.0-rc.2 publication
+## Historical bounded 2.0.0-rc.2 publication
 
 The owner approved short verification and an RC fallback on 2026-10-13. This
 candidate is published to npm `next`. The owner subsequently authorized moving
@@ -58,8 +102,8 @@ p95 result is claimed by the short path. The existing 1,000-task parity run
 `38483369676` is retained for review; no fresh 200-repeat benchmark is dispatched.
 
 The writer inventory covers every current `src` JavaScript module and records
-imports plus potential write sites. Alias, computed-path, external-caller, and
-transitive-authority review remain incomplete. The inventory explicitly keeps
+imports plus potential write sites. At that historical RC checkpoint, alias, computed-path, external-caller, and
+transitive-authority review remained incomplete. The inventory explicitly keeps
 `wholeConsumerClosure: false`; it prevents drift and does not authorize setting
 `soleSQLiteWriter` to true.
 
@@ -69,22 +113,37 @@ confirmation `PUBLISH PUBLIC PACKAGE`, then verify npm version, Git commit,
 tarball integrity, and provenance. Stable publishing retains full checks and
 additionally refuses incomplete sole-writer acceptance.
 
-## Owner-authorized RC2 default channel
+## Owner-authorized default-channel promotion
+
+Publishing a new release candidate still uses `next`. Moving an already
+published candidate to `latest` is a separate owner-authorized tag operation;
+it neither republishes the package nor changes the immutable Git tag.
+The owner authorized RC4 after its cross-platform npm audits passed.
+
+For that explicitly authorized RC4 operation, authenticated npm CLI access
+was used:
+
+```bash
+npm dist-tag add @cassiomc1/forgeloop@2.0.0-rc.4 latest
+npm view @cassiomc1/forgeloop dist-tags --json
+```
+
+npm may require separate browser/security-key verification for login and
+for the tag mutation. Credentials belong in npm's authentication flow,
+never documentation, Git or task artifacts. Confirm the registry result
+before reporting success. The version remains an RC; promotion does not
+establish stable SQLite acceptance or production readiness.
 
-Dispatch `npm-publish.yml` on `main` with operation `promote-latest` and
-confirmation `POINT LATEST TO RC2`. This moves only `latest` to the already
-published public `2.0.0-rc.2`; it neither republishes nor modifies the RC2 tag.
-The promotion checks the exact release commit and downloaded SHA-512, refuses
-unexpected existing tags, and requires npm trusted-publisher `manageDistTags`
-authority. No credentials are logged or stored. The version remains an RC;
-stable SQLite acceptance and production readiness are still incomplete.
+The older `promote-latest` operation in `npm-publish.yml` and
+`scripts/promote-rc-latest.mjs` is hard-bound to RC2. It is historical tooling,
+not an RC4 promotion path; do not dispatch `POINT LATEST TO RC2` for the
+current release. Its exact-identity and tag guards are retained.
 
 ## ForgeLoop 2.0.0 candidate scope
 
-The 2.0.0 candidate is not release-ready while SQLite migration plan §10 has
-open consumer-closure, current-source performance, or platform evidence. Keep
-all acceptance boxes open until their evidence is bound to the exact candidate
-revision.
+A stable 2.0.0 publication requires the source-bound acceptance record and final
+release-source checks. The preparation checklist below is not itself a pass;
+retain exact evidence for each applicable requirement.
 
 The 2.0.0 candidate carries the SQLite storage transition alongside the
 existing protocol, routing, provider, documentation, and package surfaces. The

package/docs/REVENUE_CENTRIC_DESIGN.md

@@ -0,0 +1,69 @@
+# Revenue-centric design companion
+
+ForgeLoop includes an optional [revenue-centric design companion](../skills/forgeloop/references/revenue-centric-design/SKILL.md)
+for product journeys, activation, pricing clarity and retention. It adapts
+[heliocosta-dev/revenue-centric-design at the reviewed commit](https://github.com/heliocosta-dev/revenue-centric-design/tree/1942760c2242f609bf63ce2c97204f5a1791bd68),
+a curation of Richard ([@richardrx](https://x.com/richardrx)).
+
+## Availability and scope
+
+The source and npm package include the focused skill, an offline journey
+playbook, full upstream license and pin manifest under
+`skills/forgeloop/references/revenue-centric-design/`. The original twelve
+theme references are linked at an immutable upstream commit; media, updater
+scripts, scraping dependencies and API configuration are excluded.
+
+Ask an agent to read the companion at that package or source path for relevant
+product work. It is not activated for ordinary protocol or storage maintenance.
+Hosts requiring skill discovery can copy that complete directory into their
+project skill directory after inspecting any existing destination. Preserve
+its license, attribution and pin. `init`, `update` and the skill generator do
+not install or synchronize this discovery copy.
+
+```bash
+node scripts/verify-revenue-design-skill.mjs
+# From a consumer project with a local ForgeLoop installation:
+node node_modules/@cassiomc1/forgeloop/scripts/verify-revenue-design-skill.mjs
+```
+
+The checker verifies the explicit file set and SHA-256 hashes with CRLF
+normalized to LF for portable text checkouts. The pin detects drift against a
+reviewed manifest; it is not a signature, sandbox or evidence of business impact.
+For a copied directory, call the exported `verifyRevenueDesignSkill` function
+with its absolute `rootDir`.
+
+## Use with ForgeLoop
+
+Inspect the actual user journey, identify observed friction and propose a
+small reversible change. Pair a user-value metric with a guardrail such as
+successful cancellation, accessibility, error recovery or price comprehension.
+Treat principles, anecdotes and claimed statistics as hypotheses requiring
+context and original-source verification. Browser checks establish behavior;
+conversion and retention claims require appropriate real measurement.
+
+For ForgeLoopAudit, relevant work concerns read-only project selection, a first
+successful inspection, understandable evidence, useful errors and navigation.
+This addition does not add commercial flows, tracking or paid experiments to
+the auditor. Audit remains read-only and keeps its own verification commands.
+
+The canonical contract, guide router, runtime, gates and validators retain
+all authority. This companion adds no guide ID, runtime dependency, provider,
+automatic gate or completion requirement. Its advice cannot establish
+`COMPLETE` or `VALID`. Preserve informed choice: honest proof and pricing,
+visible renewal terms, reversible defaults and usable cancellation/opt-out.
+
+## Attribution and usage terms
+
+The [complete upstream license](../skills/forgeloop/references/revenue-centric-design/LICENSE)
+is retained unchanged. It requires attribution to Richard and the source,
+preservation of its full terms in copies/derivatives, and excludes gambling,
+betting, casino and real-money games-of-chance uses, including loot boxes.
+These are source-available custom terms, not an OSI-approved open-source
+license or ForgeLoop's PolyForm license. Copy the license with any adaptation.
+
+The adaptation replaces the broad upstream entrypoint with a focused workflow
+and local journey matrix. It links source themes progressively, keeps external
+research unverified until checked, and preserves ForgeLoop authority and user
+choice. To update it, review the upstream commit and terms, update the
+adaptation and pin together, then verify integrity, documentation and package
+contents. Do not run the upstream updater as part of a ForgeLoop release.

package/docs/SECURITY_AUDIT_SKILL.md

@@ -0,0 +1,131 @@
+# Cloudflare security audit companion
+
+ForgeLoop bundles Cloudflare's optional
+[`security-audit`](../skills/security-audit/SKILL.md) skill for source-based
+security questions, focused vulnerability reviews, and explicitly requested
+codebase audits. It provides a repeatable investigation workflow alongside
+the canonical [security guide](../ENG/sec-code-eng.md).
+
+The companion is instruction content with local report validators. It adds no
+runtime dependency, scanner service, automatic scan, or ForgeLoop completion
+gate. ForgeLoopAudit inspects protocol evidence; this companion investigates
+source-level security boundaries. These are separate capabilities.
+
+## Availability and setup
+
+The complete skill directory ships in the source repository and core npm
+package at `skills/security-audit/`. It includes the domain references,
+findings schema, both validators, their tests, the upstream MIT license, and
+ForgeLoop's pin manifest. The upstream files are unchanged.
+
+From a ForgeLoop checkout, verify the copy before using it:
+
+```bash
+node scripts/verify-security-audit-skill.mjs
+```
+
+In a project with a local npm installation, use:
+
+```bash
+node node_modules/@cassiomc1/forgeloop/scripts/verify-security-audit-skill.mjs
+```
+
+Ask an agent to read the companion's `SKILL.md` at that package or checkout
+path and use its guidance for the requested scope. Hosts that require skill
+discovery can instead copy the **entire** `skills/security-audit/` directory
+into their supported project skill directory, such as
+`.agents/skills/security-audit/`. Inspect an existing destination first;
+preserve local modifications rather than overwriting them. Keep all companion
+files together, including `LICENSE` and `PIN.json`. Verify a copied directory
+with `verifySecurityAuditSkill({ rootDir: absoluteSkillDirectory })`, exported
+by the same checker module.
+
+ForgeLoop `init` and `update` do not install or synchronize this skill into a
+host's discovery directories. Updating ForgeLoop also does not update a copied
+host skill. No global installation or external Skills CLI is required.
+
+## Choose the appropriate mode
+
+| Request | Mode and result |
+| --- | --- |
+| Explain a security control or investigate one suspected issue | Guidance mode; read relevant references, without automatically creating audit files or running all phases |
+| Audit a codebase, perform a comprehensive security review, or produce audit reports | Full audit mode; follow all six upstream phases, including independent verification and coverage accounting |
+| Fix a confirmed issue | A separately scoped ForgeLoop implementation contract with regression checks; the audit itself does not modify target source |
+
+Example agent request for a focused review:
+
+> Read the bundled security-audit skill. Review the authorization boundary in
+> src/auth in guidance mode. Return source-grounded observations and exact
+> unresolved facts.
+
+Example agent request for a full audit:
+
+> Read the bundled security-audit skill. Audit this repository, follow all six
+> phases, and report partial coverage and unavailable capabilities explicitly.
+
+For a full audit, select scope, source revision, profile, and an external
+output directory under the upstream rules. Use an in-target output directory
+only when the user explicitly chooses it and version control ignores the
+entire directory. Respect host write permissions. Audit artifacts belong to
+the audit output directory, outside ForgeLoop-owned task state.
+
+Full audit mode requires independent delegated hunters and verifiers. A
+single agent's self-review cannot satisfy that independence. Target-controlled
+execution additionally requires the upstream OS-enforced sandbox: network
+isolation, sanitized environment, read-only target/toolchain, assigned scratch
+writes, and explicit resource limits. A generic terminal sandbox or a
+`run-check` receipt does not establish all these controls. If a required
+capability is unavailable, retain the exact blocker and incomplete or
+`needs_validation` status as required upstream; do not weaken the evidence
+bar. No live endpoint probing, dependency fetching, publication, or paid
+service use is authorized by loading this skill.
+
+## Findings and ForgeLoop authority
+
+Preserve upstream verdicts:
+
+- `confirmed`: a source-grounded boundary failure with the required validation;
+  severity describes the demonstrated impact.
+- `needs_validation`: an exact source-grounded hypothesis with a missing fact;
+  it has no severity.
+- `rejected`: a candidate disproved by validation.
+
+The six phases produce architecture and coverage records, findings, independent
+record verification, and reports. Run both upstream validators against the
+artifacts using the argument contracts documented in the skill. They validate
+report structure and consistency; passing them does not prove that the target
+is secure, that every attack surface was covered, or that a finding is true.
+
+Findings remain advisory observations. They cannot satisfy ForgeLoop gates,
+change claims, advance phases, or establish `COMPLETE` or `VALID`. The
+[Security Review provider](./SECURITY_REVIEW.md) is a separate host-injected
+observation API; this bundle does not register a provider or import reports
+into it. Its normalized finding contract is not interchangeable with the
+upstream report schema.
+
+When a finding requires a fix, inspect it, bind it to a scoped contract, and
+verify the behavior through canonical ForgeLoop checks. Use `run-check` for
+exact-command provenance where execution is authorized. Never copy a report
+directly into task state or relabel it as ForgeLoop-owned evidence. The
+canonical runtime and validators retain all completion authority.
+
+## Provenance and maintenance
+
+- Source: [cloudflare/security-audit-skill](https://github.com/cloudflare/security-audit-skill).
+- Pinned commit: `c1c8a8c1471069fb0e188eeaff69b8e8db6564a8`.
+- Upstream directory: `skills/security-audit/`; `LICENSE` comes from the
+  upstream repository root.
+- License: [MIT, copyright Cloudflare, Inc.](../skills/security-audit/LICENSE),
+  retained separately from ForgeLoop's license.
+- [PIN.json](../skills/security-audit/PIN.json) records SHA-256 hashes of every
+  upstream file, including the license. The checker rejects changed, missing,
+  extra, or symlinked entries without executing the skill.
+  The repository's `.gitattributes` preserves the entire companion tree as
+  bytes, including CJS validators and the license, across CRLF checkout settings.
+
+The hashes detect drift against the reviewed manifest; they are not a
+signature or a sandbox. Updating the companion is an explicit maintenance
+change: review the exact upstream revision and license, replace the complete
+upstream tree, regenerate its file hashes, update the documented pin, run the
+integrity checker and both upstream validator suites, and verify package
+contents. Do not silently fetch a newer revision during normal operation.

package/docs/SECURITY_REVIEW.md

@@ -57,6 +57,12 @@ ForgeLoop-owned validation and evidence contract.
 
 ## Operational rules
 
+The optional bundled [Cloudflare security audit companion](./SECURITY_AUDIT_SKILL.md)
+is an agent workflow with a separate report schema. It does not register a
+Security Review provider or automatically import its findings. An upstream
+`needs_validation` record must not be promoted to a severity-bearing confirmed
+finding or canonical evidence by an adapter.
+
 - Keep registration lazy and explicit.
 - Use a host-owned provider and a bounded request.
 - Treat findings as advisory observations, not proof of `VALID`, `COMPLETE`,

package/docs/STABLE_2_ACCEPTANCE.md

@@ -0,0 +1,80 @@
+# Stable ForgeLoop 2.0.0 acceptance
+
+This record separates supported operational-writer acceptance from publication,
+production cutover and universal process exclusion. Historical migration
+scoreboards retain their original source and dates; this record is the current
+release pointer.
+
+## Supported writer boundary
+
+The source review covers every core/MCP runtime JavaScript module, 105 literal
+filesystem modules, 457 lexically bound filesystem/wrapper references and 16
+indirect references. The inventory has no nonliteral runtime imports. Ninety-five
+filesystem modules match the prior reviewed bytes; ten changed modules were
+reviewed against their exact deltas. Source hashes, roles, indirect-reference
+dispositions, authority chains and limits are retained in the
+[source review](https://github.com/cassiomc1/forgeloop/blob/61447313c5b13e6eb8d80240a5be5c6eea56a410/benchmarks/storage-sqlite/stable-2.0.0-writer-review.json.gz).
+
+Supported CLI, Integration API and MCP dispatch select canonical SQLite.
+Operational state, events, receipts, claims and indexed domain records share the
+native transaction boundary. Portable writers reject operational namespaces;
+mixed native/legacy layouts, foreign or expired contexts and actor-supplied
+persistence capabilities fail closed. Explicit migration and restore admission
+retain independent ownership and quiescence checks.
+
+Configuration, installation manifests, exports/bundles, backups, immutable
+attachments, owner-bound maintenance journals/archives, repository-index caches,
+transport state and private scratch files are explicit file-owned exceptions.
+They are not writable operational mirrors. Legacy data requires explicit
+migration; a migrated active project does not silently fall back to JSON.
+
+The candidate advertises `soleSQLiteWriter: true` for this reviewed supported
+operational boundary. Source acceptance does not imply final release, registry,
+performance, or production acceptance.
+
+## Validation evidence
+
+- [Native candidate audit](https://github.com/cassiomc1/forgeloop/actions/runs/39125623599):
+  15/15 checks on macOS ARM64, Windows x64 and Linux x64, including the new
+  review-finding → diagnosis → correction → fresh verification flow.
+- [Windows full suite](https://github.com/cassiomc1/forgeloop/actions/runs/39083442557):
+  successful on the runtime correction candidate.
+- [Old-client exclusion](https://github.com/cassiomc1/forgeloop/actions/runs/39125628347):
+  successful on native Linux and Windows. Retained evidence records the precise
+  inventoried identity/installation and cleanup boundary.
+- macOS source `61447313`: all sixteen real public rollback/owner-death cases
+  pass with unchanged source; the separate old-client drill passes with cleanup.
+  Raw records are retained under `benchmarks/storage-sqlite/stable-candidate-6144731-darwin-*`.
+- The [earlier-source hosted pair](https://github.com/cassiomc1/forgeloop/actions/runs/39083441154)
+  at `e9139a55` passes the owner-approved comparison: 1,000 canonical-rich-all
+  tasks, ordinary 10 events, selected 1,000 events, 200 samples per side,
+  exact output parity and validated worker completion. Native p95 is 2,205.943 ms
+  versus 5,162.466 ms for task listing, and 2,190.628 ms versus 5,177.674 ms for
+  project tasks. This is preparation evidence; the final release source must
+  repeat the same hosted case before publication.
+
+`scripts/verify-stable-storage-review.mjs` checks complete core/MCP runtime
+module membership and normalized source SHA-256 hashes against the reviewed
+manifest. The stable channel guard requires this check; any new module or source
+drift requires review. This is a repository release check, not a signature or
+substitute for the behavioral checks below.
+
+Final-source full pre-push/release verification, native candidate checks,
+required exact-head PR checks and the final hosted comparison must all be
+successful. The immutable `v2.0.0` publication workflow preserves the stable
+channel guard and runs full verification; the RC1/RC2 shortcut is inapplicable.
+After publication, verify registry `gitHead`, SHA-512 integrity and tag identity,
+then run fresh unversioned `latest` installations with the expected exact version
+on all three native hosts. The audit also checks both bundled companions.
+Update this source record with terminal release links in the post-publication
+documentation/Audit alignment change; never treat a pending run as successful.
+
+## Limits
+
+These checks establish the supported release boundary. Process-kill drills do
+not prove physical power-loss behavior. Raw privileged SQLite access, arbitrary
+host providers/external commands and uninventoried legacy installations are
+outside this proof. Production migration still requires a named target, backup,
+writer inventory and operator-enforced quiescence; no live project was migrated
+by these release tests. No production deployment or Audit binary publication
+is implied by core npm publication.