@cassiomc1/forgeloop 2.0.0-rc.2 → 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

@@ -11,9 +11,9 @@
 [![Package smoke](https://github.com/cassiomc1/forgeloop/actions/workflows/package-smoke.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/package-smoke.yml)
 [![Release notes](https://github.com/cassiomc1/forgeloop/actions/workflows/release-notes.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/release-notes.yml)
 
-ForgeLoop is the deterministic governor for AI-assisted engineering. Jev provides bounded System One semantic input; the host coding model provides System Two implementation. ForgeLoop owns lifecycle, claims, gates, evidence, completion, recovery, and publication truth.
+ForgeLoop governs AI-assisted engineering. Jev supplies bounded semantic input; the host model implements changes. ForgeLoop owns lifecycle, claims, gates, evidence, completion, recovery, and publication truth.
 
-Operational sources: [`DOCS_INDEX.md`](./DOCS_INDEX.md); [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) is canonical; [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md) defines discovery; [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md) stores project facts; [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) selects guides.
+Sources: [`DOCS_INDEX.md`](./DOCS_INDEX.md); canonical [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md); discovery [`PROTOCOL_INTEGRATION.md`](./PROTOCOL_INTEGRATION.md); project facts [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md); guides [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md).
 
 ## Where should I start?
 
@@ -33,7 +33,6 @@ Operational sources: [`DOCS_INDEX.md`](./DOCS_INDEX.md); [`LOOP_ENGINEERING.md`]
 - **Troubleshooting & error codes** → [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md)
 - **Code attestation & revision coverage** → [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md)
 - **System architecture & safety** → [`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) & [`THREAT_MODEL.md`](./THREAT_MODEL.md)
-- **Documentation index & ownership** → [`DOCS_INDEX.md`](./DOCS_INDEX.md)
 
 ## Real execution proof
 
@@ -78,7 +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 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
@@ -88,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
@@ -203,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
@@ -246,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
@@ -495,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
@@ -615,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
 
@@ -635,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.2
+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,11 +4,61 @@ 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.
 
-## Bounded 2.0.0-rc.2 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
+verification and the clean-user audit on Windows, macOS and Linux. The bounded
+source-equivalence shortcut below applies only to RC1 and RC2. Stable SQLite
+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
+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.
+Supply `FORGELOOP_NPM_AUDIT_JEV_KEY` through GitHub Actions secrets and remove
+temporary credentials after the runs finish.
+
+## 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 only to npm `next`; stable `latest` remains blocked while
-`soleSQLiteWriter` is false. A release candidate does not assert completed
+candidate is published to npm `next`. The owner subsequently authorized moving
+`latest` to the existing RC2 through a guarded tag-only promotion. Publishing a
+new stable version remains blocked while `soleSQLiteWriter` is false. A release candidate does not assert completed
 migration acceptance or production readiness.
 
 After npm rejected restricted RC1 publication with `E402`, the owner authorized
@@ -50,9 +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 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.
+
+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

@@ -1,5 +1,38 @@
 # ForgeLoop Troubleshooting Guide
 
+## Windows Repository Index ZIP extraction
+
+When `init` reports `E_REPOSITORY_INDEX_ENGINE_EXTRACTION_FAILED` and
+`tar: This does not look like a tar archive`, a GNU tar from Git may be
+shadowing Windows' ZIP-capable system tool. RC3 selects
+`%SystemRoot%\System32\tar.exe` explicitly for inspection and extraction.
+Archive and binary checksum verification and unsafe-entry rejection still
+apply. A missing system tool remains an explicit extraction failure; ForgeLoop
+does not install replacement software automatically.
+
+## Restoring completed tasks into another directory
+
+Use an attachment-inclusive `storage-backup` and `storage-restore` with
+externally stopped writers. Historical execution records keep their original
+project root and exact bytes. RC3 accepts them only when they exactly match
+the snapshot bound to the destination's restore journal and storage marker.
+Keep `.forgeloop/storage-restores/<operation-id>/snapshot` and its journal;
+they are retained provenance evidence, not a disposable search cache.
+An altered record, missing snapshot or broken binding remains rejected.
+
+Storage restore does not install project code or instruction adapters. Restore
+the project files separately, then run `forgeloop init` in the destination to
+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, 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
+before deciding whether to retry.
+
 This guide provides symptom-first recovery procedures for common ForgeLoop protocol, state, and verification issues.
 
 ---
@@ -100,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.2",
+  "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`.

package/src/core/completion-artifacts.js

@@ -124,6 +124,19 @@ function commandProvenanceError(message = "Observed command evidence requires a
   return artifactError("E_COMMAND_PROVENANCE_UNATTESTED", message, [ARTIFACT_PATHS.receipt]);
 }
 
+async function validateExecutionProjectRoot({ target, taskId, check, execution, protocolProjectRoot, allowForeignCwd, executionArtifacts }) {
+  if (allowForeignCwd || path.resolve(protocolProjectRoot) === path.resolve(target)) return;
+  const { isRetainedRestoreExecution } = await import("../storage/restore-execution-provenance.js");
+  const restored = !executionArtifacts && await isRetainedRestoreExecution(target, execution, { taskId });
+  if (!restored) {
+    throw artifactError(
+      "E_EXECUTION_REF_INVALID",
+      "Execution artifact protocol project root does not match the current target",
+      [taskId ? taskExecutionPath(taskId, check.executionRef) : ARTIFACT_PATHS.executionDirectory],
+    );
+  }
+}
+
 /**
  * Revalidate the ForgeLoop-owned execution artifact behind an observed command
  * check. This is intentionally asynchronous so completion and audit can verify
@@ -194,13 +207,7 @@ export async function validateCheckExecutionProvenance(check, {
       [taskId ? taskExecutionPath(taskId, check.executionRef) : ARTIFACT_PATHS.executionDirectory],
     );
   }
-  if (!allowForeignCwd && path.resolve(protocolProjectRoot) !== path.resolve(target)) {
-    throw artifactError(
-      "E_EXECUTION_REF_INVALID",
-      "Execution artifact protocol project root does not match the current target",
-      [taskId ? taskExecutionPath(taskId, check.executionRef) : ARTIFACT_PATHS.executionDirectory],
-    );
-  }
+  await validateExecutionProjectRoot({ target, taskId, check, execution, protocolProjectRoot, allowForeignCwd, executionArtifacts });
   if (check.status === "passed" && (execution.status !== "passed" || execution.exitCode !== 0)) {
     throw artifactError(
       "E_EXECUTION_REF_INVALID",

package/src/repository-index/binary-manager.js

@@ -181,8 +181,14 @@ export function validateArchiveEntry(entry) {
   return normalized;
 }
 
+export function resolveArchiveTool(archive, { platform = process.platform, env = process.env } = {}) {
+  // Windows ships a ZIP-capable bsdtar. Git's GNU tar can shadow it on PATH.
+  if (platform === "win32") return path.win32.join(env.SystemRoot || "C:\\Windows", "System32", "tar.exe");
+  return archive === "zip" ? "unzip" : "tar";
+}
+
 async function listArchiveEntries(archivePath, { archive = "tar.gz", execFileImpl = nodeExecFile } = {}) {
-  const listCommand = archive === "zip" && process.platform !== "win32" ? "unzip" : "tar";
+  const listCommand = resolveArchiveTool(archive);
   const archiveName = path.basename(archivePath);
   const listArgs = listCommand === "unzip" ? ["-Z1", archiveName] : ["-tf", archiveName];
   try {
@@ -195,7 +201,7 @@ async function listArchiveEntries(archivePath, { archive = "tar.gz", execFileImp
 
 async function extractArchive(archivePath, extractionDirectory, { archive = "tar.gz", execFileImpl = nodeExecFile } = {}) {
   await listArchiveEntries(archivePath, { archive, execFileImpl });
-  const extractCommand = archive === "zip" && process.platform !== "win32" ? "unzip" : "tar";
+  const extractCommand = resolveArchiveTool(archive);
   const destination = path.relative(path.dirname(archivePath), extractionDirectory).replaceAll("\\", "/") || ".";
   const extractArgs = extractCommand === "unzip"
     ? ["-q", path.basename(archivePath), "-d", destination]

package/src/storage/migration-validation.js

@@ -26,7 +26,7 @@ function artifactSchema(row) {
 }
 
 /** Validate imported payloads with their existing protocol schemas and rules. */
-export async function validateMigrationDatabase(db, { target, packageRoot }) {
+export async function validateMigrationDatabase(db, { target, packageRoot, archivedExecutions = false }) {
   const schemas = new Map();
   const validate = async (text, name, label, taskId = null) => {
     if (!name) throw Object.assign(new Error(`Unmapped operational artifact: ${label}`), { code: "E_STORAGE_MIGRATION_UNMAPPED_SOURCE" });
@@ -55,13 +55,13 @@ export async function validateMigrationDatabase(db, { target, packageRoot }) {
       validator?.(value);
     }
   }
-  return withOperationalStore({ db, target }, async () => {
+  return withOperationalStore({ db, target, readOnly: true }, async () => {
     const tasks = [];
     for (const row of db.prepare("SELECT task_id FROM tasks ORDER BY task_id").iterate()) {
       const state = await readWorkState(target, { taskId: row.task_id, packageRoot });
       for (const check of state?.checks ?? []) {
         if (check.provenance === "FORGELOOP_EXECUTED") {
-          await validateCheckExecutionProvenance(check, { target, packageRoot, taskId: row.task_id });
+          await validateCheckExecutionProvenance(check, { target, packageRoot, taskId: row.task_id, allowForeignCwd: archivedExecutions });
         }
       }
       const ledger = await validateEventLedger(target, packageRoot, { taskId: row.task_id });

package/src/storage/project-replacement.js

@@ -77,7 +77,7 @@ export async function resumeProjectReplacementPreparation(target, { operationId,
     if (intent.phase === "PREPARING") {
       await ensurePreparedRestoreSnapshot(target, current.root, intent, { journalFilename: "replacement-intent.json" });
       await withVerifiedProjectStorageBackup(await assertSafePath(current.root, "snapshot"), async retained => {
-        await validateMigrationDatabase(retained.db, { target: retained.root, packageRoot });
+        await validateMigrationDatabase(retained.db, { target: retained.root, packageRoot, archivedExecutions: true });
         await withVerifiedProjectStorageBackup(intent.source, source => {
           if (canonicalFingerprint(source.manifest) !== intent.sourceFingerprint
             || canonicalFingerprint(logicalSnapshot(source.db)) !== canonicalFingerprint(logicalSnapshot(retained.db))) throw invalid("Replacement recovery snapshot differs from recorded source");
@@ -99,7 +99,7 @@ export async function resumeProjectReplacementPreparation(target, { operationId,
 export async function replaceActiveProjectStorage(source, target, { writersQuiesced = false, packageRoot = getPackageRoot() } = {}) {
   if (writersQuiesced !== true) throw Object.assign(new Error("Exclude writers and close their database connections before active replacement"), { code: "E_STORAGE_MIGRATION_QUIESCENCE_REQUIRED" });
   return withVerifiedProjectStorageBackup(source, async ({ db, root, manifest }) => {
-    await validateMigrationDatabase(db, { target: root, packageRoot });
+    await validateMigrationDatabase(db, { target: root, packageRoot, archivedExecutions: true });
     const relative = path.relative(path.resolve(target), root).split(path.sep).join("/");
     if (REPLACEMENT_ACTIVE_ROOTS.some(name => relative === name || relative.startsWith(`${name}/`))) throw invalid("Replacement source cannot be archived outgoing operational state");
     return withStorageMaintenance(target, async () => {
@@ -119,7 +119,7 @@ export async function replaceActiveProjectStorage(source, target, { writersQuies
       const snapshot = await assertSafePath(operationRoot, "snapshot");
       await backupProjectStorage(db, root, snapshot);
       await withVerifiedProjectStorageBackup(snapshot, async retained => {
-        await validateMigrationDatabase(retained.db, { target: retained.root, packageRoot });
+        await validateMigrationDatabase(retained.db, { target: retained.root, packageRoot, archivedExecutions: true });
         await withVerifiedProjectStorageBackup(root, current => {
           if (canonicalFingerprint(current.manifest) !== intent.sourceFingerprint
             || canonicalFingerprint(logicalSnapshot(current.db)) !== canonicalFingerprint(logicalSnapshot(retained.db))) throw invalid("Incoming source changed during replacement preparation");

package/src/storage/project-restore.js

@@ -92,7 +92,7 @@ export async function restoreProjectStorageToFreshProject(source, target, { writ
           if (canonicalFingerprint(current.manifest) !== canonicalFingerprint(sourceManifest)
             || canonicalFingerprint(logicalSnapshot(current.db)) !== canonicalFingerprint(logicalSnapshot(snapshot))) throw invalid("Source backup changed during restore preparation");
         });
-        await validateMigrationDatabase(snapshot, { target: retained, packageRoot });
+        await validateMigrationDatabase(snapshot, { target: retained, packageRoot, archivedExecutions: true });
         const binding = { operationId, databaseSchemaVersion: readStorageMeta(snapshot).schema_version,
           sourceInventoryFingerprint: canonicalFingerprint({ database: manifest.databaseSha256, inventory: manifest.inventorySha256, references: manifest.references }) };
         Object.assign(journal, { phase: "READY", binding, snapshotFingerprint: canonicalFingerprint(manifest) });
@@ -111,7 +111,7 @@ async function publishReadyRestore(target, operationRoot, journal, { packageRoot
   const persist = () => writeFileAtomic(journalPath, `${JSON.stringify(journal, null, 2)}\n`);
   const { operationId, binding } = journal;
   return withVerifiedProjectStorageBackup(retained, async ({ db: snapshot, manifest }) => {
-    await validateMigrationDatabase(snapshot, { target: retained, packageRoot });
+    await validateMigrationDatabase(snapshot, { target: retained, packageRoot, archivedExecutions: true });
     await assertOwnedStorageMaintenance(target);
     await verifyProjectRestoreJournal(target, operationId, { expectedOwnerId: await assertOwnedStorageMaintenance(target) });
     await assertRestorePublicationLayout(target, snapshot);
@@ -186,7 +186,7 @@ async function validatePreparedRestore(target, root, journal, packageRoot) {
     await withVerifiedProjectStorageBackup(journal.source, async source => {
       if (canonicalFingerprint(source.manifest) !== journal.sourceFingerprint
         || canonicalFingerprint(logicalSnapshot(source.db)) !== canonicalFingerprint(logicalSnapshot(snapshot))) throw invalid("Prepared restore differs from its recorded source backup");
-      await validateMigrationDatabase(snapshot, { target: snapshotPath, packageRoot });
+      await validateMigrationDatabase(snapshot, { target: snapshotPath, packageRoot, archivedExecutions: true });
     });
     await assertOwnedStorageMaintenance(target);
     Object.assign(journal, { phase: "READY", snapshotFingerprint: canonicalFingerprint(manifest), binding: {

package/src/storage/restore-execution-provenance.js

@@ -0,0 +1,26 @@
+import { canonicalFingerprint } from "../core/artifacts.js";
+import { readStorageVersionMarker } from "./storage-marker.js";
+import { verifyProjectRestoreJournal } from "./restore-journal.js";
+import { withVerifiedProjectStorageBackup } from "./project-backup.js";
+import { operationalContext } from "./operational-context.js";
+
+/** Historical roots remain valid only for exact records in the bound snapshot. */
+export async function isRetainedRestoreExecution(target, execution, { taskId } = {}) {
+  // Replacement journals also audit incoming archives. Those read-only audits
+  // must not select their snapshot as the caller's live operational project.
+  return operationalContext.run(null, () => verifyRetainedExecution(target, execution, taskId));
+}
+
+async function verifyRetainedExecution(target, execution, taskId) {
+  const marker = await readStorageVersionMarker(target);
+  if (!marker?.operationId) return false;
+  let retained;
+  try { retained = await verifyProjectRestoreJournal(target, marker.operationId); }
+  catch (error) { if (error.code === "ENOENT") return false; throw error; }
+  if (!retained.snapshotVerified || !["PUBLISHING", "ACTIVE"].includes(retained.journal.phase)) return false;
+  return withVerifiedProjectStorageBackup(retained.snapshot, ({ db }) => {
+    const row = db.prepare("SELECT payload_json FROM executions WHERE task_id = ? AND execution_id = ?")
+      .get(taskId ?? execution.taskId, execution.executionId);
+    return Boolean(row && canonicalFingerprint(JSON.parse(row.payload_json)) === canonicalFingerprint(execution));
+  });
+}

package/src/storage/restore-replacement-archive.js

@@ -22,7 +22,7 @@ const belongs = (name, root) => name === root || name.startsWith(`${root}/`);
 async function incomingSnapshot(target, operationId, packageRoot) {
   const root = await assertSafePath(target, `.forgeloop/storage-restores/${operationId}/snapshot`);
   return withVerifiedProjectStorageBackup(root, async ({ db, manifest }) => {
-    await validateMigrationDatabase(db, { target: root, packageRoot });
+    await validateMigrationDatabase(db, { target: root, packageRoot, archivedExecutions: true });
     return { root, fingerprint: canonicalFingerprint(manifest) };
   });
 }

package/src/storage/restore-replacement.js

@@ -80,7 +80,7 @@ export async function prepareActiveStorageReplacement(target, operationId, { wri
     const backup = await assertSafePath(root, "backup");
     await backupProjectStorage(db, target, backup);
     await withVerifiedProjectStorageBackup(backup, async retained => {
-      await validateMigrationDatabase(retained.db, { target: retained.root, packageRoot });
+      await validateMigrationDatabase(retained.db, { target: retained.root, packageRoot, archivedExecutions: true });
       const logicalFingerprint = canonicalFingerprint(logicalSnapshot(retained.db));
       if (logicalFingerprint !== canonicalFingerprint(logicalSnapshot(db))) throw invalid("Outgoing state changed while its retained backup was prepared");
       Object.assign(manifest, { backupFingerprint: canonicalFingerprint(retained.manifest), logicalFingerprint });

package/src/storage/unit-of-work.js

@@ -1,7 +1,8 @@
 import { publishAttachmentFile, verifyAttachmentFile } from "./attachment-files.js";
 import { insertVerifiedAttachmentReference, validateAttachmentReference } from "./attachment-references.js";
 import path from "node:path";
-import { randomUUID, createHash } from "node:crypto";
+import { randomUUID, createHash, randomInt } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
 import { operationalContext, getOperationalStore } from "./operational-context.js";
 import { canonicalFingerprint } from "../core/artifacts.js";
 import { taskStorageKey } from "../core/task-identity.js";
@@ -547,7 +548,10 @@ async function commitPreparedStore(store, packageRoot) {
   for (let refresh = 0; ; refresh += 1) {
     try { store.commit(); return; }
     catch (error) {
-      if (error.code !== "E_STORAGE_CATALOG_CHANGED" || refresh >= 3) throw error;
+      if (error.code !== "E_STORAGE_CATALOG_CHANGED" || refresh >= 16) throw error;
+      // Spread simultaneous creators before refreshing their authoritative
+      // claim inputs. The prepared command and external effects are not replayed.
+      await delay(Math.min(5 * (2 ** refresh), 100) + randomInt(0, 20));
       store.reads.delete("task-catalog");
       const { discoverTasks } = await import("../core/task-discovery.js");
       const { assertNoScopeConflicts } = await import("../core/task-scope.js");