@cassiomc1/forgeloop 0.1.1 → 0.1.2

package/src/core/contract.js

@@ -0,0 +1,141 @@
+import { PROTOCOL_VERSION } from "./protocol.js";
+import { ARTIFACT_PATHS, canonicalFingerprint, readJsonArtifact, writeJsonArtifact } from "./artifacts.js";
+import { assertSchema, readSchema } from "./schema-validation.js";
+import { assertSecretFree } from "./receipt.js";
+
+export const CONTRACT_SCHEMA_VERSION = 1;
+
+const CONTRACT_ARRAY_FIELDS = Object.freeze([
+  "deliverables",
+  "constraints",
+  "risks",
+  "verification",
+  "successCriteria",
+  "stopConditions",
+  "unresolvedDecisions",
+  "sourceRefs",
+]);
+
+function assertStringArray(value, label) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim() === "")) {
+    throw new Error(`${label} must be an array of non-empty strings`);
+  }
+}
+
+const ASSUMPTION_FIELDS = Object.freeze([
+  "value",
+  "reason",
+  "scope",
+  "reversible",
+  "source",
+]);
+
+function assertAssumptionObject(value, label) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be a plain object`);
+  }
+
+  const keys = Object.keys(value);
+  const unexpected = keys.filter((key) => !ASSUMPTION_FIELDS.includes(key));
+  if (unexpected.length > 0) {
+    throw new Error(`${label} contains unknown property: ${unexpected[0]}`);
+  }
+
+  for (const field of ASSUMPTION_FIELDS) {
+    if (!Object.prototype.hasOwnProperty.call(value, field)) {
+      throw new Error(`${label}.${field} is required`);
+    }
+  }
+
+  if (typeof value.value !== "string" || value.value.trim() === "") {
+    throw new Error(`${label}.value must be a non-empty string`);
+  }
+  if (typeof value.reason !== "string" || value.reason.trim() === "") {
+    throw new Error(`${label}.reason must be a non-empty string`);
+  }
+  if (typeof value.scope !== "string" || value.scope.trim() === "") {
+    throw new Error(`${label}.scope must be a non-empty string`);
+  }
+  if (value.reversible !== true) {
+    throw new Error(`${label}.reversible must be true`);
+  }
+  if (value.source !== "agent-default") {
+    throw new Error(`${label}.source must be agent-default`);
+  }
+}
+
+export function assertAssumptions(value, label = "Contract assumptions") {
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array`);
+  }
+  value.forEach((item, index) => {
+    assertAssumptionObject(item, `${label}[${index}]`);
+  });
+  return value;
+}
+
+export function createContract(input = {}) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("Contract must be a JSON object");
+  }
+  if (typeof input.taskId !== "string" || input.taskId.trim() === "") {
+    throw new Error("Contract taskId is required");
+  }
+  if (typeof input.objective !== "string" || input.objective.trim() === "") {
+    throw new Error("Contract objective is required");
+  }
+
+  const contract = {
+    schemaVersion: CONTRACT_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    taskId: input.taskId,
+    objective: input.objective,
+    assumptions: [],
+  };
+  assertAssumptions(input.assumptions ?? []);
+  for (const field of CONTRACT_ARRAY_FIELDS) {
+    const value = input[field] ?? [];
+    assertStringArray(value, `Contract ${field}`);
+    contract[field] = [...value];
+  }
+  contract.assumptions = (input.assumptions ?? []).map((assumption) => ({
+    value: assumption.value,
+    reason: assumption.reason,
+    scope: assumption.scope,
+    reversible: assumption.reversible,
+    source: assumption.source,
+  }));
+  assertSecretFree(contract);
+  return contract;
+}
+
+export function contractFingerprint(contract) {
+  return canonicalFingerprint(contract);
+}
+
+export async function validateContract(contract, packageRoot) {
+  assertSecretFree(contract);
+  assertAssumptions(contract.assumptions ?? []);
+  const schema = await readSchema("current-contract", packageRoot);
+  assertSchema(contract, schema, "current contract");
+  return contract;
+}
+
+export async function readContract(target, packageRoot) {
+  const artifact = await readJsonArtifact(target, ARTIFACT_PATHS.contract, "current-contract", packageRoot);
+  await validateContract(artifact.value, packageRoot);
+  return artifact;
+}
+
+export async function writeContract(target, contract, packageRoot, options = {}) {
+  assertSecretFree(contract);
+  assertAssumptions(contract.assumptions ?? []);
+  return writeJsonArtifact(
+    target,
+    ARTIFACT_PATHS.contract,
+    contract,
+    "current-contract",
+    packageRoot,
+    options,
+  );
+}

package/src/core/coverage.js

@@ -0,0 +1,89 @@
+import { PROTOCOL_VERSION } from "./protocol.js";
+
+export const COVERAGE_SCHEMA_VERSION = 1;
+export const COVERAGE_STATUSES = Object.freeze(["COVERED", "PARTIAL", "NOT_VERIFIED", "BLOCKED"]);
+
+function coverageError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function stringArray(value, label) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim() === "")) {
+    throw coverageError("E_EVIDENCE_COVERAGE_INVALID", `${label} must be an array of non-empty strings`);
+  }
+  return [...new Set(value)];
+}
+
+export function evaluateCoverage(requiredEvidence, observedEvidence, { blocked = false } = {}) {
+  const required = stringArray(requiredEvidence, "requiredEvidence");
+  const observed = stringArray(observedEvidence, "observedEvidence");
+  if (blocked) return "BLOCKED";
+  if (required.length === 0 || required.every((item) => observed.includes(item))) return "COVERED";
+  if (required.some((item) => observed.includes(item))) return "PARTIAL";
+  return "NOT_VERIFIED";
+}
+
+export function createCoverage(input = {}) {
+  const requiredEvidence = stringArray(input.requiredEvidence ?? [], "requiredEvidence");
+  const observedEvidence = stringArray(input.observedEvidence ?? [], "observedEvidence");
+  const status = input.status ?? evaluateCoverage(requiredEvidence, observedEvidence, { blocked: input.blocked === true });
+  const value = {
+    schemaVersion: COVERAGE_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    requirement: input.requirement,
+    requiredEvidence,
+    observedEvidence,
+    status,
+    ...(input.details !== undefined ? { details: structuredClone(input.details) } : {}),
+  };
+  return assertCoverage(value);
+}
+
+export function assertCoverage(value, label = "evidence coverage") {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw coverageError("E_EVIDENCE_COVERAGE_INVALID", `${label} must be an object`);
+  }
+  if (value.schemaVersion !== COVERAGE_SCHEMA_VERSION || value.protocolVersion !== PROTOCOL_VERSION) {
+    throw coverageError("E_EVIDENCE_COVERAGE_INVALID", `${label} has an unsupported protocol version`);
+  }
+  if (typeof value.requirement !== "string" || value.requirement.trim() === "") {
+    throw coverageError("E_EVIDENCE_COVERAGE_INVALID", `${label}.requirement is required`);
+  }
+  const requiredEvidence = stringArray(value.requiredEvidence, `${label}.requiredEvidence`);
+  const observedEvidence = stringArray(value.observedEvidence, `${label}.observedEvidence`);
+  if (!COVERAGE_STATUSES.includes(value.status)) {
+    throw coverageError("E_EVIDENCE_COVERAGE_INVALID", `${label}.status is invalid`);
+  }
+  const expected = evaluateCoverage(requiredEvidence, observedEvidence, {
+    blocked: value.status === "BLOCKED",
+  });
+  if (value.status !== expected && !(value.status === "BLOCKED" && expected === "BLOCKED")) {
+    throw coverageError("E_EVIDENCE_COVERAGE_PARTIAL", `${label}.status does not match its observed evidence`);
+  }
+  return value;
+}
+
+export function assertCoverageList(value, label = "evidenceCoverage") {
+  if (!Array.isArray(value)) throw coverageError("E_EVIDENCE_COVERAGE_INVALID", `${label} must be an array`);
+  value.forEach((item, index) => assertCoverage(item, `${label}[${index}]`));
+  return value;
+}
+
+export function coverageForRequirements(requirements, checks, { blockedIds = [] } = {}) {
+  const normalizedRequirements = stringArray(requirements ?? [], "requirements");
+  const normalizedChecks = Array.isArray(checks) ? checks : [];
+  const observed = new Set(
+    normalizedChecks
+      .filter((check) => check?.status === "passed" && check.evidenceKind === "OBSERVED")
+      .flatMap((check) => [check.id, check.kind, check.requirement]),
+  );
+  const blocked = new Set(blockedIds);
+  return normalizedRequirements.map((requirement) => createCoverage({
+    requirement,
+    requiredEvidence: [requirement],
+    observedEvidence: observed.has(requirement) ? [requirement] : [],
+    blocked: blocked.has(requirement),
+  }));
+}

package/src/core/events.js

@@ -0,0 +1,124 @@
+import { createHash, randomUUID } from "node:crypto";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { assertSafePath, ensureWithin, fileExists } from "./filesystem.js";
+import { ARTIFACT_PATHS, canonicalFingerprint } from "./artifacts.js";
+import { assertJsonBytes, assertJsonLimits } from "./json-safety.js";
+import { assertSchema, readSchema } from "./schema-validation.js";
+import { assertSecretFree } from "./receipt.js";
+import { PROTOCOL_VERSION } from "./protocol.js";
+
+const EVENT_SCHEMA_VERSION = 1;
+
+function eventHash(event) {
+  const { hash, ...body } = event;
+  return canonicalFingerprint(body);
+}
+
+function protocolError(code, message, artifacts = [ARTIFACT_PATHS.events]) {
+  const error = new Error(message);
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+async function readEvents(target, packageRoot) {
+  await assertSafePath(target, ARTIFACT_PATHS.events);
+  const eventsPath = ensureWithin(target, ARTIFACT_PATHS.events);
+  if (!(await fileExists(eventsPath))) return [];
+  const text = await readFile(eventsPath, "utf8");
+  assertJsonBytes(text, ARTIFACT_PATHS.events);
+  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}]`);
+    } catch (error) {
+      throw protocolError("E_EVENT_INVALID", `${ARTIFACT_PATHS.events} line ${index + 1}: ${error.message}`);
+    }
+    return event;
+  });
+}
+
+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 previous = events.at(-1) ?? null;
+  const event = {
+    seq: events.length + 1,
+    schemaVersion: EVENT_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    taskId: input.taskId,
+    event: input.event,
+    at: input.at ?? new Date().toISOString(),
+    ...(input.fingerprint ? { fingerprint: input.fingerprint } : {}),
+    previousHash: previous?.hash ?? null,
+    ...(input.details ? { details: structuredClone(input.details) } : {}),
+  };
+  assertSecretFree(event);
+  const schema = await readSchema("event", packageRoot);
+  assertSchema(event, schema, ARTIFACT_PATHS.events);
+  event.hash = eventHash(event);
+  const eventsPath = ensureWithin(target, ARTIFACT_PATHS.events);
+  if (!options.dryRun) {
+    await mkdir(path.dirname(eventsPath), { recursive: true });
+    await appendFile(eventsPath, `${JSON.stringify(event)}\n`, { encoding: "utf8" });
+  }
+  return event;
+}
+
+export async function validateEventLedger(target, packageRoot) {
+  let events;
+  try {
+    events = await readEvents(target, packageRoot);
+  } catch (error) {
+    return { valid: false, events: [], errors: [{ code: error.code ?? "E_EVENT_INVALID", message: error.message }] };
+  }
+  const errors = [];
+  let taskId = null;
+  const seen = new Set();
+  for (const [index, event] of events.entries()) {
+    if (event.seq !== index + 1) {
+      errors.push({ code: "E_EVENT_INVALID", message: `event sequence must be ${index + 1}` });
+    }
+    if (taskId === null) taskId = event.taskId;
+    if (event.taskId !== taskId) errors.push({ code: "E_EVENT_INVALID", message: "event task IDs must remain stable" });
+    if (event.previousHash !== (index === 0 ? null : events[index - 1].hash)) {
+      errors.push({ code: "E_LEDGER_HASH_INVALID", message: `event ${event.seq} previousHash does not match` });
+    }
+    if (event.hash !== eventHash(event)) {
+      errors.push({ code: "E_LEDGER_HASH_INVALID", message: `event ${event.seq} hash does not match its content` });
+    }
+    seen.add(event.event);
+    if (event.event === "EXECUTION_STARTED" && !seen.has("ROUTE_VALIDATED")) {
+      errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "execution started before route validation" });
+    }
+    if (event.event === "EXECUTION_STARTED" && !seen.has("CONTRACT_VALIDATED")) {
+      errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "execution started before contract validation" });
+    }
+    if (event.event === "EXECUTION_STARTED" && !seen.has("PREFLIGHT_READY")) {
+      errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "execution started before preflight readiness" });
+    }
+    if (event.event === "EXECUTION_STARTED") {
+      const preflight = events.slice(0, index).findLast((candidate) => candidate.event === "PREFLIGHT_READY");
+      const requiredGates = preflight?.details?.requiredGates ?? [];
+      const satisfiedGates = new Set(events.slice(0, index)
+        .filter((candidate) => candidate.event === "GATE_SATISFIED")
+        .map((candidate) => candidate.details?.gate));
+      for (const gate of requiredGates) {
+        if (!satisfiedGates.has(gate)) {
+          errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: `execution started before gate satisfaction: ${gate}` });
+        }
+      }
+    }
+    if (event.event === "COMPLETION_VALIDATED" && !seen.has("VERIFICATION_RECORDED")) {
+      errors.push({ code: "E_PHASE_CHRONOLOGY_INVALID", message: "completion validated before verification evidence" });
+    }
+  }
+  return { valid: errors.length === 0, events, errors };
+}

package/src/core/gate-artifact.js

@@ -0,0 +1,54 @@
+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";
+
+function gateName(value) {
+  if (typeof value !== "string" || !/^[a-z0-9][a-z0-9-]*$/.test(value)) {
+    const error = new Error(`Invalid gate name: ${value}`);
+    error.code = "E_GATE_INVALID";
+    throw error;
+  }
+  return value;
+}
+
+export function gatePath(gate) {
+  return `${ARTIFACT_PATHS.gates ?? ".forgeloop/gates"}/${gateName(gate)}.json`;
+}
+
+export async function persistGate(target, gate, packageRoot, options = {}) {
+  const relativePath = gatePath(gate.gate);
+  return writeJsonArtifact(target, relativePath, gate, "gate", packageRoot, options);
+}
+
+export async function readGate(target, gate, packageRoot) {
+  const relativePath = gatePath(gate);
+  return readJsonArtifact(target, relativePath, "gate", packageRoot);
+}
+
+export async function readGateIfPresent(target, gate, packageRoot) {
+  const relativePath = gatePath(gate);
+  await assertSafePath(target, relativePath);
+  const filePath = ensureWithin(target, relativePath);
+  if (!(await fileExists(filePath))) return null;
+  return readJsonArtifact(target, relativePath, "gate", packageRoot);
+}
+
+export async function validateGateArtifacts(target, gateValue, packageRoot) {
+  const schema = await readSchema("gate", packageRoot);
+  assertSchema(gateValue, schema, "gate");
+  const stale = [];
+  for (const artifact of gateValue.artifacts ?? []) {
+    await assertSafePath(target, artifact.path);
+    const artifactPath = ensureWithin(target, artifact.path);
+    if (!(await fileExists(artifactPath))) {
+      stale.push({ path: artifact.path, status: "missing" });
+      continue;
+    }
+    const digest = sha256(await readBytes(artifactPath));
+    if (digest !== artifact.sha256) stale.push({ path: artifact.path, status: "changed" });
+  }
+  return stale;
+}

package/src/core/gates.js

@@ -0,0 +1,55 @@
+import { PROTOCOL_VERSION } from "./protocol.js";
+import path from "node:path";
+
+export const GATE_SCHEMA_VERSION = 1;
+export const GATE_STATUSES = Object.freeze(["satisfied", "unverified", "blocked"]);
+
+function stringArray(value, label) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim() === "")) {
+    throw new Error(`${label} must be an array of non-empty strings`);
+  }
+  return [...value];
+}
+
+function artifactList(value) {
+  if (!Array.isArray(value)) throw new Error("Gate artifacts must be an array");
+  return value.map((artifact) => {
+    if (!artifact || typeof artifact !== "object" || Array.isArray(artifact)) {
+      throw new Error("Gate artifact entries must be objects");
+    }
+    if (typeof artifact.path !== "string" || !artifact.path) throw new Error("Gate artifact path is required");
+    const portable = artifact.path.replaceAll("\\", "/");
+    const normalized = path.posix.normalize(portable);
+    if (portable.startsWith("/") || /^[A-Za-z]:\//.test(portable) || normalized === ".." || normalized.startsWith("../")) {
+      throw new Error(`Gate artifact path escapes the target: ${artifact.path}`);
+    }
+    if (typeof artifact.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(artifact.sha256)) {
+      throw new Error(`Gate artifact hash is invalid: ${artifact.path}`);
+    }
+    return { path: normalized.replace(/^\.\//, ""), sha256: artifact.sha256 };
+  });
+}
+
+export function createGate(input = {}) {
+  if (typeof input.taskId !== "string" || !input.taskId) throw new Error("Gate taskId is required");
+  if (typeof input.gate !== "string" || !input.gate) throw new Error("Gate name is required");
+  if (!GATE_STATUSES.includes(input.status)) throw new Error(`Unknown gate status: ${input.status}`);
+  const artifacts = artifactList(input.artifacts ?? []);
+  return {
+    schemaVersion: GATE_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    taskId: input.taskId,
+    gate: input.gate,
+    status: input.status,
+    requiredBy: stringArray(input.requiredBy ?? [], "Gate requiredBy"),
+    artifacts,
+    decisions: stringArray(input.decisions ?? [], "Gate decisions"),
+    unknowns: stringArray(input.unknowns ?? [], "Gate unknowns"),
+    approvedAssumptions: stringArray(input.approvedAssumptions ?? [], "Gate approvedAssumptions"),
+    evidence: Array.isArray(input.evidence) ? input.evidence.map((item) => ({ ...item })) : [],
+  };
+}
+
+export function requiredGatePaths(gates) {
+  return [...new Set(gates)].sort().map((gate) => `.forgeloop/gates/${gate}.json`);
+}

package/src/core/guide-metadata.js

@@ -0,0 +1,62 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+const GUIDE_FILES = Object.freeze({
+  premium: "ENG/premium-sites-studio-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",
+});
+
+function parseList(frontmatter, key) {
+  const lines = frontmatter.split(/\r?\n/);
+  const start = lines.findIndex((line) => line.trim() === `${key}:`);
+  if (start < 0) return [];
+  const values = [];
+  for (const line of lines.slice(start + 1)) {
+    if (!/^\s+-\s+/.test(line)) break;
+    values.push(line.replace(/^\s+-\s+/, "").trim());
+  }
+  return values.filter(Boolean);
+}
+
+function parseFrontmatter(text, relativePath) {
+  const match = text.match(/^---\s*\n([\s\S]*?)\n---\s*\n/);
+  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;
+  return {
+    guideId,
+    requiresGates: parseList(frontmatter, "requires-gates"),
+    completionEvidence: parseList(frontmatter, "completion-evidence"),
+  };
+}
+
+export async function readGuideMetadata(packageRoot) {
+  const metadata = {};
+  for (const [id, relativePath] of Object.entries(GUIDE_FILES)) {
+    const text = await readFile(path.join(packageRoot, relativePath), "utf8");
+    const parsed = parseFrontmatter(text, relativePath);
+    metadata[id] = {
+      guideId: parsed.guideId ?? id,
+      requiresGates: [...parsed.requiresGates],
+      completionEvidence: [...parsed.completionEvidence],
+      path: relativePath,
+    };
+  }
+  return metadata;
+}
+
+export async function requiredGatesForGuides(guides, packageRoot) {
+  const metadata = await readGuideMetadata(packageRoot);
+  return [...new Set(guides.flatMap((guide) => metadata[guide]?.requiresGates ?? []))].sort();
+}
+
+export async function completionEvidenceForGuides(guides, packageRoot) {
+  const metadata = await readGuideMetadata(packageRoot);
+  return [...new Set(guides.flatMap((guide) => metadata[guide]?.completionEvidence ?? []))].sort();
+}

package/src/core/phase.js

@@ -0,0 +1,88 @@
+import { ARTIFACT_PATHS } from "./artifacts.js";
+import { readJsonArtifact } from "./artifacts.js";
+import { readContract } from "./contract.js";
+import { appendProtocolEvent, validateEventLedger } from "./events.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import { assertWorkPhase, isValidTransition } from "./protocol.js";
+import { readWorkState, writeWorkState } from "./work-state.js";
+import { evaluateCompletion } from "./completion.js";
+
+function phaseError(code, message, artifacts = []) {
+  const error = new Error(message);
+  error.code = code;
+  error.artifacts = artifacts;
+  return error;
+}
+
+const PHASE_EVENTS = Object.freeze({
+  CONTRACT_READY: "CONTRACT_VALIDATED",
+  ROUTED: "ROUTE_VALIDATED",
+  DESIGNING: "DESIGN_GATE_STARTED",
+  PLANNED: "PLAN_RECORDED",
+  EXECUTING: "EXECUTION_STARTED",
+  VERIFYING: "VERIFICATION_STARTED",
+  COMPLETE: "COMPLETION_VALIDATED",
+});
+
+async function assertPhasePrerequisites(target, state, toPhase, packageRoot) {
+  if (toPhase === "CONTRACT_READY" || toPhase === "ROUTED" || toPhase === "EXECUTING") {
+    try {
+      await readContract(target, packageRoot);
+    } catch (error) {
+      throw phaseError("E_PHASE_PREREQUISITE_MISSING", `Phase ${toPhase} requires ${ARTIFACT_PATHS.contract}: ${error.message}`, [ARTIFACT_PATHS.contract]);
+    }
+  }
+  if (toPhase === "ROUTED" || toPhase === "EXECUTING") {
+    try {
+      await readPersistedRoute(target, packageRoot);
+    } catch (error) {
+      throw phaseError("E_PHASE_PREREQUISITE_MISSING", `Phase ${toPhase} requires ${ARTIFACT_PATHS.route}: ${error.message}`, [ARTIFACT_PATHS.route]);
+    }
+  }
+  if (toPhase === "EXECUTING") {
+    let preflight;
+    try {
+      preflight = await readJsonArtifact(target, ARTIFACT_PATHS.preflight, "preflight", packageRoot);
+    } catch (error) {
+      throw phaseError("E_PHASE_PREREQUISITE_MISSING", `EXECUTING requires READY ${ARTIFACT_PATHS.preflight}: ${error.message}`, [ARTIFACT_PATHS.preflight]);
+    }
+    if (preflight.value.status !== "READY") {
+      throw phaseError("E_PREFLIGHT_NOT_READY", "EXECUTING requires a READY preflight", [ARTIFACT_PATHS.preflight]);
+    }
+    const ledger = await validateEventLedger(target, packageRoot);
+    for (const requiredEvent of ["CONTRACT_VALIDATED", "ROUTE_VALIDATED", "PREFLIGHT_READY"]) {
+      if (!ledger.events.some((event) => event.event === requiredEvent)) {
+        throw phaseError("E_PHASE_CHRONOLOGY_INVALID", `EXECUTING requires a ${requiredEvent} protocol event`, [ARTIFACT_PATHS.events]);
+      }
+    }
+  }
+  if (toPhase === "COMPLETE" && state.verificationEvidence.length === 0) {
+    throw phaseError("E_PHASE_EVIDENCE_MISSING", "COMPLETE requires verification evidence");
+  }
+  if (toPhase === "COMPLETE") {
+    const completion = await evaluateCompletion({ target, packageRoot, persist: false });
+    if (completion.status !== "VALID") {
+      throw phaseError("E_COMPLETION_REJECTED", "COMPLETE requires a valid completion audit", completion.errors.flatMap((error) => error.artifacts ?? []));
+    }
+  }
+}
+
+export async function advanceWorkState(target, toPhase, { packageRoot, now = new Date().toISOString() } = {}) {
+  assertWorkPhase(toPhase);
+  const state = await readWorkState(target, packageRoot);
+  if (!state) throw phaseError("E_PHASE_PREREQUISITE_MISSING", "Cannot advance without work state", [ARTIFACT_PATHS.state]);
+  await assertPhasePrerequisites(target, state, toPhase, packageRoot);
+  if (!isValidTransition(state.phase, toPhase)) {
+    throw phaseError("E_PHASE_TRANSITION_INVALID", `Invalid work-state transition: ${state.phase} -> ${toPhase}`);
+  }
+  const next = {
+    ...state,
+    previousPhase: state.phase,
+    phase: toPhase,
+    lastUpdated: now,
+  };
+  await writeWorkState(target, next, { packageRoot });
+  const eventType = PHASE_EVENTS[toPhase];
+  if (eventType) await appendProtocolEvent(target, { taskId: state.taskId, event: eventType, at: now }, packageRoot);
+  return next;
+}

package/src/core/policies.js

@@ -0,0 +1,69 @@
+import { PROTOCOL_VERSION } from "./protocol.js";
+import { assertSchema, readSchema } from "./schema-validation.js";
+
+export const POLICY_SCHEMA_VERSION = 1;
+
+const POLICIES = Object.freeze({
+  "web-premium": {
+    name: "web-premium",
+    description: "Strict completion for premium website delivery.",
+    complianceMode: "strict",
+    requiredGates: ["design", "quality"],
+    requiredEvidence: ["responsive-validation", "accessibility-validation", "build", "visual-validation"],
+    allowedCompletionStates: ["COMPLETE"],
+    freshnessRequired: true,
+  },
+  bugfix: {
+    name: "bugfix",
+    description: "Standard completion with diagnosis and regression evidence.",
+    complianceMode: "standard",
+    requiredGates: ["diagnosis", "regression"],
+    requiredEvidence: ["reproduction", "regression"],
+    allowedCompletionStates: ["COMPLETE", "BLOCKED"],
+    freshnessRequired: true,
+  },
+  "security-critical": {
+    name: "security-critical",
+    description: "Strict completion with a declared trust boundary and observed security evidence.",
+    complianceMode: "strict",
+    requiredGates: ["threat-boundary", "security-verification"],
+    requiredEvidence: ["security-validation", "negative-test"],
+    allowedCompletionStates: ["COMPLETE", "BLOCKED"],
+    freshnessRequired: true,
+  },
+  prototype: {
+    name: "prototype",
+    description: "Advisory local work with explicit non-production semantics.",
+    complianceMode: "advisory",
+    requiredGates: [],
+    requiredEvidence: [],
+    allowedCompletionStates: ["COMPLETE", "BLOCKED"],
+    freshnessRequired: false,
+  },
+});
+
+export function getPolicy(name) {
+  const value = POLICIES[name];
+  if (!value) {
+    const error = new Error(`Unknown policy pack: ${name}`);
+    error.code = "E_POLICY_UNKNOWN";
+    throw error;
+  }
+  return {
+    schemaVersion: POLICY_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    ...value,
+    requiredGates: [...value.requiredGates],
+    requiredEvidence: [...value.requiredEvidence],
+    allowedCompletionStates: [...value.allowedCompletionStates],
+  };
+}
+
+export function listPolicies() {
+  return Object.keys(POLICIES).sort().map(getPolicy);
+}
+
+export async function validatePolicy(policy, packageRoot) {
+  const schema = await readSchema("policy", packageRoot);
+  return assertSchema(policy, schema, "policy");
+}