@cassiomc1/forgeloop 0.1.11 → 0.1.13

package/src/commands/validate-protocol.js

@@ -97,14 +97,6 @@ export async function runValidateProtocol({
   const stateClassification = state && readErrors.length === 0 && !stateValidationError
     ? await classifyLoadedWorkState({ target, state, contractFile })
     : null;
-  const result = validateTaskArtifactSet({
-    route,
-    state,
-    stateClassification,
-    receipt,
-    taskBriefs,
-    delegatedResults,
-  });
   let readyConsistencyErrors = [];
   try {
     const persistedPreflight = await readJsonArtifact(target, ARTIFACT_PATHS.preflight, "preflight", packageRoot);
@@ -119,9 +111,11 @@ export async function runValidateProtocol({
   } catch {
     // A missing or invalid preflight is already outside the optional protocol set.
   }
+  let ledgerEvents = [];
   let ledgerErrors = [];
   if (state && !stateValidationError) {
     const ledger = await validateEventLedger(target, packageRoot);
+    ledgerEvents = ledger.events ?? [];
     ledgerErrors = [
       ...ledger.errors.map((error) => ({ ...error, artifacts: [ARTIFACT_PATHS.events] })),
       ...validateStateLedgerCoherence(state, ledger.events).map((error) => ({
@@ -130,6 +124,15 @@ export async function runValidateProtocol({
       })),
     ];
   }
+  const result = validateTaskArtifactSet({
+    route,
+    state,
+    stateClassification,
+    receipt,
+    taskBriefs,
+    delegatedResults,
+    events: ledgerEvents,
+  });
   if (readErrors.length > 0 || schemaErrors.length > 0 || readyConsistencyErrors.length > 0 || ledgerErrors.length > 0) {
     return {
       ...result,

package/src/core/conformance.js

@@ -23,6 +23,24 @@ function sortErrors(errors) {
     || left.message.localeCompare(right.message));
 }
 
+export function delegationIsInScope({
+  state = null,
+  receipt = null,
+  events = [],
+  taskBriefs = [],
+  delegatedResults = [],
+} = {}) {
+  if (taskBriefs && taskBriefs.length > 0) return true;
+  if (delegatedResults && delegatedResults.length > 0) return true;
+  if (state?.delegatedTasks && state.delegatedTasks.length > 0) return true;
+  if (state?.delegatedTaskIds && state.delegatedTaskIds.length > 0) return true;
+  if (receipt?.delegatedTasks && receipt.delegatedTasks.length > 0) return true;
+  if (Array.isArray(events) && events.some((event) => typeof event?.type === "string" && event.type.toLowerCase().includes("delegat"))) {
+    return true;
+  }
+  return false;
+}
+
 export function validateTaskArtifactSet({
   route = null,
   state = null,
@@ -30,6 +48,7 @@ export function validateTaskArtifactSet({
   receipt = null,
   taskBriefs = [],
   delegatedResults = [],
+  events = [],
 } = {}) {
   const errors = [];
   const incomplete = [];
@@ -62,6 +81,7 @@ export function validateTaskArtifactSet({
     errors.push(error("STATE_RECEIPT_GUIDES_MISMATCH", "execution-receipt.selectedGuides must equal work-state.selectedGuides", ["state", "receipt"]));
   }
 
+  const delegationActive = delegationIsInScope({ state, receipt, events, taskBriefs, delegatedResults });
   const briefIds = new Set();
   for (const brief of taskBriefs) {
     if (!brief?.taskId) continue;
@@ -86,13 +106,18 @@ export function validateTaskArtifactSet({
     }
   }
 
-  if (taskBriefs.length > 0) {
-    for (const taskId of [...briefIds].sort()) {
-      if (!delegatedIds.has(taskId)) incomplete.push(`missing delegated result: ${taskId}`);
+  if (delegationActive) {
+    if (taskBriefs.length > 0) {
+      for (const taskId of [...briefIds].sort()) {
+        if (!delegatedIds.has(taskId)) incomplete.push(`missing delegated result: ${taskId}`);
+      }
+    } else if (delegatedResults.length > 0) {
+      incomplete.push("task briefs are required when delegated results are supplied");
+    } else {
+      incomplete.push("task briefs and delegated results were not supplied for delegated task");
     }
-  } else if (delegatedResults.length === 0) {
-    incomplete.push("task briefs and delegated results were not supplied");
   }
+
   if (!route || !state || !receipt) incomplete.push("route, state, and receipt are all required for a complete artifact set");
 
   const sortedErrors = sortErrors(errors);
@@ -117,6 +142,22 @@ export function validateTaskArtifactSet({
     }
     : null;
 
+  const delegation = delegationActive
+    ? {
+      status: sortedErrors.some((e) => e.code.includes("DELEGAT") || e.code.includes("TASK"))
+        ? "INCONSISTENT"
+        : incomplete.some((i) => i.includes("delegat") || i.includes("brief"))
+          ? "INCOMPLETE"
+          : "VALID",
+      required: true,
+      errors: sortedErrors.filter((e) => e.code.includes("DELEGAT") || e.code.includes("TASK")),
+    }
+    : {
+      status: "NOT_APPLICABLE",
+      required: false,
+      errors: [],
+    };
+
   const evidenceKind = status === "VALID"
     ? "OBSERVED"
     : status === "INCOMPLETE"
@@ -131,6 +172,7 @@ export function validateTaskArtifactSet({
     errors: sortedErrors,
     incomplete: [...new Set(incomplete)].sort(),
     stale,
+    delegation,
     evidence: [createEvidence({
       kind: evidenceKind,
       source: "ForgeLoop protocol conformance",

package/src/core/discovery-surfaces.js

@@ -0,0 +1,22 @@
+export const DISCOVERY_SURFACES = Object.freeze([
+  Object.freeze({
+    id: "agents-md",
+    path: "AGENTS.md",
+    kind: "project-instructions",
+  }),
+  Object.freeze({
+    id: "claude-md",
+    path: "CLAUDE.md",
+    kind: "project-instructions",
+  }),
+  Object.freeze({
+    id: "cursor-rule",
+    path: ".cursor/rules/project-loop.mdc",
+    kind: "project-instructions",
+  }),
+  Object.freeze({
+    id: "github-repository-instructions",
+    path: ".github/copilot-instructions.md",
+    kind: "project-instructions",
+  }),
+]);

package/src/core/inspect.js

@@ -1,5 +1,5 @@
 import { fileExists, ensureWithin, readBytes } from "./filesystem.js";
-import { AGENT_SUPPORT } from "./agent-support.js";
+import { DISCOVERY_SURFACES } from "./discovery-surfaces.js";
 import { readManifest } from "./manifest.js";
 import { PROTOCOL_VERSION } from "./protocol.js";
 import { inspectSchemaHealth } from "./schema-validation.js";
@@ -42,15 +42,14 @@ export async function inspectTarget({ target, packageRoot, contractFile = null }
     ? `${FORGELOOP_KIT_DIR}/schemas`
     : "schemas";
   const doctor = await runDoctor({ target, packageRoot });
-  const agents = await Promise.all(AGENT_SUPPORT.map(async (record) => ({
-    id: record.id,
-    name: record.name,
-    support: record.support,
-    instructionFiles: record.instructionFiles,
-    available: (await Promise.all(
-      record.instructionFiles.map(async (relativePath) => fileExists(ensureWithin(target, relativePath))),
-    )).some(Boolean),
+  const surfaces = await Promise.all(DISCOVERY_SURFACES.map(async (surface) => ({
+    id: surface.id,
+    path: surface.path,
+    kind: surface.kind,
+    available: await fileExists(ensureWithin(target, surface.path)),
   })));
+  const availableSurfaces = surfaces.filter((surface) => surface.available);
+  const protocolActivated = availableSurfaces.length > 0;
 
   const findings = [...doctor.findings];
   for (const schema of schemaHealth.schemas) {
@@ -100,9 +99,20 @@ export async function inspectTarget({ target, packageRoot, contractFile = null }
       error: manifestError,
     },
     profile,
+    integration: {
+      protocolActivated,
+      protocolMarker: "FORGELOOP_PROJECT_PROTOCOL=REQUIRED",
+      discovery: {
+        status: protocolActivated ? "INSTRUCTION_DISCOVERED" : "INSTRUCTION_ABSENT",
+        surfaces,
+      },
+      capability: {
+        status: "NOT_VERIFIED",
+      },
+    },
     adapters: {
-      detected: agents.filter((agent) => agent.available).map((agent) => agent.id),
-      agents,
+      detected: availableSurfaces.map((s) => s.path),
+      surfaces,
     },
     protocol: {
       version: PROTOCOL_VERSION,
@@ -112,7 +122,8 @@ export async function inspectTarget({ target, packageRoot, contractFile = null }
     },
     state: { ...state, path: WORK_STATE_PATH, present: statePresent },
     compatibility: {
-      agents: AGENT_SUPPORT.map((record) => record.id),
+      deprecated: true,
+      agents: [],
     },
     findings,
     evidence,

package/src/core/native-adapters.js

@@ -15,13 +15,44 @@ export function nativeShimReferences(relativePath) {
   const prefix = nativeShimPrefix(relativePath);
   return [
     `${prefix}/LOOP_ENGINEERING.md`,
-    `${prefix}/AGENT_COMPATIBILITY.md`,
+    `${prefix}/PROTOCOL_INTEGRATION.md`,
   ];
 }
 
 export function nativeShim(relativePath) {
   const kitPrefix = nativeShimPrefix(relativePath);
-  return `# ForgeLoop native adapter\n\nRead and follow the canonical ForgeLoop protocol in ${kitPrefix}/LOOP_ENGINEERING.md and ${kitPrefix}/AGENT_COMPATIBILITY.md.\nThe canonical guides and schemas are under ${kitPrefix}/; keep this adapter concise and preserve any host-specific instructions.\n`;
+  return `<!-- FORGELOOP_PROJECT_PROTOCOL=REQUIRED -->
+# ForgeLoop Project Protocol
+
+This project is ForgeLoop-enabled.
+
+If your execution environment loaded this file, ForgeLoop applies to work
+performed in this project regardless of model, provider, product, IDE,
+agent name, runtime name, or orchestration environment.
+
+Do not treat ForgeLoop as vendor-specific, harness-specific, optional,
+advisory, or something to follow only "in spirit".
+
+Read and follow:
+- ${kitPrefix}/LOOP_ENGINEERING.md
+- ${kitPrefix}/PROTOCOL_INTEGRATION.md
+
+Before changing product or executable files, establish the ForgeLoop contract,
+route, required gates, and READY preflight.
+
+Use the project-local ForgeLoop CLI for lifecycle-owned protocol state.
+Never manually synthesize lifecycle chronology or assign ForgeLoop COMPLETE.
+
+Do not install a missing verification tool merely to satisfy a check.
+Use an existing equivalent, obtain explicit authority, or report the
+verification dimension as NOT_VERIFIED.
+
+Before claiming ForgeLoop-verified completion, require
+\`forgeloop complete\` to return \`VALID\`.
+
+If a required capability is unavailable, report that ForgeLoop dimension as
+not verified rather than simulating it.
+`;
 }
 
 export function resolveNativeReference(relativePath, reference) {
@@ -45,6 +76,7 @@ export function inspectNativeAdapter(relativePath, bytes) {
     missingReferences,
     resolvedReferences,
     hasForgeLoopMarker: /forgeloop/i.test(text),
+    hasProtocolMarker: text.includes("FORGELOOP_PROJECT_PROTOCOL=REQUIRED"),
   };
 }
 

package/src/core/templates.js

@@ -32,6 +32,7 @@ export const TEMPLATE_PATHS = [
   "ORCHESTRATOR_INTEGRATION.md",
   "THREAT_MODEL.md",
   "CONTRACT_COVERAGE.md",
+  "PROTOCOL_INTEGRATION.md",
   "AGENT_COMPATIBILITY.md",
   "THIRD_PARTY_NOTICES.md",
   "LICENSE",

package/src/core/verification-capability.js

@@ -0,0 +1,47 @@
+export const E_VERIFICATION_TOOL_UNAVAILABLE = "E_VERIFICATION_TOOL_UNAVAILABLE";
+export const E_INSTALLATION_AUTHORITY_REQUIRED = "E_INSTALLATION_AUTHORITY_REQUIRED";
+
+export function classifyVerificationCapability({
+  available = false,
+  equivalentAvailable = false,
+  installationAuthorized = false,
+  installationRequired = false,
+} = {}) {
+  if (available) {
+    return {
+      action: "USE_AVAILABLE",
+      reasonCode: null,
+      message: "Verification tool is locally available.",
+    };
+  }
+
+  if (equivalentAvailable) {
+    return {
+      action: "USE_EQUIVALENT",
+      reasonCode: null,
+      message: "An existing local equivalent verifier is available.",
+    };
+  }
+
+  if (installationAuthorized) {
+    return {
+      action: "INSTALL_AUTHORIZED",
+      reasonCode: null,
+      message: "Installation is explicitly authorized for this verification requirement.",
+    };
+  }
+
+  if (installationRequired) {
+    return {
+      action: "REQUEST_AUTHORITY",
+      reasonCode: E_INSTALLATION_AUTHORITY_REQUIRED,
+      message: "Verification tool is required but installation authority has not been granted.",
+    };
+  }
+
+  return {
+    action: "RECORD_NOT_VERIFIED",
+    reasonCode: E_VERIFICATION_TOOL_UNAVAILABLE,
+    message: "Verification tool is absent and installation was not authorized.",
+  };
+}

package/conformance/README.md

@@ -1,153 +0,0 @@
-# ForgeLoop conformance scenarios
-
-These scenarios are adapter-facing contracts. They describe requests and the
-artifacts a live agent must produce; they do not invoke a model runtime and are
-not part of the deterministic `npm test` execution path.
-
-The current published baseline for new runs is
-`@cassiomc1/forgeloop@0.1.10`. Pin that version when preparing a reproducible
-blind run; historical reports retain the exact package version they used.
-
-The frozen baseline was verified on 2026-08-13 with this identity:
-
-```text
-package: @cassiomc1/forgeloop@0.1.10
-npm gitHead: 10246cf92016c92c91c6d99c2e8c7df7d99fa68a
-release commit: 10246cf92016c92c91c6d99c2e8c7df7d99fa68a
-GitHub tag: v0.1.10 -> 10246cf92016c92c91c6d99c2e8c7df7d99fa68a
-tarball URL: https://registry.npmjs.org/@cassiomc1/forgeloop/-/forgeloop-0.1.10.tgz
-tarball SHA-1: 175a83ebd00e6b0ec4f0b7bf2ed8924198d6df3c
-npm SHA-512 integrity: sha512-+aMssrl9Wh69at9B1oKJQJEpgHpbKlb7sT1pLAWh+v/IouxXZkVqz5w34iR54pfqykjhl5Nrpd+g3XbQtzYdbA==
-release identity: RELEASE_IDENTITY_VALID
-```
-
-The repository may contain documentation or executable commits after this
-frozen package. Those commits do not change the package used by the blind run.
-Version `0.1.10` includes the completion-validation and cleanup TOCTOU fixes;
-repeat the complete identity check before starting a reproducible run.
-
-The repository candidate is `0.1.11` and is not published. It makes repeated
-verification recoverable through normal CLI transitions, evaluates evidence
-readiness consistently, rejects future lifecycle claims and contradictory
-compound evidence, and detects divergence between new work-state cycles and
-their event ledger. Continue pinning `0.1.10` until `0.1.11` is published and
-its release identity is verified.
-
-Run a scenario in a disposable target using the Standard profile first:
-
-```bash
-npx @cassiomc1/forgeloop preflight --json
-npx @cassiomc1/forgeloop next --json
-npx @cassiomc1/forgeloop audit --json
-npx @cassiomc1/forgeloop complete --json
-```
-
-The expected post-implementation path is:
-
-```text
-implementation
-→ forgeloop next
-→ advance --to VERIFYING
-→ forgeloop next
-→ prepare-completion
-→ forgeloop next
-→ checks + record-check
-→ forgeloop next
-→ advance --to REVIEWING
-→ forgeloop next
-→ complete
-```
-
-Use the Strict profile only as a separate experiment:
-
-```bash
-# .forgeloop/kit/PROJECT_PROFILE.md must be verified before this profile starts.
-npx @cassiomc1/forgeloop preflight --strict --json
-npx @cassiomc1/forgeloop audit --strict --json
-npx @cassiomc1/forgeloop complete --strict --json
-```
-
-Do not mix Standard and Strict criteria in one conformance result. Live-run
-diagnostic records belong under [`conformance/runs/`](./runs/); they must not
-contain secrets, credentials, hidden reasoning, or unnecessary conversation
-history.
-
-## Release identity evidence
-
-Every live-run report records the exact published package used by the target.
-Include all of these fields before sending the blind prompt:
-
-```text
-package: @cassiomc1/forgeloop@X.Y.Z
-npm gitHead: <40-character commit SHA>
-release commit: <40-character commit SHA>
-GitHub tag: vX.Y.Z -> <40-character commit SHA>
-tarball URL: https://registry.npmjs.org/...
-tarball SHA-1: <40-character hex digest>
-npm SHA-512 integrity: sha512-<base64 digest>
-release identity: RELEASE_IDENTITY_VALID
-```
-
-Run the repository's read-only verifier against the exact release commit:
-
-```bash
-RELEASE_COMMIT="$(git rev-list -n1 vX.Y.Z)"
-npm run release:identity -- --version X.Y.Z --release-commit "$RELEASE_COMMIT"
-```
-
-Do not interpret a local package version, a green build, or a tarball URL by
-itself as publication proof. If the verifier cannot establish every identity
-field, record `RELEASE_IDENTITY_NOT_VERIFIED` or
-`RELEASE_IDENTITY_INVALID` and do not start the blind run.
-
-The complete-website scenario deliberately fails when implementation starts
-before the contract, route, and required gates exist.
-
-## Migration compatibility evidence
-
-The real published `0.1.6` fixture at
-[`tests/fixtures/legacy-0.1.6/`](../tests/fixtures/legacy-0.1.6/) is frozen
-with package, tarball, SHA-1, SHA-512, `gitHead`, and extraction-date metadata.
-The migration tests run from those local bytes and cover interruptions after
-hidden writes, after hidden verification, after the manifest authority switch,
-and during legacy cleanup. An interrupted target must be diagnosed as
-`E_MIGRATION_INCOMPLETE`; a later `update` may retry only hash-owned cleanup.
-User-modified, unmanaged, and `preserve=true` files remain untouched even when
-that leaves a root residual. ForgeLoop revalidates the recorded ownership hash
-immediately before deleting each managed legacy file. This narrows the race
-window but does not provide OS-level filesystem locking against a separately
-privileged concurrent process.
-
-## Autonomous blind-run isolation
-
-External workflows may help with local planning, review, tests, or
-documentation, but a mandatory approval policy for a ForgeLoop `NON_BLOCKING`
-decision is `INCOMPATIBLE WITH AUTONOMOUS MODE`. The harness must exclude that
-policy before the blind prompt starts; do not add a hint to the prompt that
-changes the scenario. `NON_BLOCKING` must remain non-blocking, and any
-compatibility conflict is recorded as `WORKFLOW_CONFLICT`, not as a fake user
-blocker.
-
-For the sixth blind run, record these values before sending the unchanged blind
-prompt:
-
-```text
-mandatory-approval workflows enabled: NO
-external brainstorming hard gate enabled: NO
-external design approval gate enabled: NO
-subagents enabled: NO
-delegation enabled: NO
-```
-
-Also record the available and invoked external workflows, explicit autonomy
-mode, process count, subagent count, and delegation status. If the harness
-cannot disable a mandatory approval workflow, record `TEST_NOT_STARTED` and do
-not interpret the run as a conformance failure or success. An installed
-workflow and a compatible workflow are separate claims; use
-`INCOMPATIBLE WITH AUTONOMOUS MODE`, not "broken", for the former.
-
-Every live-run report must classify how it ended with exactly one
-`terminationSource`: `AGENT`, `OPERATOR`, `HARNESS`, `TIMEOUT`, or `BLOCKER`.
-An operator-terminated run is recorded as `RUN_STATUS: OPERATOR_INTERRUPTED`,
-`CONFORMANCE: PARTIAL`, with post-termination capabilities marked
-`NOT_REACHED` and the smallest failure class `OPERATOR_INTERRUPTION`.

package/conformance/backend-auth/EXPECTED_ROUTE.json

@@ -1,7 +0,0 @@
-{
-  "workType": "api-auth",
-  "surfaces": ["api", "auth"],
-  "risks": ["untrusted-input"],
-  "platforms": ["server"],
-  "guides": ["clean", "test", "security", "performance"]
-}

package/conformance/backend-auth/REQUEST.md

@@ -1,4 +0,0 @@
-# Backend authentication
-
-Change an authenticated backend surface with explicit trust-boundary review,
-negative tests, and observed verification.

package/conformance/backend-auth/REQUIRED_EVIDENCE.json

@@ -1,3 +0,0 @@
-{
-  "required": ["security-validation", "negative-test"]
-}

package/conformance/backend-auth/REQUIRED_GATES.json

@@ -1,3 +0,0 @@
-{
-  "required": ["threat-boundary"]
-}

package/conformance/blind-premium-website/EXPECTED_ROUTE.json

@@ -1,7 +0,0 @@
-{
-  "workType": "complete-website",
-  "surfaces": ["ui", "forms"],
-  "risks": ["accessibility"],
-  "platforms": ["web"],
-  "guides": ["premium", "design", "taste", "accessibility", "clean", "test", "security", "performance"]
-}

package/conformance/blind-premium-website/REQUEST.md

@@ -1,6 +0,0 @@
-# Premium law firm website
-
-Create a premium website for a law firm.
-
-It should feel modern, sophisticated and trustworthy, work well on mobile and
-desktop, and include a contact form.

package/conformance/blind-premium-website/REQUIRED_EVIDENCE.json

@@ -1,14 +0,0 @@
-{
-  "required": [
-    "accessibility-validation",
-    "build",
-    "focus-management",
-    "keyboard-navigation",
-    "mobile-viewport",
-    "performance-validation",
-    "responsive-validation",
-    "security-validation",
-    "tests",
-    "visual-validation"
-  ]
-}

package/conformance/blind-premium-website/REQUIRED_GATES.json

@@ -1,3 +0,0 @@
-{
-  "required": ["design", "quality", "threat-boundary"]
-}

package/conformance/complete-website/EXPECTED_ROUTE.json

@@ -1,7 +0,0 @@
-{
-  "workType": "complete-website",
-  "surfaces": ["ui", "forms"],
-  "risks": ["accessibility"],
-  "platforms": ["web"],
-  "guides": ["premium", "design", "taste", "accessibility", "clean", "test", "security", "performance"]
-}

package/conformance/complete-website/REQUEST.md

@@ -1,6 +0,0 @@
-# Complete website
-
-Create a premium, accessible website. Establish the current contract and
-persist deterministic routing before implementation. Satisfy design and
-quality gates, then record observed responsive, accessibility, build, and
-visual evidence.

package/conformance/complete-website/REQUIRED_EVIDENCE.json

@@ -1,3 +0,0 @@
-{
-  "required": ["responsive-validation", "accessibility-validation", "build", "visual-validation"]
-}

package/conformance/complete-website/REQUIRED_GATES.json

@@ -1,3 +0,0 @@
-{
-  "required": ["design", "quality"]
-}

package/conformance/docs-only/EXPECTED_ROUTE.json

@@ -1,7 +0,0 @@
-{
-  "workType": "documentation",
-  "surfaces": [],
-  "risks": [],
-  "platforms": [],
-  "guides": []
-}

package/conformance/docs-only/REQUEST.md

@@ -1,4 +0,0 @@
-# Documentation only
-
-Update domain documentation and verify Markdown, links, paths, and examples.
-No design gate is required.

package/conformance/docs-only/REQUIRED_EVIDENCE.json

@@ -1,3 +0,0 @@
-{
-  "required": ["documentation-validation"]
-}

package/conformance/docs-only/REQUIRED_GATES.json

@@ -1,3 +0,0 @@
-{
-  "required": []
-}