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

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,9 @@ 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. The owner-selected default
+`latest` channel targets `2.0.0-rc.2`, which remains a release candidate with
+incomplete stable SQLite acceptance.
 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

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.4
 
 ## Canonical loop
 

package/docs/RELEASE_CHECKLIST.md

@@ -4,11 +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.
 
+## 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.
+
 ## 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,6 +69,16 @@ 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
+
+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.
+
 ## ForgeLoop 2.0.0 candidate scope
 
 The 2.0.0 candidate is not release-ready while SQLite migration plan §10 has

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, RC3 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.
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "2.0.0-rc.2",
+  "version": "2.0.0-rc.4",
   "description": "Evidence-first engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",

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");