@cassiomc1/forgeloop 2.0.0-rc.5 → 2.0.0

package/docs/RELEASE_CHECKLIST.md

@@ -4,14 +4,30 @@ 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.
 
-## Current published candidate — 2026-10-14
+## Stable 2.0.0 candidate — 2026-10-18
 
-The public core package is `2.0.0-rc.4`; npm `latest` and `next` both resolve
-to RC4. It requires Node.js 24.19.0+ with built-in `node:sqlite`. The MCP
-companion retains restricted distribution. RC4 is a release candidate;
-`soleSQLiteWriter` remains false and stable/production acceptance is open.
+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.
 
-Observed release evidence:
+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.
@@ -20,20 +36,11 @@ Observed release evidence:
 - [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.
-  This run uses the test-harness branch `codex/latest-user-audit-20261014`;
-  its `latest` input is not present in the main-branch workflow.
+  Those results describe RC4, not a later stable package.
 
-The published npm `gitHead` and immutable `v2.0.0-rc.4` tag identify
+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. RC4 carries those runtime
-fixes plus the Windows archive-repair test correction.
-
-Verify the live registry before relying on a channel:
-
-```bash
-npm view @cassiomc1/forgeloop version dist-tags --json
-npm view @cassiomc1/forgeloop@2.0.0-rc.4 gitHead dist.integrity --json
-```
+publication was cancelled before npm publication.
 
 ## Runtime corrections after RC2
 
@@ -44,12 +51,18 @@ 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.
 
@@ -89,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.
 
@@ -128,10 +141,9 @@ current release. Its exact-identity and tag guards are retained.
 
 ## ForgeLoop 2.0.0 candidate scope
 
-A stable 2.0.0 release is not 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.

package/docs/TROUBLESHOOTING.md

@@ -280,6 +280,18 @@ forgeloop record-diagnosis --task <id> \
   --next-safe-action="Smallest safe action to address the hypothesis"
 ```
 
+A new finding discovered in `REVIEWING` can also be diagnosed there. First
+record the actual negative observation with `record-check --kind manual-review
+--status failed --evidence-kind OBSERVED`, binding it to the affected
+requirement. A blocked finding uses `--status blocked --evidence-kind BLOCKED`.
+Passed evidence remains restricted to `VERIFYING`. Both legacy and structured
+diagnoses must reference a failed or blocked check from the current cycle.
+Then follow `next`, enter `CORRECTING`, and rerun verification in the new cycle.
+A task already in `CORRECTING` from review follows the same finding and
+diagnosis requirements. Repository-only drift may be refreshed through
+`reconcile-closure` after its contract-bound check passes; that refresh neither
+creates a diagnosis nor authorizes a retry.
+
 Then advance to `CORRECTING`:
 
 ```bash