@cassiomc1/forgeloop 1.0.0 → 1.1.0

package/src/core/error-codes.js

@@ -0,0 +1,197 @@
+import { FAILURE_CODES } from "./protocol.js";
+import {
+  E_AUTHORITY_INVALID,
+  E_AUTHORITY_SCOPE_MISMATCH,
+  E_COMMAND_RESOLUTION_AMBIGUOUS,
+  E_INSTALLATION_AUTHORITY_REQUIRED,
+  E_VERIFICATION_TOOL_UNAVAILABLE,
+} from "./verification-constants.js";
+
+export const E_TASK_REQUIRED = "E_TASK_REQUIRED";
+export const E_TASK_NOT_FOUND = "E_TASK_NOT_FOUND";
+export const E_TASK_ALREADY_EXISTS = "E_TASK_ALREADY_EXISTS";
+export const E_TASK_AMBIGUOUS = "E_TASK_AMBIGUOUS";
+export const E_TASK_SELECTOR_CONFLICT = "E_TASK_SELECTOR_CONFLICT";
+export const E_TASK_DESCRIPTOR_INVALID = "E_TASK_DESCRIPTOR_INVALID";
+export const E_TASK_KEY_MISMATCH = "E_TASK_KEY_MISMATCH";
+export const E_TASK_CONTEXT_MISMATCH = "E_TASK_CONTEXT_MISMATCH";
+
+export const E_TASK_LOCKED = "E_TASK_LOCKED";
+export const E_TASK_LOCK_INVALID = "E_TASK_LOCK_INVALID";
+
+export const E_TASK_SCOPE_REQUIRED = "E_TASK_SCOPE_REQUIRED";
+export const E_TASK_SCOPE_CONFLICT = "E_TASK_SCOPE_CONFLICT";
+export const E_TASK_SCOPE_DIRTY = "E_TASK_SCOPE_DIRTY";
+export const E_TASK_SCOPE_FROZEN = "E_TASK_SCOPE_FROZEN";
+export const E_TASK_CHANGE_OUTSIDE_SCOPE = "E_TASK_CHANGE_OUTSIDE_SCOPE";
+export const E_TASK_CHANGE_ATTRIBUTION_UNAVAILABLE = "E_TASK_CHANGE_ATTRIBUTION_UNAVAILABLE";
+
+export const E_TASK_LAYOUT_LEGACY = "E_TASK_LAYOUT_LEGACY";
+export const E_TASK_MIGRATION_INVALID = "E_TASK_MIGRATION_INVALID";
+export const E_TASK_MIGRATION_IDENTITY_MISMATCH = "E_TASK_MIGRATION_IDENTITY_MISMATCH";
+
+/**
+ * Public, stable ForgeLoop error and reason codes documented for users and harnesses.
+ */
+export const PUBLIC_ERROR_CODES = Object.freeze({
+  E_PREFLIGHT_NOT_READY: Object.freeze({
+    code: "E_PREFLIGHT_NOT_READY",
+    category: "preflight",
+    classification: "PUBLIC_STABLE",
+    meaning: "Preflight gates or contract validations are incomplete.",
+    safeResolution: "Satisfy required gates and check preflight output.",
+  }),
+  E_CONTRACT_STALE: Object.freeze({
+    code: "E_CONTRACT_STALE",
+    category: "freshness",
+    classification: "PUBLIC_STABLE",
+    meaning: "Contract modified after downstream artifacts were generated.",
+    safeResolution: "Re-run forgeloop route and forgeloop preflight.",
+  }),
+  E_ROUTE_STALE: Object.freeze({
+    code: "E_ROUTE_STALE",
+    category: "freshness",
+    classification: "PUBLIC_STABLE",
+    meaning: "Routing result does not match the active contract fingerprint.",
+    safeResolution: "Re-run forgeloop route.",
+  }),
+  E_GATE_STALE: Object.freeze({
+    code: "E_GATE_STALE",
+    category: "freshness",
+    classification: "PUBLIC_STABLE",
+    meaning: "Referenced gate artifact changed after approval.",
+    safeResolution: "Update artifact SHA-256 in gate file.",
+  }),
+  E_VERIFICATION_TOOL_UNAVAILABLE: Object.freeze({
+    code: "E_VERIFICATION_TOOL_UNAVAILABLE",
+    category: "capability",
+    classification: "PUBLIC_STABLE",
+    meaning: "Required verification executable is missing in environment.",
+    safeResolution: "Use local equivalent, obtain host authority, or record NOT_VERIFIED.",
+  }),
+  E_INSTALLATION_AUTHORITY_REQUIRED: Object.freeze({
+    code: "E_INSTALLATION_AUTHORITY_REQUIRED",
+    category: "authority",
+    classification: "PUBLIC_STABLE",
+    meaning: "Attempted software installation without host authority grant.",
+    safeResolution: "Use local non-installing binaries or request host authority grant.",
+  }),
+  E_AUTHORITY_INVALID: Object.freeze({
+    code: "E_AUTHORITY_INVALID",
+    category: "authority",
+    classification: "PUBLIC_STABLE",
+    meaning: "Authority grant file is malformed or expired.",
+    safeResolution: "Obtain a valid authority grant from host operator.",
+  }),
+  E_AUTHORITY_SCOPE_MISMATCH: Object.freeze({
+    code: "E_AUTHORITY_SCOPE_MISMATCH",
+    category: "authority",
+    classification: "PUBLIC_STABLE",
+    meaning: "Authority grant does not cover the requested package.",
+    safeResolution: "Request updated authority scope.",
+  }),
+  E_AUTHORITY_UNTRUSTED_SOURCE: Object.freeze({
+    code: "E_AUTHORITY_UNTRUSTED_SOURCE",
+    category: "authority",
+    classification: "PUBLIC_STABLE",
+    meaning: "Authority file placed inside untrusted project tree.",
+    safeResolution: "Place authority file in host-managed trusted location.",
+  }),
+  E_EXECUTION_REF_INVALID: Object.freeze({
+    code: "E_EXECUTION_REF_INVALID",
+    category: "provenance",
+    classification: "PUBLIC_STABLE",
+    meaning: "Referenced execution ID does not exist.",
+    safeResolution: "Re-run check via forgeloop run-check.",
+  }),
+  E_CHECK_INVALID: Object.freeze({
+    code: "E_CHECK_INVALID",
+    category: "verification",
+    classification: "PUBLIC_STABLE",
+    meaning: "Check structure or required parameters are invalid.",
+    safeResolution: "Provide valid check ID, requirement, and parameters.",
+  }),
+  E_RECEIPT_STATE_MISMATCH: Object.freeze({
+    code: "E_RECEIPT_STATE_MISMATCH",
+    category: "verification",
+    classification: "PUBLIC_STABLE",
+    meaning: "Receipt does not match current state cycle or work state.",
+    safeResolution: "Run forgeloop prepare-completion --json.",
+  }),
+  E_CONTINUITY_RECONCILIATION_REQUIRED: Object.freeze({
+    code: "E_CONTINUITY_RECONCILIATION_REQUIRED",
+    category: "continuity",
+    classification: "PUBLIC_STABLE",
+    meaning: "Continuity context has drifted from work state.",
+    safeResolution: "Run forgeloop reconcile-continuity --json.",
+  }),
+  E_TASK_AMBIGUOUS: Object.freeze({
+    code: "E_TASK_AMBIGUOUS",
+    category: "task-resolution",
+    classification: "PUBLIC_STABLE",
+    meaning: "Multiple tasks exist in the project but no task selector was provided.",
+    safeResolution: "Select a task explicitly using --task <id> or FORGELOOP_TASK=<id>.",
+  }),
+  E_TASK_LOCKED: Object.freeze({
+    code: "E_TASK_LOCKED",
+    category: "concurrency",
+    classification: "PUBLIC_STABLE",
+    meaning: "Task mutation is currently locked by another concurrent process or run-check.",
+    safeResolution: "Wait for the active mutation to complete or inspect the lock with forgeloop task-show.",
+  }),
+  E_TASK_SCOPE_CONFLICT: Object.freeze({
+    code: "E_TASK_SCOPE_CONFLICT",
+    category: "scope",
+    classification: "PUBLIC_STABLE",
+    meaning: "Task write claims overlap with another non-complete task in the same checkout.",
+    safeResolution: "Adjust write claims to non-overlapping paths or run tasks in separate worktrees.",
+  }),
+  E_TASK_SCOPE_DIRTY: Object.freeze({
+    code: "E_TASK_SCOPE_DIRTY",
+    category: "scope",
+    classification: "PUBLIC_STABLE",
+    meaning: "Claimed paths contain pre-existing uncommitted changes.",
+    safeResolution: "Commit or stash changes in claimed paths before defining or adopting the scope.",
+  }),
+  E_TASK_CHANGE_OUTSIDE_SCOPE: Object.freeze({
+    code: "E_TASK_CHANGE_OUTSIDE_SCOPE",
+    category: "scope",
+    classification: "PUBLIC_STABLE",
+    meaning: "Modified paths in repository exceed the declared task write claims.",
+    safeResolution: "Update write claims with forgeloop task-scope or revert out-of-scope modifications.",
+  }),
+});
+
+export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
+  ...FAILURE_CODES,
+  E_VERIFICATION_TOOL_UNAVAILABLE,
+  E_INSTALLATION_AUTHORITY_REQUIRED,
+  E_COMMAND_RESOLUTION_AMBIGUOUS,
+  E_AUTHORITY_INVALID,
+  E_AUTHORITY_SCOPE_MISMATCH,
+  "E_AUTHORITY_UNTRUSTED_SOURCE",
+  "E_EXECUTION_REF_INVALID",
+  "E_NATIVE_ADAPTER_STALE",
+  "E_NATIVE_ADAPTER_TARGET_MISSING",
+  "E_MIGRATION_INCOMPLETE",
+  "E_MIGRATION_WRITE_VERIFY",
+  E_TASK_REQUIRED,
+  E_TASK_NOT_FOUND,
+  E_TASK_ALREADY_EXISTS,
+  E_TASK_AMBIGUOUS,
+  E_TASK_SELECTOR_CONFLICT,
+  E_TASK_DESCRIPTOR_INVALID,
+  E_TASK_KEY_MISMATCH,
+  E_TASK_CONTEXT_MISMATCH,
+  E_TASK_LOCKED,
+  E_TASK_LOCK_INVALID,
+  E_TASK_SCOPE_REQUIRED,
+  E_TASK_SCOPE_CONFLICT,
+  E_TASK_SCOPE_DIRTY,
+  E_TASK_SCOPE_FROZEN,
+  E_TASK_CHANGE_OUTSIDE_SCOPE,
+  E_TASK_CHANGE_ATTRIBUTION_UNAVAILABLE,
+  E_TASK_LAYOUT_LEGACY,
+  E_TASK_MIGRATION_INVALID,
+  E_TASK_MIGRATION_IDENTITY_MISMATCH,
+]));

package/src/core/events.js

@@ -1,4 +1,4 @@
-import { createHash, randomUUID } from "node:crypto";
+
 import { appendFile, mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
 
@@ -10,6 +10,8 @@ import { assertSecretFree } from "./receipt.js";
 import { PROTOCOL_VERSION } from "./protocol.js";
 import { isRecoverableCompletionEvidenceCode } from "./completion-recovery.js";
 
+import { taskArtifactPath } from "./task-paths.js";
+
 const EVENT_SCHEMA_VERSION = 1;
 export const LIFECYCLE_MILESTONES = Object.freeze([
   "CONTRACT_VALIDATED",
@@ -47,22 +49,23 @@ function protocolError(code, message, artifacts = [ARTIFACT_PATHS.events]) {
   return error;
 }
 
-async function readEvents(target, packageRoot) {
-  await assertSafePath(target, ARTIFACT_PATHS.events);
-  const eventsPath = ensureWithin(target, ARTIFACT_PATHS.events);
+export async function readEvents(target, packageRoot, options = {}) {
+  const relPath = options?.eventsPath ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "events") : ARTIFACT_PATHS.events);
+  await assertSafePath(target, relPath);
+  const eventsPath = ensureWithin(target, relPath);
   if (!(await fileExists(eventsPath))) return [];
   const text = await readFile(eventsPath, "utf8");
-  assertJsonBytes(text, ARTIFACT_PATHS.events);
+  assertJsonBytes(text, relPath);
   const schema = await readSchema("event", packageRoot);
   const lines = text.split(/\r?\n/).filter((line) => line.trim() !== "");
   return lines.map((line, index) => {
     let event;
     try {
       event = JSON.parse(line);
-      assertJsonLimits(event, `${ARTIFACT_PATHS.events}[${index}]`);
-      assertSchema(event, schema, `${ARTIFACT_PATHS.events}[${index}]`);
+      assertJsonLimits(event, `${relPath}[${index}]`);
+      assertSchema(event, schema, `${relPath}[${index}]`);
     } catch (error) {
-      throw protocolError("E_EVENT_INVALID", `${ARTIFACT_PATHS.events} line ${index + 1}: ${error.message}`);
+      throw protocolError("E_EVENT_INVALID", `${relPath} line ${index + 1}: ${error.message}`, [relPath]);
     }
     return event;
   });
@@ -71,7 +74,8 @@ async function readEvents(target, packageRoot) {
 export async function appendProtocolEvent(target, input, packageRoot, options = {}) {
   if (typeof input?.taskId !== "string" || !input.taskId) throw protocolError("E_EVENT_INVALID", "event taskId is required");
   if (typeof input?.event !== "string" || !input.event) throw protocolError("E_EVENT_INVALID", "event type is required");
-  const events = await readEvents(target, packageRoot);
+  const relPath = options?.eventsPath ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "events") : ARTIFACT_PATHS.events);
+  const events = await readEvents(target, packageRoot, { ...options, eventsPath: relPath });
   const previous = events.at(-1) ?? null;
   const event = {
     seq: events.length + 1,
@@ -86,9 +90,9 @@ export async function appendProtocolEvent(target, input, packageRoot, options =
   };
   assertSecretFree(event);
   const schema = await readSchema("event", packageRoot);
-  assertSchema(event, schema, ARTIFACT_PATHS.events);
+  assertSchema(event, schema, relPath);
   event.hash = eventHash(event);
-  const eventsPath = ensureWithin(target, ARTIFACT_PATHS.events);
+  const eventsPath = ensureWithin(target, relPath);
   if (!options.dryRun) {
     await mkdir(path.dirname(eventsPath), { recursive: true });
     await appendFile(eventsPath, `${JSON.stringify(event)}\n`, { encoding: "utf8" });
@@ -96,12 +100,13 @@ export async function appendProtocolEvent(target, input, packageRoot, options =
   return event;
 }
 
-export async function validateEventLedger(target, packageRoot) {
+export async function validateEventLedger(target, packageRoot, options = {}) {
+  const relPath = options?.eventsPath ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "events") : ARTIFACT_PATHS.events);
   let events;
   try {
-    events = await readEvents(target, packageRoot);
+    events = await readEvents(target, packageRoot, { ...options, eventsPath: relPath });
   } catch (error) {
-    return { valid: false, events: [], errors: [{ code: error.code ?? "E_EVENT_INVALID", message: error.message }] };
+    return { valid: false, events: [], errors: [{ code: error.code ?? "E_EVENT_INVALID", message: error.message, artifacts: [relPath] }] };
   }
   const errors = [];
   let taskId = null;

package/src/core/execution.js

@@ -1,14 +1,16 @@
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
-
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileExists } from "./filesystem.js";
 import {
   ARTIFACT_PATHS,
   executionArtifactPath,
   readJsonArtifact,
   writeJsonArtifact,
 } from "./artifacts.js";
+import { taskExecutionPath } from "./task-paths.js";
 import {
-  classifyCommandResolution,
   resolveExecutionResolution,
   validateVerificationAuthority,
   E_COMMAND_RESOLUTION_AMBIGUOUS,
@@ -86,6 +88,7 @@ export async function runCommandExecution({
   details,
   authorityContext,
   runtimeContext,
+  executionPath,
 } = {}) {
   const commandArgv = normalizeArgv(argv);
   const resolution = await resolveExecutionResolution({
@@ -150,8 +153,8 @@ export async function runCommandExecution({
     status: processResult.exitCode === 0 && !processResult.spawnError ? "passed" : "failed",
     exitCode: processResult.exitCode,
   };
-  const path = executionArtifactPath(executionId);
-  const written = await writeJsonArtifact(target, path, execution, "execution", packageRoot);
+  const execPath = executionPath ?? (taskId ? taskExecutionPath(taskId, executionId) : executionArtifactPath(executionId));
+  const written = await writeJsonArtifact(target, execPath, execution, "execution", packageRoot);
   return {
     path: written.path,
     execution: written.value,
@@ -161,14 +164,43 @@ export async function runCommandExecution({
   };
 }
 
-export async function readExecutionArtifact({ target, executionRef, packageRoot } = {}) {
+export async function readExecutionArtifact({ target, executionRef, packageRoot, taskId } = {}) {
   let relativePath;
   try {
-    relativePath = executionArtifactPath(executionRef);
+    relativePath = taskId ? taskExecutionPath(taskId, executionRef) : executionArtifactPath(executionRef);
     const artifact = await readJsonArtifact(target, relativePath, "execution", packageRoot);
     return artifact;
   } catch (error) {
     if (error.code === "E_EXECUTION_REF_INVALID") throw error;
+    if (error.code === "ARTIFACT_MISSING") {
+      if (taskId) {
+        try {
+          const fallbackPath = executionArtifactPath(executionRef);
+          const artifact = await readJsonArtifact(target, fallbackPath, "execution", packageRoot);
+          return artifact;
+        } catch {
+          // ignore fallback failure
+        }
+      } else {
+        try {
+          const taskStateDir = path.join(target, ".forgeloop", "task-state");
+          if (await fileExists(taskStateDir)) {
+            const entries = await readdir(taskStateDir, { withFileTypes: true });
+            for (const entry of entries) {
+              if (entry.isDirectory()) {
+                const execFile = path.join(taskStateDir, entry.name, "executions", `${executionRef}.json`);
+                if (await fileExists(execFile)) {
+                  const rel = path.relative(target, execFile).replaceAll("\\", "/");
+                  return await readJsonArtifact(target, rel, "execution", packageRoot);
+                }
+              }
+            }
+          }
+        } catch {
+          // ignore scan failure
+        }
+      }
+    }
     throw executionError("E_EXECUTION_REF_INVALID", "Execution reference does not resolve to a valid ForgeLoop artifact", [relativePath ?? ARTIFACT_PATHS.executionDirectory]);
   }
 }

package/src/core/gate-artifact.js

@@ -1,9 +1,8 @@
-import path from "node:path";
-
 import { assertSafePath, ensureWithin, fileExists, readBytes } from "./filesystem.js";
 import { ARTIFACT_PATHS, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
 import { assertSchema, readSchema } from "./schema-validation.js";
 import { sha256 } from "./manifest.js";
+import { taskGatePath } from "./task-paths.js";
 
 function gateName(value) {
   if (typeof value !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(value)) {
@@ -14,22 +13,26 @@ function gateName(value) {
   return value;
 }
 
-export function gatePath(gate) {
-  return `${ARTIFACT_PATHS.gates ?? ".forgeloop/gates"}/${gateName(gate)}.json`;
+export function gatePath(gate, options = {}) {
+  const name = gateName(gate);
+  if (options?.taskId) {
+    return taskGatePath(options.taskId, name);
+  }
+  return `${ARTIFACT_PATHS.gates ?? ".forgeloop/gates"}/${name}.json`;
 }
 
 export async function persistGate(target, gate, packageRoot, options = {}) {
-  const relativePath = gatePath(gate.gate);
+  const relativePath = options?.gatePath ?? (options?.taskId ? taskGatePath(options.taskId, gate.gate) : gatePath(gate.gate, options));
   return writeJsonArtifact(target, relativePath, gate, "gate", packageRoot, options);
 }
 
-export async function readGate(target, gate, packageRoot) {
-  const relativePath = gatePath(gate);
+export async function readGate(target, gate, packageRoot, options = {}) {
+  const relativePath = options?.gatePath ?? (options?.taskId ? taskGatePath(options.taskId, gate) : gatePath(gate, options));
   return readJsonArtifact(target, relativePath, "gate", packageRoot);
 }
 
-export async function readGateIfPresent(target, gate, packageRoot) {
-  const relativePath = gatePath(gate);
+export async function readGateIfPresent(target, gate, packageRoot, options = {}) {
+  const relativePath = options?.gatePath ?? (options?.taskId ? taskGatePath(options.taskId, gate) : gatePath(gate, options));
   await assertSafePath(target, relativePath);
   const filePath = ensureWithin(target, relativePath);
   if (!(await fileExists(filePath))) return null;

package/src/core/gates.js

@@ -50,6 +50,8 @@ export function createGate(input = {}) {
   };
 }
 
-export function requiredGatePaths(gates) {
-  return [...new Set(gates)].sort().map((gate) => `.forgeloop/gates/${gate}.json`);
+import { taskGatePath } from "./task-paths.js";
+
+export function requiredGatePaths(gates, { taskId } = {}) {
+  return [...new Set(gates)].sort().map((gate) => (taskId ? taskGatePath(taskId, gate) : `.forgeloop/gates/${gate}.json`));
 }

package/src/core/guide-metadata.js

@@ -1,17 +1,7 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 
-const GUIDE_FILES = Object.freeze({
-  premium: "ENG/premium-sites-studio-eng.md",
-  taste: "ENG/taste-frontend-eng.md",
-  clean: "ENG/clean-code-eng.md",
-  test: "ENG/test-code-eng.md",
-  security: "ENG/sec-code-eng.md",
-  design: "ENG/design-code-eng.md",
-  performance: "ENG/perf-code-eng.md",
-  accessibility: "ENG/accessibility-eng.md",
-  games: "ENG/games-code-design-web-eng.md",
-});
+import { GUIDE_FILES } from "./guide-registry.js";
 
 function parseList(frontmatter, key) {
   const lines = frontmatter.split(/\r?\n/);
@@ -30,8 +20,12 @@ function parseFrontmatter(text, relativePath) {
   if (!match) throw new Error(`${relativePath} is missing YAML frontmatter`);
   const frontmatter = match[1];
   const guideId = frontmatter.match(/^guide-id:\s*([^\s]+)\s*$/m)?.[1] ?? null;
+  const lastReviewed = frontmatter.match(/^last-reviewed:\s*"?([^"\r\n]+)"?\s*$/m)?.[1] ?? null;
+  const version = frontmatter.match(/^version:\s*"?([^"\r\n]+)"?\s*$/m)?.[1] ?? null;
   return {
     guideId,
+    lastReviewed,
+    version,
     requiresGates: parseList(frontmatter, "requires-gates"),
     completionEvidence: parseList(frontmatter, "completion-evidence"),
   };
@@ -44,6 +38,8 @@ export async function readGuideMetadata(packageRoot) {
     const parsed = parseFrontmatter(text, relativePath);
     metadata[id] = {
       guideId: parsed.guideId ?? id,
+      lastReviewed: parsed.lastReviewed,
+      version: parsed.version,
       requiresGates: [...parsed.requiresGates],
       completionEvidence: [...parsed.completionEvidence],
       path: relativePath,

package/src/core/guide-registry.js

@@ -0,0 +1,29 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const currentDir = path.dirname(fileURLToPath(import.meta.url));
+const rawGuides = JSON.parse(
+  readFileSync(path.resolve(currentDir, "../config/guides.json"), "utf8"),
+);
+
+export const GUIDE_REGISTRY = Object.freeze(
+  Object.fromEntries(
+    Object.entries(rawGuides).map(([id, def]) => [
+      id,
+      Object.freeze({ id, ...def }),
+    ]),
+  ),
+);
+
+export const GUIDE_IDS = Object.freeze(Object.keys(GUIDE_REGISTRY));
+
+export const GUIDE_FILES = Object.freeze(
+  Object.fromEntries(Object.entries(GUIDE_REGISTRY).map(([id, def]) => [id, def.path])),
+);
+
+export const GUIDE_TEMPLATE_PATHS = Object.freeze(
+  Object.values(GUIDE_REGISTRY)
+    .filter((def) => def.install)
+    .map((def) => def.path),
+);

package/src/core/inspect.js

@@ -20,7 +20,9 @@ function profileMetadata(bytes) {
   };
 }
 
-export async function inspectTarget({ target, packageRoot, contractFile = null, authorityContext, runtimeContext }) {
+import { taskArtifactPath } from "./task-paths.js";
+
+export async function inspectTarget({ target, packageRoot, contractFile = null, authorityContext, runtimeContext, taskId = null, stateFile = null } = {}) {
   let manifest = null;
   let manifestError = null;
   try {
@@ -34,10 +36,11 @@ export async function inspectTarget({ target, packageRoot, contractFile = null,
   const profile = (profilePath && await fileExists(profilePath))
     ? { ...profileMetadata(await readBytes(profilePath)), path: profileRelativePath }
     : { mode: null, status: null };
-  const statePath = ensureWithin(target, WORK_STATE_PATH);
+  const effectiveStateRel = stateFile ?? (taskId ? taskArtifactPath(taskId, "state") : WORK_STATE_PATH);
+  const statePath = ensureWithin(target, effectiveStateRel);
   const statePresent = await fileExists(statePath);
-  const state = await readAndClassifyWorkState({ target, packageRoot, contractFile });
-  const continuity = await reconcileContinuity({ target, packageRoot });
+  const state = await readAndClassifyWorkState({ target, packageRoot, contractFile, taskId, stateFile: effectiveStateRel });
+  const continuity = await reconcileContinuity({ target, packageRoot, taskId });
   const schemaRoot = manifest?.layoutVersion >= 2
     ? ensureWithin(target, FORGELOOP_KIT_DIR)
     : target;

package/src/core/native-adapters.js

@@ -40,6 +40,12 @@ Read and follow:
 Before changing product or executable files, establish the ForgeLoop contract,
 route, required gates, and READY preflight.
 
+Before creating or activating new lifecycle state:
+If \`.forgeloop/work-state.json\` exists, inspect the existing task,
+reconcile continuity when present, inspect the checkout, and run
+\`forgeloop next\`. A change of harness, model, provider, IDE, process,
+terminal, or session does not create a new task.
+
 Use the project-local ForgeLoop CLI for lifecycle-owned protocol state.
 Never manually synthesize lifecycle chronology or assign ForgeLoop COMPLETE.