@cassiomc1/forgeloop 1.0.0 → 1.1.0

package/src/core/task-paths.js

@@ -0,0 +1,96 @@
+import { assertTaskId, taskStorageKey } from "./task-identity.js";
+
+export const TASK_STATE_ROOT = ".forgeloop/task-state";
+export const SESSIONS_ROOT = ".forgeloop/sessions";
+
+export const TASK_ARTIFACT_FILES = Object.freeze({
+  descriptor: "task.json",
+  contract: "contract.json",
+  route: "routing-result.json",
+  preflight: "preflight.json",
+  state: "work-state.json",
+  continuity: "continuity.json",
+  receipt: "execution-receipt.json",
+  events: "events.ndjson",
+  gates: "gates",
+  executions: "executions",
+  lock: ".lock",
+});
+
+export const PROJECT_ARTIFACT_PATHS = Object.freeze({
+  config: ".forgeloop/config.json",
+  sources: ".forgeloop/sources.json",
+  manifest: ".forgeloop/.manifest.json",
+  kit: ".forgeloop/kit",
+  gitignore: ".forgeloop/.gitignore",
+});
+
+export const LEGACY_TASK_ARTIFACT_PATHS = Object.freeze({
+  contract: ".forgeloop/current-contract.json",
+  route: ".forgeloop/routing-result.json",
+  preflight: ".forgeloop/preflight.json",
+  state: ".forgeloop/work-state.json",
+  continuity: ".forgeloop/continuity.json",
+  receipt: ".forgeloop/execution-receipt.json",
+  events: ".forgeloop/events.ndjson",
+  gates: ".forgeloop/gates",
+  executions: ".forgeloop/executions",
+  session: ".forgeloop/session.json",
+});
+
+export function taskDirectory(taskId) {
+  return `${TASK_STATE_ROOT}/${taskStorageKey(taskId)}`;
+}
+
+export function taskArtifactPath(taskId, key) {
+  const relative = TASK_ARTIFACT_FILES[key];
+  if (!relative) {
+    throw new Error(`Unknown task artifact: ${key}`);
+  }
+  return `${taskDirectory(taskId)}/${relative}`;
+}
+
+export function taskGatePath(taskId, gateId) {
+  if (typeof gateId !== "string" || !gateId || gateId.includes("/") || gateId.includes("\\") || gateId.includes("..")) {
+    throw new Error(`Invalid gate ID: ${gateId}`);
+  }
+  const cleanId = gateId.endsWith(".json") ? gateId : `${gateId}.json`;
+  return `${taskDirectory(taskId)}/${TASK_ARTIFACT_FILES.gates}/${cleanId}`;
+}
+
+export function taskExecutionPath(taskId, executionId) {
+  if (typeof executionId !== "string" || !/^exec-[A-Za-z0-9_-]+$/.test(executionId)) {
+    throw new Error(`Invalid execution ID: ${executionId}`);
+  }
+  return `${taskDirectory(taskId)}/${TASK_ARTIFACT_FILES.executions}/${executionId}.json`;
+}
+
+export function taskLockPath(taskId) {
+  return taskArtifactPath(taskId, "lock");
+}
+
+export function sessionArtifactPath(sessionId) {
+  if (typeof sessionId !== "string" || !sessionId || sessionId.includes("/") || sessionId.includes("\\") || sessionId.includes("..")) {
+    throw new Error(`Invalid session ID: ${sessionId}`);
+  }
+  const cleanId = sessionId.endsWith(".json") ? sessionId : `${sessionId}.json`;
+  return `${SESSIONS_ROOT}/${cleanId}`;
+}
+
+export function buildTaskArtifactPaths(taskId) {
+  assertTaskId(taskId);
+  const dir = taskDirectory(taskId);
+  return Object.freeze({
+    descriptor: `${dir}/${TASK_ARTIFACT_FILES.descriptor}`,
+    contract: `${dir}/${TASK_ARTIFACT_FILES.contract}`,
+    route: `${dir}/${TASK_ARTIFACT_FILES.route}`,
+    preflight: `${dir}/${TASK_ARTIFACT_FILES.preflight}`,
+    state: `${dir}/${TASK_ARTIFACT_FILES.state}`,
+    continuity: `${dir}/${TASK_ARTIFACT_FILES.continuity}`,
+    receipt: `${dir}/${TASK_ARTIFACT_FILES.receipt}`,
+    events: `${dir}/${TASK_ARTIFACT_FILES.events}`,
+    gates: `${dir}/${TASK_ARTIFACT_FILES.gates}`,
+    executions: `${dir}/${TASK_ARTIFACT_FILES.executions}`,
+    lock: `${dir}/${TASK_ARTIFACT_FILES.lock}`,
+  });
+}

package/src/core/task-scope.js

@@ -0,0 +1,179 @@
+import path from "node:path";
+import {
+  E_TASK_CHANGE_OUTSIDE_SCOPE,
+  E_TASK_DESCRIPTOR_INVALID,
+  E_TASK_SCOPE_CONFLICT,
+  E_TASK_SCOPE_DIRTY,
+  E_TASK_SCOPE_FROZEN,
+} from "./error-codes.js";
+import { currentChangedPaths } from "./repository.js";
+
+const FROZEN_PHASES = new Set([
+  "EXECUTING",
+  "VERIFYING",
+  "DIAGNOSING",
+  "CORRECTING",
+  "REVIEWING",
+  "COMPLETE",
+]);
+
+export function normalizeWriteClaim(claim) {
+  if (typeof claim !== "string" || claim.trim() === "") {
+    const error = new Error("Write claim must be a non-empty string");
+    error.code = E_TASK_DESCRIPTOR_INVALID;
+    throw error;
+  }
+
+  const portable = claim.trim().replaceAll("\\", "/");
+  if (portable.startsWith("/") || /^[A-Za-z]:\//.test(portable)) {
+    const error = new Error(`Write claim must remain relative: ${claim}`);
+    error.code = E_TASK_DESCRIPTOR_INVALID;
+    throw error;
+  }
+
+  const normalized = path.posix.normalize(portable);
+  if (normalized === ".." || normalized.startsWith("../")) {
+    const error = new Error(`Write claim escapes project directory: ${claim}`);
+    error.code = E_TASK_DESCRIPTOR_INVALID;
+    throw error;
+  }
+
+  if (normalized === "." || normalized === "./") {
+    return ".";
+  }
+
+  return normalized.replace(/^\.\//, "").replace(/\/+$/, "");
+}
+
+export function normalizeWriteClaims(claims) {
+  if (claims === undefined || claims === null) {
+    return [];
+  }
+  if (!Array.isArray(claims)) {
+    const error = new Error("writeClaims must be an array of string prefixes");
+    error.code = E_TASK_DESCRIPTOR_INVALID;
+    throw error;
+  }
+
+  const normalized = claims.map((c) => normalizeWriteClaim(c));
+  const unique = [...new Set(normalized)];
+  return unique.sort((a, b) => a.localeCompare(b));
+}
+
+export function claimsOverlap(claimA, claimB) {
+  const normA = normalizeWriteClaim(claimA).toLowerCase();
+  const normB = normalizeWriteClaim(claimB).toLowerCase();
+
+  if (normA === "." || normB === ".") {
+    return true;
+  }
+
+  if (normA === normB) {
+    return true;
+  }
+
+  if (normA.startsWith(`${normB}/`)) {
+    return true;
+  }
+
+  if (normB.startsWith(`${normA}/`)) {
+    return true;
+  }
+
+  return false;
+}
+
+export function checkScopeConflicts(newClaims, existingTasks = [], currentTaskId = null) {
+  const normalizedNew = normalizeWriteClaims(newClaims);
+  if (normalizedNew.length === 0) return [];
+
+  const conflicts = [];
+  for (const task of existingTasks) {
+    if (task.taskId === currentTaskId) continue;
+    // Only non-COMPLETE tasks hold active write claims
+    if (task.phase === "COMPLETE") continue;
+
+    const taskClaims = normalizeWriteClaims(task.writeClaims ?? task.descriptor?.writeClaims ?? []);
+    for (const newClaim of normalizedNew) {
+      for (const existingClaim of taskClaims) {
+        if (claimsOverlap(newClaim, existingClaim)) {
+          conflicts.push({
+            taskId: task.taskId,
+            phase: task.phase,
+            conflictingClaim: existingClaim,
+            requestedClaim: newClaim,
+          });
+        }
+      }
+    }
+  }
+
+  return conflicts;
+}
+
+export function assertNoScopeConflicts(newClaims, existingTasks = [], currentTaskId = null) {
+  const conflicts = checkScopeConflicts(newClaims, existingTasks, currentTaskId);
+  if (conflicts.length > 0) {
+    const first = conflicts[0];
+    const error = new Error(
+      `Task write claim "${first.requestedClaim}" conflicts with active task "${first.taskId}" (claim "${first.conflictingClaim}", phase: ${first.phase ?? "PLANNED"})`,
+    );
+    error.code = E_TASK_SCOPE_CONFLICT;
+    error.conflicts = conflicts;
+    throw error;
+  }
+}
+
+export async function assertScopeClean(target, claims) {
+  const normalized = normalizeWriteClaims(claims);
+  if (normalized.length === 0) return;
+
+  const changed = await currentChangedPaths(target, { paths: normalized });
+  if (changed !== null && changed.length > 0) {
+    const error = new Error(
+      `Claimed scope contains pre-existing uncommitted changes: ${changed.slice(0, 5).join(", ")}${changed.length > 5 ? "..." : ""}`,
+    );
+    error.code = E_TASK_SCOPE_DIRTY;
+    error.changedPaths = changed;
+    throw error;
+  }
+}
+
+export function assertScopeNotFrozen(phase) {
+  if (phase && FROZEN_PHASES.has(phase)) {
+    const error = new Error(
+      `Task scope cannot be modified once execution lifecycle has started (current phase: ${phase})`,
+    );
+    error.code = E_TASK_SCOPE_FROZEN;
+    throw error;
+  }
+}
+
+export function assertClaimsCoverChangedPaths(claims, changedPaths) {
+  const normalizedClaims = normalizeWriteClaims(claims);
+  if (normalizedClaims.length === 0) return;
+
+  // Root claim covers everything
+  if (normalizedClaims.includes(".")) return;
+
+  const outOfScope = [];
+  for (const changedPath of changedPaths ?? []) {
+    const normPath = changedPath.replaceAll("\\", "/").replace(/^\.\//, "").toLowerCase();
+    const covered = normalizedClaims.some((claim) => {
+      const normClaim = claim.toLowerCase();
+      return normPath === normClaim || normPath.startsWith(`${normClaim}/`);
+    });
+    if (!covered) {
+      outOfScope.push(changedPath);
+    }
+  }
+
+  if (outOfScope.length > 0) {
+    const error = new Error(
+      `Observed repository changes exceed task write claims: ${outOfScope.slice(0, 5).join(", ")}${outOfScope.length > 5 ? "..." : ""}`,
+    );
+    error.code = E_TASK_CHANGE_OUTSIDE_SCOPE;
+    error.outOfScopePaths = outOfScope;
+    throw error;
+  }
+}

package/src/core/templates.js

@@ -8,6 +8,7 @@ import {
   targetPathForSource,
 } from "./target-layout.js";
 import { nativeShim } from "./native-adapters.js";
+import { GUIDE_TEMPLATE_PATHS } from "./guide-registry.js";
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 
@@ -37,15 +38,7 @@ export const TEMPLATE_PATHS = [
   "THIRD_PARTY_NOTICES.md",
   "LICENSE",
   "LICENSE-DOCS.md",
-  "ENG/accessibility-eng.md",
-  "ENG/clean-code-eng.md",
-  "ENG/design-code-eng.md",
-  "ENG/games-code-design-web-eng.md",
-  "ENG/perf-code-eng.md",
-  "ENG/premium-sites-studio-eng.md",
-  "ENG/taste-frontend-eng.md",
-  "ENG/sec-code-eng.md",
-  "ENG/test-code-eng.md",
+  ...GUIDE_TEMPLATE_PATHS,
   "schemas/routing-input.schema.json",
   "schemas/routing-result.schema.json",
   "schemas/work-state.schema.json",
@@ -67,6 +60,7 @@ export const TEMPLATE_PATHS = [
   "schemas/policy.schema.json",
   "schemas/task-bundle.schema.json",
   "schemas/authority.schema.json",
+  "schemas/task-descriptor.schema.json",
 ];
 
 export function getPackageRoot() {

package/src/core/work-state.js

@@ -18,6 +18,7 @@ import { createEvidence } from "./evidence.js";
 import { assertJsonBytes } from "./json-safety.js";
 import { assertCoverageList } from "./coverage.js";
 import { canonicalFingerprint } from "./artifacts.js";
+import { taskArtifactPath } from "./task-paths.js";
 
 export const WORK_STATE_PATH = ".forgeloop/work-state.json";
 
@@ -229,17 +230,22 @@ async function validateStoredState(state, packageRoot = getPackageRoot()) {
   return assertWorkStateSemantics(state);
 }
 
-export async function readWorkState(target, packageRoot = getPackageRoot()) {
-  await assertSafePath(target, WORK_STATE_PATH);
-  const statePath = ensureWithin(target, WORK_STATE_PATH);
+export async function readWorkState(target, options = {}) {
+  const packageRoot = typeof options === "string" ? options : (options?.packageRoot ?? getPackageRoot());
+  const relPath = typeof options === "object" && options !== null
+    ? (options.statePath ?? options.relativePath ?? (options.taskId ? taskArtifactPath(options.taskId, "state") : (options.taskContext ? options.taskContext.paths.state : WORK_STATE_PATH)))
+    : WORK_STATE_PATH;
+
+  await assertSafePath(target, relPath);
+  const statePath = ensureWithin(target, relPath);
   if (!(await fileExists(statePath))) return null;
   let state;
   try {
     const bytes = await readBytes(statePath);
-    assertJsonBytes(bytes, WORK_STATE_PATH);
+    assertJsonBytes(bytes, relPath);
     state = JSON.parse(bytes.toString("utf8"));
   } catch (error) {
-    throw new WorkStateError(`Unable to parse ${WORK_STATE_PATH}: ${error.message}`);
+    throw new WorkStateError(`Unable to parse ${relPath}: ${error.message}`);
   }
   try {
     return await validateStoredState(state, packageRoot);
@@ -263,20 +269,25 @@ export async function readContractFingerprint(target, contractFile) {
   return { path: contractFile, fingerprint: contractFingerprint(contract) };
 }
 
-export async function writeWorkState(target, state, { dryRun = false, packageRoot = getPackageRoot() } = {}) {
+export async function writeWorkState(target, state, options = {}) {
+  const packageRoot = options?.packageRoot ?? getPackageRoot();
+  const dryRun = options?.dryRun ?? false;
+  const relPath = options?.statePath ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "state") : WORK_STATE_PATH);
+
   await validateStoredState(state, packageRoot);
-  await assertSafePath(target, WORK_STATE_PATH);
-  const statePath = ensureWithin(target, WORK_STATE_PATH);
+  await assertSafePath(target, relPath);
+  const statePath = ensureWithin(target, relPath);
   await writeFileAtomic(statePath, `${JSON.stringify(state, null, 2)}\n`, { dryRun });
   return state;
 }
 
-export async function clearWorkState(target) {
-  await assertSafePath(target, WORK_STATE_PATH);
-  const statePath = ensureWithin(target, WORK_STATE_PATH);
-  if (!(await fileExists(statePath))) return { removed: false, path: WORK_STATE_PATH };
+export async function clearWorkState(target, options = {}) {
+  const relPath = options?.statePath ?? options?.relativePath ?? (options?.taskId ? taskArtifactPath(options.taskId, "state") : WORK_STATE_PATH);
+  await assertSafePath(target, relPath);
+  const statePath = ensureWithin(target, relPath);
+  if (!(await fileExists(statePath))) return { removed: false, path: relPath };
   await unlink(statePath);
-  return { removed: true, path: WORK_STATE_PATH };
+  return { removed: true, path: relPath };
 }
 
 export async function readRequiredArtifactFingerprints(target, artifacts) {