@cassiomc1/forgeloop 2.0.0-rc.4 → 2.0.0-rc.5

package/DOCS_INDEX.md

@@ -36,6 +36,7 @@ integration and guide context. Use this map before editing documentation.
 | Platform adapters | [`docs/PLATFORM_ADAPTERS.md`](./docs/PLATFORM_ADAPTERS.md) | Generic CI boundary and platform mapping guidance |
 | Universal integration API | [`docs/UNIVERSAL_INTEGRATION.md`](./docs/UNIVERSAL_INTEGRATION.md) | Programmatic integration subpath, envelope semantics, and consumer map |
 | Audit UX read model | [`docs/AUDIT_UX.md`](./docs/AUDIT_UX.md) | Bounded read-only task timeline, health, verification, ownership, and completion projection |
+| ForgeLoopAudit workspace | [`docs/FORGELOOP_AUDIT.md`](./docs/FORGELOOP_AUDIT.md) | In-repository Audit setup, project inspection, view walkthrough, screenshots and verification links |
 | Advisory context providers | [`docs/ADVISORY_CONTEXT.md`](./docs/ADVISORY_CONTEXT.md) | Optional external host context, non-evidence trust boundary, allowlist normalization, and safety rules |
 | Provider extension architecture | [`docs/PROVIDER_ARCHITECTURE.md`](./docs/PROVIDER_ARCHITECTURE.md) | Provider-neutral architecture, invocation lifecycle, strict snapshots, cancellation, trust, and authority boundaries |
 | Provider extension reference | [`docs/PROVIDERS.md`](./docs/PROVIDERS.md) | Capability discovery, provider kinds, common contract, limits, errors, and maintainer checklist |

package/README.md

@@ -77,9 +77,8 @@ not establish project identity. Public project evidence remains v1.
 ## Distribution and license
 
 GitHub hosts source and issues. The core npm package is publicly available;
-the MCP companion retains restricted distribution. The owner-selected default
-`latest` channel targets `2.0.0-rc.2`, which remains a release candidate with
-incomplete stable SQLite acceptance.
+the MCP companion retains restricted distribution. RC5 targets `next`; `latest`
+remains at RC4. Stable SQLite acceptance is incomplete.
 ForgeLoop-owned source and documentation are licensed under the
 [PolyForm Noncommercial License 1.0.0](./LICENSE). Commercial use is not granted
 by this license. Third-party notices are documented in
@@ -89,7 +88,7 @@ by this license. Third-party notices are documented in
 
 ### Installation
 
-After your organization grants access, configure npm authentication and install:
+Install the public core package from npm; no organization access is required:
 
 ```bash
 npm install --global @cassiomc1/forgeloop
@@ -204,7 +203,7 @@ forgeloop protocol-info --json
 | Validate completion | Yes | Provides real work and evidence |
 | Schedule agents or LLM inference | No | External to the protocol |
 
-From the privately delivered package, initialize a target project with:
+Initialize a target project using the public npm package:
 
 ```bash
 npx @cassiomc1/forgeloop init
@@ -247,7 +246,7 @@ host-reported or `UNKNOWN`; values are never estimated.
 capability, but advisory recall remains Integration API only. The stock CLI
 does not auto-recall providers and does not expose a `context-recall` command.
 
-Validate the source checkout offline before any private release:
+Validate the source checkout before preparing a release:
 
 ```bash
 node src/cli.js init
@@ -496,6 +495,12 @@ CI audits each supplied task receipt explicitly. With no receipt it reports
 completion or attestation. For contributor checks and safe payload retention,
 see [CONTRIBUTING.md](./CONTRIBUTING.md#focused-verification-and-maintenance).
 
+## ForgeLoopAudit workspace
+
+The read-only auditor lives in `ForgeLoopAudit/`. See
+[setup, usage and screenshots](./docs/FORGELOOP_AUDIT.md) for the demo,
+project inspection and audit views.
+
 ## Protocol compatibility
 
 The npm package version is independent of protocol version. The current
@@ -616,17 +621,15 @@ docs/diagrams/          typed Archify diagram source and inventory
 docs/assets/diagrams/   committed HTML, SVG, and generation receipt
 scripts/                checks, renderer, release identity, CI notes
 tests/                  Node and Python regression coverage
-.forgeloop/             project-scoped ForgeLoop configuration
+.forgeloop/             project-scoped configuration
 .forgeloop/task-state/  isolated live task protocol state
 DOCS_INDEX.md           documentation map and ownership boundaries
 ```
 
-Project-scoped configuration remains under `.forgeloop/`.
 Task-scoped mutable protocol state is stored under
 `.forgeloop/task-state/<taskKey>/`.
 
-For document ownership, guide routing, capability degradation, and integration
-details, start at [`DOCS_INDEX.md`](./DOCS_INDEX.md).
+For documentation ownership and integrations, see [`DOCS_INDEX.md`](./DOCS_INDEX.md).
 
 ## Programmatic integration and MCP
 
@@ -636,8 +639,7 @@ ForgeLoop exposes a stable programmatic surface:
 import { executeForgeLoopCommand } from "@cassiomc1/forgeloop/integration";
 ```
 
-The local MCP server (`@cassiomc1/forgeloop-mcp`, stdio) is an adapter over
-this exact API — it never reimplements ForgeLoop. See
+The local MCP server (`@cassiomc1/forgeloop-mcp`, stdio) wraps this API. See
 [`docs/UNIVERSAL_INTEGRATION.md`](./docs/UNIVERSAL_INTEGRATION.md) and
 [`docs/MCP.md`](./docs/MCP.md). MCP is optional; the CLI and instruction-only
 hosts remain fully supported without it.

package/docs/AGENT_PROTOCOL_SUMMARY.md

@@ -7,7 +7,7 @@
 ForgeLoop is a portable protocol and support CLI for verifiable engineering workflows. It records and validates task state, contracts, routing, checks, evidence, continuity, and optional code attestations. It does not become an agent scheduler, delegation service, source-control authority, or secret manager.
 
 Protocol version: 1
-Package version: 2.0.0-rc.4
+Package version: 2.0.0-rc.5
 
 ## Canonical loop
 

package/docs/AGENT_SKILL.md

@@ -48,6 +48,21 @@ behavioral certification for every external harness. Existing native
 `AGENTS.md`, `CLAUDE.md`, Cursor, and Copilot integration surfaces remain
 intact.
 
+## ForgeLoopAudit workspace guidance
+
+The generated Skill documents the Audit component at `ForgeLoopAudit/` inside
+the ForgeLoop repository, replacing the standalone repository and
+`../ForgeLoopAudit`. It directs agents to
+resolve the target project root before running commands: core ForgeLoop uses
+the parent root; Audit uses its own directory, instructions, package scripts,
+and configured protocol runtime. ForgeLoop is the source and contribution home
+for both components; their package commands, task state, and receipt provenance
+remain scoped to the target root. Audit remains a read-only auditor.
+
+Maintain this guidance in `scripts/generate-forgeloop-skill.mjs`, then run
+`npm run skill:generate` and `npm run skill:check`. An independently installed
+Skill must be updated separately; generation only writes the repository copy.
+
 ## Safety Boundaries
 
 Agents must discover tasks first, follow `next`, respect claims, require

package/docs/FORGELOOP_AUDIT.md

@@ -0,0 +1,71 @@
+# ForgeLoopAudit — setup and usage
+
+ForgeLoopAudit is the local, read-only web interface for inspecting ForgeLoop
+projects. It lives in [`ForgeLoopAudit/`](https://github.com/cassiomc1/forgeloop/blob/main/ForgeLoopAudit/README.md) in this
+repository; the standalone repository is retired. Use it to inspect task
+progress, findings, verification evidence, quality, history and reports.
+ForgeLoop remains the authority for lifecycle and completion decisions.
+
+## Start ForgeLoopAudit
+
+Use Node.js **24.19.0 or newer**. From a checkout of this repository:
+
+```bash
+cd ForgeLoopAudit
+npm ci
+npm run build:web
+node dist/server/cli.mjs --demo
+```
+
+The CLI starts a loopback-only server and opens the browser. If it does not
+open automatically, use the one-time bootstrap URL printed in the terminal.
+Keep the terminal running while using Audit; press `Ctrl+C` to stop the server.
+
+To inspect your own ForgeLoop project, replace the demo command with an
+explicit project path, still from `ForgeLoopAudit/`:
+
+```bash
+node dist/server/cli.mjs --project /absolute/path/to/your-project
+```
+
+To inspect the parent ForgeLoop checkout itself, use `--project ..`.
+Audit reads native SQLite task state through ForgeLoop's public Integration API.
+Legacy JSON projects open as `ARTIFACT_ONLY`; Audit does not migrate them or
+change task state. Project selection stays with the local server rather than
+uploading a repository through the browser.
+
+## Explore the audit views
+
+1. Open **Audit Summary** for integrity, completion readiness, quality and trust
+   verdicts. Use **Run audit** to refresh the read-only assessment.
+2. Use **Projects** and **Task Board** to navigate registered projects and tasks
+   by canonical lifecycle phase; open **Tasks** for a task's detailed audit.
+3. Review **Findings** and **Evidence** to trace warnings and verification gaps.
+   Coverage, attestation and completion are separate signals.
+4. Inspect **Quality**, **Policy & Trust**, **Audit History** and **Diagnostics**
+   for supporting context. Use **Reports** for exports to managed local storage.
+   **Repository Search** is discovery only, not verification evidence.
+
+## Screenshots
+
+These are existing captures of the ForgeShop demo, taken from the production
+renderer at 1440 × 900 in the dark theme, aligned to Audit `0.3.0-rc.3` and
+ForgeLoop `2.0.0-rc.4`. The demo deliberately includes invalid, stale, blocked and
+unverified scenarios. Its warnings and coverage values do not establish
+completion or production readiness for your project.
+
+| Audit Summary | Task Board |
+| --- | --- |
+| ![ForgeShop demo audit summary with separate integrity, readiness, quality and trust verdicts](https://raw.githubusercontent.com/cassiomc1/forgeloop/main/ForgeLoopAudit/screen/audit-summary.png) | ![Read-only task board grouping demo tasks by canonical lifecycle phase](https://raw.githubusercontent.com/cassiomc1/forgeloop/main/ForgeLoopAudit/screen/kanban.png) |
+| Findings | Evidence |
+| ![ForgeShop demo findings with provenance and severity](https://raw.githubusercontent.com/cassiomc1/forgeloop/main/ForgeLoopAudit/screen/findings.png) | ![ForgeShop demo task evidence and verification scope](https://raw.githubusercontent.com/cassiomc1/forgeloop/main/ForgeLoopAudit/screen/evidence.png) |
+
+See the [complete screenshot gallery](https://github.com/cassiomc1/forgeloop/blob/main/ForgeLoopAudit/README.md#screenshots)
+and [capture provenance](https://github.com/cassiomc1/forgeloop/blob/main/ForgeLoopAudit/screen/README.md) for the full set.
+For development, verification and command-root details, see the
+[Audit README](https://github.com/cassiomc1/forgeloop/blob/main/ForgeLoopAudit/README.md),
+[Audit documentation index](https://github.com/cassiomc1/forgeloop/blob/main/ForgeLoopAudit/docs/README.md) and
+[workspace guidance](./AGENT_SKILL.md#forgeloopaudit-workspace-guidance).
+Audit has its own dependencies, build and verification commands. Its application
+source and screenshots are excluded from the core npm package; npm users can
+[read this section and its images on GitHub](https://github.com/cassiomc1/forgeloop#forgeloopaudit-workspace).

package/docs/GETTING_STARTED.md

@@ -117,6 +117,12 @@ and numeric limits.
 
 ### Global installation
 
+The public core package is available without organization access. As of
+2026-10-14, both npm `latest` and `next` resolve to `2.0.0-rc.4`. The default
+installation below uses `latest`; use `@cassiomc1/forgeloop@2.0.0-rc.4` when an
+exact reproducible version is required. RC4 remains a release candidate;
+its passing new-user checks do not establish stable SQLite acceptance.
+
 Install the ForgeLoop CLI globally to make the `forgeloop` command available
 in your terminal:
 

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
 
@@ -90,6 +92,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.

package/docs/RELEASE_CHECKLIST.md

@@ -4,6 +4,37 @@ 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
+
+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.
+
+Observed 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.
+  This run uses the test-harness branch `codex/latest-user-audit-20261014`;
+  its `latest` input is not present in the main-branch workflow.
+
+The published 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
+```
+
 ## Runtime corrections after RC2
 
 RC3 and later candidates with runtime changes require fresh full repository
@@ -22,7 +53,7 @@ SQLite integrity 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
@@ -69,19 +100,35 @@ 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
+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.

package/docs/TROUBLESHOOTING.md

@@ -27,7 +27,7 @@ install the kit before expecting the complete `doctor` report to be healthy.
 ## Concurrent task creation
 
 Task creation revalidates write claims atomically. If the catalog changes while
-a command is prepared, RC3 refreshes authoritative claim inputs with bounded
+a command is prepared, RC4 refreshes authoritative claim inputs with bounded
 backoff and jitter without replaying the command or its external effects.
 Overlapping claims still fail. Sustained contention can exhaust the retry
 bound and return a catalog-change refusal; inspect fresh task discovery
@@ -133,7 +133,8 @@ tests or change assertions. Local coverage remains an explicit command because
 instrumentation adds measurable overhead; the PR unit lane wraps that same
 `test:ci` process across four deterministic shards, then aggregates coverage
 without running the suite again. Docs-only changes run the quick suite only on
-the first Node 24 shard; the other shards and the Node 20 lane do not install.
+the first Node 24 shard; the other shards do not install. The minimum Node
+24.19.0 compatibility lane runs only for applicable source or runtime changes.
 
 #### Native Windows guidance
 

package/docs/documentation-manifest.json

@@ -1405,6 +1405,17 @@
         "self-hosted-node-validation"
       ],
       "packaged": true
+    },
+    {
+      "path": "docs/FORGELOOP_AUDIT.md",
+      "id": "forgeloop-audit",
+      "class": "operational",
+      "audience": [
+        "user",
+        "maintainer"
+      ],
+      "canonicalFor": [],
+      "packaged": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "2.0.0-rc.4",
+  "version": "2.0.0-rc.5",
   "description": "Evidence-first engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",
@@ -82,6 +82,7 @@
     "docs/MCP.md",
     "docs/UNIVERSAL_INTEGRATION.md",
     "docs/AUDIT_UX.md",
+    "docs/FORGELOOP_AUDIT.md",
     "docs/DIAGNOSTIC_MODEL.md",
     "docs/EXECUTION_TRACE.md",
     "docs/CODE_ATTESTATION.md",
@@ -193,7 +194,7 @@
   },
   "dependencies": {
     "@typesafe-ai/sdk": "0.6.0",
-    "smol-toml": "1.8.0"
+    "smol-toml": "1.9.0"
   },
   "exports": {
     ".": "./src/cli.js",

package/scripts/generate-forgeloop-skill.mjs

@@ -42,6 +42,12 @@ Runtime registries and validators outrank canonical protocol docs; canonical doc
 
 In ForgeLoop's own source repository, use \`node src/cli.js\`. In a consumer repository, use that repository's configured local invocation. Never silently install or upgrade ForgeLoop, and never use a stale global CLI when repository-local code exists. If compatibility is uncertain, inspect \`protocol-info --json\`.
 
+## ForgeLoopAudit Workspace
+
+ForgeLoopAudit is maintained at \`ForgeLoopAudit/\` inside the ForgeLoop repository, replacing the standalone repository and sibling path \`../ForgeLoopAudit\`. ForgeLoop is its source and contribution home. This source layout is not a prerequisite for consumer projects or npm installations. Audit remains a read-only auditor with its own package, documentation, build, and verification commands; it is not included in the core ForgeLoop npm package.
+
+Resolve the target root before running commands. For core work, stay at the ForgeLoop root and use \`node src/cli.js\`. For Audit work, enter \`ForgeLoopAudit/\`, read its own project instructions and \`README.md\`, and resolve its configured ForgeLoop runtime there. Audit development uses \`npm run dev:web\`; its full verification uses \`npm run verify:full\`, both from the Audit root. Do not apply the parent's CLI path blindly in the child directory or merge their task state. A directory move does not rebind receipts, workspace bindings, or stored project paths; inspect affected artifacts through supported tooling and never rewrite protocol state to repair a moved root.
+
 ## Operating Workflow
 
 1. Discover existing work with \`node src/cli.js task-list --json\`.

package/skills/forgeloop/SKILL.md

@@ -27,6 +27,12 @@ Runtime registries and validators outrank canonical protocol docs; canonical doc
 
 In ForgeLoop's own source repository, use `node src/cli.js`. In a consumer repository, use that repository's configured local invocation. Never silently install or upgrade ForgeLoop, and never use a stale global CLI when repository-local code exists. If compatibility is uncertain, inspect `protocol-info --json`.
 
+## ForgeLoopAudit Workspace
+
+ForgeLoopAudit is maintained at `ForgeLoopAudit/` inside the ForgeLoop repository, replacing the standalone repository and sibling path `../ForgeLoopAudit`. ForgeLoop is its source and contribution home. This source layout is not a prerequisite for consumer projects or npm installations. Audit remains a read-only auditor with its own package, documentation, build, and verification commands; it is not included in the core ForgeLoop npm package.
+
+Resolve the target root before running commands. For core work, stay at the ForgeLoop root and use `node src/cli.js`. For Audit work, enter `ForgeLoopAudit/`, read its own project instructions and `README.md`, and resolve its configured ForgeLoop runtime there. Audit development uses `npm run dev:web`; its full verification uses `npm run verify:full`, both from the Audit root. Do not apply the parent's CLI path blindly in the child directory or merge their task state. A directory move does not rebind receipts, workspace bindings, or stored project paths; inspect affected artifacts through supported tooling and never rewrite protocol state to repair a moved root.
+
 ## Operating Workflow
 
 1. Discover existing work with `node src/cli.js task-list --json`.