@cassiomc1/forgeloop 1.13.0 → 1.14.0

package/docs/protocol-requirements.json

@@ -72,6 +72,30 @@
       "statement": "A structural-quality integration MUST preserve unavailable, malformed, stale, incomparable, and blocked provider results without promoting them to PASS.",
       "tests": ["tests/sentrux-structural-quality-provider.test.js", "tests/structural-quality-artifacts.test.js"],
       "validator": "src/core/structural-quality/provider.js"
+    },
+    "FL-PROVIDER-001": {
+      "source": "PROTOCOL_INTEGRATION.md",
+      "statement": "The providerExtensions capability MUST remain provider-neutral and experimental, and MUST NOT imply a public generic provider registry API.",
+      "tests": ["tests/protocol-info.test.js", "tests/provider-capabilities.test.js"],
+      "validator": "src/core/protocol-info.js"
+    },
+    "FL-PROVIDER-002": {
+      "source": "PROTOCOL_INTEGRATION.md",
+      "statement": "Every advertised provider kind MUST deny lifecycle, completion, and evidence authority.",
+      "tests": ["tests/provider-capabilities.test.js"],
+      "validator": "src/providers/capabilities.js"
+    },
+    "FL-PROVIDER-003": {
+      "source": "PROTOCOL_INTEGRATION.md",
+      "statement": "Provider results MUST cross a strict JSON snapshot boundary before consumer use.",
+      "tests": ["tests/provider-architecture.test.js"],
+      "validator": "src/providers/json-snapshot.js"
+    },
+    "FL-PROVIDER-004": {
+      "source": "PROTOCOL_INTEGRATION.md",
+      "statement": "The generic provider registry MUST remain absent from the public package subpath exports.",
+      "tests": ["tests/provider-architecture.test.js", "tests/package.test.js"],
+      "validator": "package.json"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",
@@ -60,6 +60,7 @@
     "docs/CROSS_HARNESS_CONTINUITY.md",
     "docs/ADVISORY_CONTEXT.md",
     "docs/RIPWIRE_ADAPTER.md",
+    "docs/OPENSRC_ADAPTER.md",
     "docs/CLI_REFERENCE.md",
     "docs/ARTIFACT_REFERENCE.md",
     "docs/TROUBLESHOOTING.md",
@@ -68,9 +69,21 @@
     "docs/DOCUMENTATION_GUIDE.md",
     "docs/RELEASE_CHECKLIST.md",
     "docs/PACKAGE_CONTENTS.md",
+    "docs/PROVIDER_ARCHITECTURE.md",
+    "docs/PROVIDERS.md",
+    "docs/SECURITY_REVIEW.md",
+    "docs/BROWSER_VERIFICATION.md",
+    "docs/AGENT_BROWSER_ADAPTER.md",
+    "docs/AGENT_BROWSER_VERIFICATION.md",
+    "docs/JEV_BENCHMARKS.md",
+    "docs/MODEL_ROUTING.md",
+    "docs/SEMANTIC_DECISION_PLANE.md",
+    "docs/TEST_INTELLIGENCE.md",
+    "docs/TEST_PRUNING.md",
     "scripts/CI_VALIDATORS.md",
     "docs/MCP.md",
     "docs/UNIVERSAL_INTEGRATION.md",
+    "docs/AUDIT_UX.md",
     "docs/DIAGNOSTIC_MODEL.md",
     "docs/EXECUTION_TRACE.md",
     "docs/CODE_ATTESTATION.md",
@@ -78,12 +91,18 @@
     "docs/SIGNING_PROVIDERS.md",
     "docs/PLATFORM_ADAPTERS.md",
     "docs/AGENT_PROTOCOL_SUMMARY.md",
+    "docs/AGENT_SKILL.md",
     "docs/EXECUTION_PROFILE_BENCHMARKS.md",
     "docs/REPOSITORY_INDEX.md",
     "docs/PERSISTENT_SEARCH_TRANSPORT.md",
     "docs/KNOWLEDGE_SOURCES.md",
     "scripts/generate-shell-completions.mjs",
     "scripts/generate-agent-protocol-summary.mjs",
+    "scripts/generate-forgeloop-skill.mjs",
+    "scripts/jev-smoke.mjs",
+    "scripts/benchmark-jev.mjs",
+    "scripts/benchmark-test-intelligence.mjs",
+    "skills/forgeloop",
     "scripts/run-execution-profile-benchmarks.mjs",
     "scripts/summarize-execution-profile-benchmarks.mjs",
     "scripts/validate-execution-profile-benchmarks.mjs",
@@ -128,13 +147,15 @@
     "mcp:test": "node scripts/run-mcp-tests.mjs",
     "completions:generate": "node scripts/generate-shell-completions.mjs --write",
     "completions:check": "node scripts/generate-shell-completions.mjs --check",
-    "test:quick": "node --test tests/cli.test.js tests/schema-health.test.js tests/schema-golden.test.js tests/protocol-info.test.js tests/integration-capabilities.test.js tests/ci-classify.test.js tests/validation-tiers.test.js",
+    "test:quick": "node --import=./scripts/test-semantic-provider-loader.mjs --test tests/cli.test.js tests/schema-health.test.js tests/schema-golden.test.js tests/protocol-info.test.js tests/integration-capabilities.test.js tests/ci-classify.test.js tests/validation-tiers.test.js",
     "performance:check": "node scripts/benchmark-cli-startup.mjs",
     "critical-coverage:check": "node scripts/check-critical-coverage.mjs",
     "changelog:check": "node scripts/check-changelog-freshness.mjs",
     "attestation:summary": "node scripts/write-forgeloop-attestation-summary.mjs",
     "summary:generate": "node scripts/generate-agent-protocol-summary.mjs --write",
     "summary:check": "node scripts/generate-agent-protocol-summary.mjs --check",
+    "skill:generate": "node scripts/generate-forgeloop-skill.mjs --write",
+    "skill:check": "node scripts/generate-forgeloop-skill.mjs --check",
     "mcp:setup": "node scripts/mcp-setup.mjs",
     "mcp:pack:check": "node scripts/mcp-package-smoke.mjs",
     "poc:evidence:verify": "node scripts/verify_poc_evidence.mjs",
@@ -148,11 +169,16 @@
     "transactions:compact": "node scripts/compact-transactions.mjs",
     "complexity:check": "node scripts/check-complexity.mjs",
     "repository-index:manifest": "node scripts/verify-tgrep-manifest.mjs",
+    "repository:hygiene": "node scripts/check-repository-hygiene.mjs",
     "task-discovery:benchmark": "node scripts/benchmark-task-discovery.mjs",
     "verify:fast": "node scripts/run-validation.mjs --tier fast",
     "verify:local": "node scripts/run-validation.mjs --tier local",
     "verify:prepush": "node scripts/run-validation.mjs --tier prepush",
-    "verify:release": "node scripts/run-validation.mjs --tier release"
+    "verify:release": "node scripts/run-validation.mjs --tier release",
+    "jev:smoke": "node scripts/jev-smoke.mjs",
+    "benchmark:jev": "node scripts/benchmark-jev.mjs",
+    "benchmark:jev:live": "node scripts/benchmark-jev.mjs --live",
+    "benchmark:test-intelligence": "node scripts/benchmark-test-intelligence.mjs"
   },
   "devDependencies": {
     "c8": "^12.0.0",
@@ -161,6 +187,7 @@
     "yaml": "2.9.0"
   },
   "dependencies": {
+    "@typesafe-ai/sdk": "0.6.0",
     "smol-toml": "1.8.0"
   },
   "exports": {

package/schemas/config.schema.json

@@ -12,6 +12,20 @@
     "policy": { "type": "string", "minLength": 1 },
     "requiredGates": { "type": "array", "items": { "type": "string", "minLength": 1 } },
     "requiredEvidence": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "decisionEngine": {
+      "type": "object",
+      "required": ["required", "provider", "model", "policyVersion", "requestTimeoutMs", "maxRetries", "cache"],
+      "additionalProperties": false,
+      "properties": {
+        "required": { "const": true },
+        "provider": { "const": "typesafe-jev" },
+        "model": { "const": "jev-1.13.0" },
+        "policyVersion": { "const": 1 },
+        "requestTimeoutMs": { "type": "integer", "minimum": 500, "maximum": 60000 },
+        "maxRetries": { "type": "integer", "minimum": 0, "maximum": 3 },
+        "cache": { "type": "boolean" }
+      }
+    },
     "structuralQuality": {
       "type": "object",
       "additionalProperties": false,

package/schemas/context-plan.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/context-plan.schema.json",
+  "title": "ForgeLoop bounded context plan",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "profile", "budget", "candidateItems", "selectedItems", "candidateChars", "selectedChars", "selected", "omitted", "mandatoryIds", "promptInjectionIds", "candidateSetFingerprint", "tokenUsage", "decisionFingerprint", "authority", "evidenceAuthority", "lifecycleAuthority", "completionAuthority"],
+  "properties": {
+    "schemaVersion": { "const": 1 }, "protocolVersion": { "const": 1 },
+    "profile": { "enum": ["light", "balanced", "full"] },
+    "budget": { "type": "object", "required": ["maxItems", "maxChars"], "properties": { "maxItems": { "type": "integer", "minimum": 1 }, "maxChars": { "type": "integer", "minimum": 1 } }, "additionalProperties": false },
+    "candidateItems": { "type": "integer", "minimum": 0 }, "selectedItems": { "type": "integer", "minimum": 0 }, "candidateChars": { "type": "integer", "minimum": 0 }, "selectedChars": { "type": "integer", "minimum": 0 },
+    "selected": { "type": "array", "items": { "type": "object" } }, "omitted": { "type": "array", "items": { "type": "object" } },
+    "mandatoryIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "promptInjectionIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "candidateSetFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "tokenUsage": { "type": "object", "required": ["inputTokens", "outputTokens", "reportedBy"], "properties": { "inputTokens": { "type": ["integer", "null"] }, "outputTokens": { "type": ["integer", "null"] }, "reportedBy": { "enum": ["PROVIDER", "HOST", "UNKNOWN"] } }, "additionalProperties": false },
+    "decisionFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "authority": { "const": "SEMANTIC_DECISION" }, "evidenceAuthority": { "const": "NONE" }, "lifecycleAuthority": { "const": false }, "completionAuthority": { "const": false }
+  },
+  "additionalProperties": false
+}

package/schemas/semantic-decision.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/semantic-decision.schema.json",
+  "title": "ForgeLoop semantic decision",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "taskId", "decisionId", "decisionKind", "engine", "model", "questionSetId", "questionSetVersion", "questionSetFingerprint", "policyVersion", "stateFingerprint", "policyFingerprint", "answers", "confidence", "decision", "usage", "authority", "evidenceAuthority", "lifecycleAuthority", "completionAuthority", "ownershipAuthority", "installationAuthority", "recordedAt"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "taskId": { "type": "string", "minLength": 1 },
+    "decisionId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$" },
+    "decisionKind": { "type": "string", "minLength": 1 },
+    "engine": { "const": "typesafe-jev" },
+    "model": { "const": "jev-1.13.0" },
+    "questionSetId": { "type": "string", "minLength": 1 },
+    "questionSetVersion": { "type": "integer", "minimum": 1 },
+    "questionSetFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "questionSet": { "type": "object", "required": ["id", "version", "decisionKind", "questions", "fingerprint"], "properties": { "id": { "type": "string", "minLength": 1 }, "version": { "type": "integer", "minimum": 1 }, "decisionKind": { "type": "string", "minLength": 1 }, "questions": { "type": "object" }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "candidateIds": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" } }, "additionalProperties": true },
+    "policyVersion": { "const": 1 },
+    "stateFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "taskStateFingerprint": { "oneOf": [{ "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" }] },
+    "semanticStateFingerprint": { "oneOf": [{ "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" }] },
+    "policyFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "repositoryFingerprint": { "oneOf": [{ "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "object" }, { "type": "null" }] },
+    "contractFingerprint": { "oneOf": [{ "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" }] },
+    "routeFingerprint": { "oneOf": [{ "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" }] },
+    "verificationCycle": { "oneOf": [{ "type": "integer", "minimum": 1 }, { "type": "null" }] },
+    "candidateSetFingerprint": { "oneOf": [{ "type": "string", "pattern": "^[a-f0-9]{64}$" }, { "type": "null" }] },
+    "answers": { "type": "object" },
+    "confidence": { "type": "object" },
+    "decision": { "type": "object" },
+    "usage": {
+      "type": "object", "required": ["inputTokens", "outputTokens", "reportedBy"], "additionalProperties": false,
+      "properties": { "inputTokens": { "oneOf": [{ "type": "integer", "minimum": 0 }, { "type": "null" }] }, "outputTokens": { "oneOf": [{ "type": "integer", "minimum": 0 }, { "type": "null" }] }, "reportedBy": { "enum": ["PROVIDER", "HOST", "UNKNOWN"] } }
+    },
+    "latencyMs": { "oneOf": [{ "type": "integer", "minimum": 0 }, { "type": "null" }] },
+    "authority": { "const": "SEMANTIC_DECISION" },
+    "evidenceAuthority": { "const": "NONE" },
+    "lifecycleAuthority": { "const": false },
+    "completionAuthority": { "const": false },
+    "ownershipAuthority": { "const": false },
+    "installationAuthority": { "const": false },
+    "recordedAt": { "type": "string", "minLength": 1 }
+  },
+  "additionalProperties": false
+}

package/schemas/test-utility.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/test-utility.schema.json",
+  "title": "ForgeLoop test utility analysis",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "taskId", "generatedAt", "inventoryFingerprint", "semanticStatus", "tests"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "taskId": { "type": "string", "minLength": 1 },
+    "generatedAt": { "type": "string", "minLength": 1 },
+    "inventoryFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "semanticStatus": { "enum": ["PROVIDER_REPORTED", "UNAVAILABLE", "NOT_REQUESTED"] },
+    "decisionId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$" },
+    "semanticDecisionFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "decisionIds": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$" } },
+    "semanticDecisionFingerprints": { "type": "array", "items": { "type": "string", "pattern": "^[a-f0-9]{64}$" } },
+    "tests": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["testId", "file", "framework", "name", "classification", "recommendation", "protected"],
+        "properties": {
+          "testId": { "type": "string", "pattern": "^test-[a-f0-9]{24}$" },
+          "file": { "type": "string", "minLength": 1 },
+          "framework": { "type": "string", "minLength": 1 },
+          "suite": { "type": "string" },
+          "name": { "type": "string", "minLength": 1 },
+          "line": { "type": "integer", "minimum": 1 },
+          "sourceSummary": { "type": "string" },
+          "targets": { "type": "array", "items": { "type": "string" } },
+          "runtimeMs": { "type": ["number", "null"], "minimum": 0 },
+          "uniqueBranches": { "type": ["integer", "null"], "minimum": 0 },
+          "classification": { "enum": ["KEEP_REQUIRED", "KEEP_UNIQUE", "KEEP_RISK_GUARD", "KEEP_AUTHORITY_BOUNDARY", "KEEP_RECOVERY_INVARIANT", "KEEP_RELEASE_SMOKE", "KEEP_MIGRATION_COMPATIBILITY", "KEEP_PLATFORM_BEHAVIOR", "KEEP_DOCUMENTATION_VALUE", "KEEP_INTEGRATION_GUARD", "OBSOLETE_CANDIDATE", "FLAKY_LOW_SIGNAL", "EXPENSIVE_LOW_SIGNAL", "UNKNOWN", "REDUNDANT_CANDIDATE"] },
+          "recommendation": { "enum": ["KEEP", "REWRITE", "PROBE_REMOVAL", "BLOCKED", "REVIEW"] },
+          "protected": { "type": "boolean" },
+          "signals": { "type": "object", "additionalProperties": true }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/scripts/CI_VALIDATORS.md

@@ -48,7 +48,7 @@ missing tool implicitly:
 
 | Tier | Command | Intended use |
 | --- | --- | --- |
-| Fast | `npm run verify:fast` | feedback while editing; quick Node, lint, dependency-policy, and generated-doc checks |
+| Fast | `npm run verify:fast` | feedback while editing; quick Node, lint, dependency-policy, generated-doc, and repository-hygiene checks |
 | Local | `npm run verify:local` | full deterministic source, documentation, manifest, and frozen Python checks |
 | Pre-push | `npm run verify:prepush` | coverage, critical coverage, package/MCP checks, PoC checks, and the local suite expected before a PR |
 | Release | `npm run verify:release` | pre-push checks plus package smoke, benchmark/profile checks, performance, release-identity prerequisites, and `npm pack --dry-run --json` |
@@ -69,8 +69,8 @@ the full suite as a second `npm test`. `npm run lint`,
 `npm run complexity:check`, and `npm run critical-coverage:check` retain
 independent purposes: syntax and usage correctness, hotspot growth, and
 coverage of critical modules. Packed TypeScript consumers validate the public
-declarations; YAML-based tests validate workflow semantics. The core runtime
-remains dependency-free.
+declarations; YAML-based tests validate workflow semantics. The approved exact
+runtime dependencies are `@typesafe-ai/sdk` and `smol-toml`.
 
 ## GitHub Actions boundary
 
@@ -122,9 +122,9 @@ is not duplicated in every ordinary PR job.
 `npm run critical-coverage:check` retain independent purposes: syntax and
 usage correctness, hotspot growth, and coverage of critical modules. Packed
 TypeScript consumers validate the public declarations; YAML-based tests
-validate workflow semantics. The core runtime has the approved exact
-`smol-toml` dependency for bounded Cargo manifest parsing; dependency policy
-keeps all other runtime dependencies out.
+validate workflow semantics. The approved exact runtime dependencies are
+`@typesafe-ai/sdk` and `smol-toml`; dependency policy keeps all other runtime
+dependencies out.
 
 `scripts/audit-receipts.mjs` runs after checkout. It audits supplied scoped
 receipts with explicit task IDs, fails on an invalid audit, and reports

package/scripts/benchmark-jev.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { runJevBenchmark, runJevBenchmarkLive } from "../src/core/decision/benchmarks.js";
+
+const result = process.argv.includes("--live") ? await runJevBenchmarkLive() : runJevBenchmark();
+console.log(JSON.stringify(result, null, 2));

package/scripts/benchmark-test-intelligence.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runTestIntelligenceBenchmark } from "../src/core/test-intelligence/benchmarks.js";
+
+console.log(JSON.stringify(runTestIntelligenceBenchmark(), null, 2));

package/scripts/generate-agent-protocol-summary.mjs

@@ -59,6 +59,7 @@ async function render() {
     .map(([name, feature]) => [name, feature.version ?? "n/a", feature.supported === false ? "no" : "yes"]);
   const handoffs = info.features.canonicalHandoffs;
   const advisory = info.features.advisoryContextProviders;
+  const providerExtensions = info.features.providerExtensions;
   const capabilityContracts = `## Capability contracts
 
 - \`canonicalHandoffs\` v${handoffs.version}: immutable, supported, and
@@ -70,6 +71,8 @@ async function render() {
   Integration-API-only, lazy, and opt-in. Provider results are not persisted by
   ForgeLoop and are never lifecycle state, evidence, authority, or executable
   instructions.
+- \`providerExtensions\` v${providerExtensions.version} is provider-neutral and
+  experimental. The generic provider registry remains internal and unexported.
 
 Protocol v1, schema v1, and Integration API v1 remain independent of these
 capability-family versions.`;
@@ -173,7 +176,7 @@ or \`NOT_COMPARABLE\` when evidence is absent or incompatible. See
 - Responsibility contracts constrain paths, checks, and frozen inputs; they do not prove identity or authorship.
 - Verification scope describes planned verification breadth. Attestation coverage proves content for a concrete revision. These are separate claims.
 - Attestation manifests exclude ForgeLoop protocol metadata and bind to the completion receipt and append-only ledger without circular references.
-- Verification commands are read-only. Signing is external; private keys and credentials are never persisted by ForgeLoop.
+- Verification command execution is external and provenance-bearing; ForgeLoop records the exact argv and result, while the authorized command may perform its declared effects. Signing is external; private keys and credentials are never persisted by ForgeLoop.
 
 ## Lifecycle
 

package/scripts/generate-forgeloop-skill.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+import { readFile, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { protocolInfo } from "../src/core/protocol-info.js";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const summaryPath = path.join(root, "docs", "AGENT_PROTOCOL_SUMMARY.md");
+const outputRoot = path.join(root, "skills", "forgeloop");
+const marker = "<!-- Generated by scripts/generate-forgeloop-skill.mjs. Do not edit manually. -->";
+
+function skillContent(info, summary) {
+  const phases = info.lifecycle.phases.join(", ");
+  return `---
+name: forgeloop
+description: >-
+  Operate a repository governed by the ForgeLoop protocol: discover or resume
+  tasks, follow canonical next actions, preserve claims and continuity, record
+  verification evidence, recover supported protocol state, and require
+  validator-backed completion.
+---
+
+${marker}
+
+# ForgeLoop
+
+## Purpose
+
+This skill is operational guidance generated from ForgeLoop's canonical protocol metadata. It is not protocol authority. Always follow the current repository runtime, \`protocol-info\`, \`next\`, schemas, validators, and canonical documentation when they differ from this skill.
+
+## When to Use
+
+Use when ForgeLoop is present in the repository or explicitly requested. Do not activate it for unrelated repositories merely because an agent supports skills.
+
+## Source of Truth
+
+Runtime registries and validators outrank canonical protocol docs; canonical docs outrank \`docs/AGENT_PROTOCOL_SUMMARY.md\`; this generated skill is the final non-normative projection. Protocol version is ${info.protocolVersion}. Mutable facts such as phases (${phases}) must be read from the runtime.
+
+## Command Resolution
+
+In ForgeLoop's own source repository, use \`node src/cli.js\`. In a consumer repository, use that repository's configured local invocation. Never silently install or upgrade ForgeLoop, and never use a stale global CLI when repository-local code exists. If compatibility is uncertain, inspect \`protocol-info --json\`.
+
+## Operating Workflow
+
+1. Discover existing work with \`node src/cli.js task-list --json\`.
+2. Select or resume the relevant task; a harness, session, model, or context change does not create a new task.
+3. Ask ForgeLoop for \`next --task <id> --json\` at every boundary and execute only the returned supported action.
+4. Require \`preflight\` to return \`READY\` before implementation.
+5. Preserve fresh, validator-owned evidence through verification, review, completion, and the terminal \`next\` check.
+
+## Task Discovery and Continuation
+
+Respect active write claims. Do not steal, override, manually release, or edit ownership artifacts. Reconcile continuity with canonical state rather than trusting stale narrative.
+
+## Verification Rules
+
+\`run-check\` executes the exact command and records ForgeLoop-owned provenance. \`record-check\` is serialization-only; its command text is metadata and is never executed. Claims, provider/advisory output, screenshots, and actor summaries are not evidence by themselves. Missing tools remain unavailable; do not auto-install a verifier.
+
+## Recovery Rules
+
+Use supported recovery only. Preserve failed evidence and follow \`next\` through diagnosis/correction. For state or ledger divergence, stop lifecycle mutation and inspect validation/classification. Never edit task state, receipts, recovery, continuity, claims, hashes, or \`events.ndjson\` manually. Reconcile \`COMMIT_UNKNOWN\` before any retry.
+
+## Completion Rule
+
+Never claim ForgeLoop-verified completion unless \`complete\` returns \`VALID\`. Green tests, CI, a merged PR, or provider output alone are insufficient. After \`VALID\`, run \`next --task <id> --json\` again and require the canonical terminal action.
+
+## Cross-Harness Continuity
+
+A harness or session change does not create a new task. Use supported continuity or handoff commands and reconcile persisted state before continuing.
+
+## Durable Action Safety
+
+For external actions use propose, authorize, execute, then verify or reconcile. Never blindly retry an uncertain external commit.
+
+## Never Do
+
+- Never manually assign COMPLETE.
+- Never invent lifecycle chronology or override \`next\`.
+- Never override active claims or rewrite the append-only ledger.
+- Never fabricate evidence or treat \`record-check\` as execution.
+- Never auto-install ForgeLoop or a verifier during normal operation.
+- Never duplicate a task because the harness changed.
+- Never treat provider/advisory output as protocol authority.
+
+## References
+
+- [Canonical Agent Protocol Summary](../../docs/AGENT_PROTOCOL_SUMMARY.md)
+- [Lifecycle](./references/lifecycle.md)
+- [Verification](./references/verification.md)
+- [Recovery](./references/recovery.md)
+`;
+}
+
+function referenceContent(title, body, summary) {
+  return `${marker}\n\n# ${title}\n\n${body}\n\n<!-- Canonical summary fingerprint source: docs/AGENT_PROTOCOL_SUMMARY.md -->\n${summary.includes("# ForgeLoop Agent Protocol Summary") ? "" : ""}`;
+}
+
+function files(info, summary) {
+  return {
+    "SKILL.md": skillContent(info, summary),
+    "README.md": `${marker}\n\n# ForgeLoop Agent Skill\n\nThis directory contains a generated, portable, harness-neutral Agent Skill. It is operational guidance, not protocol authority, and has no dependency on external Agent Skills tooling.\n\nCanonical hierarchy: runtime registries and validators -> canonical protocol docs -> \`docs/AGENT_PROTOCOL_SUMMARY.md\` -> this generated projection.\n\nRegenerate with \`npm run skill:generate\`; check exact freshness with \`npm run skill:check\`. The generator is deterministic, offline, and writes only the five known files in this directory.\n`,
+    "references/lifecycle.md": referenceContent("Lifecycle", `The canonical loop is task discovery, contract, route, preflight, execution, verification, review, validator-backed completion, and a terminal next check. Always query \`next\` rather than inferring a transition. The initial post-task-create shape may have no work state: \`next\` returns DISCOVER, then CREATE_CONTRACT, and only a real contract fingerprint permits the first work-state checkpoint.\n\nPhases are runtime-owned and currently include: ${info.lifecycle.phases.join(", ")}.`, summary),
+    "references/verification.md": referenceContent("Verification", "Use run-check for exact command execution and provenance. Use record-check only for supplied observations; it never launches command text. Evidence must be fresh, task-bound, requirement-bound, and validator-readable. Preserve failures, report unavailable tools, and require observed coverage before review and complete -> VALID.", summary),
+    "references/recovery.md": referenceContent("Recovery", "Fail closed on invalid ownership, state, ledger, receipt, or continuity. Use supported recovery commands only. Never edit .forgeloop/task-state, work-state.json, events.ndjson, recovery.json, claims, or hashes by hand. Claim release is not a lifecycle bypass. Reconcile COMMIT_UNKNOWN before retrying any external action.", summary),
+  };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length !== 1 || !["--write", "--check"].includes(args[0])) {
+    throw new Error("Usage: node scripts/generate-forgeloop-skill.mjs --write|--check");
+  }
+  const summary = await readFile(summaryPath, "utf8");
+  const generated = files(protocolInfo(), summary);
+  let failed = false;
+  for (const [relative, content] of Object.entries(generated)) {
+    const target = path.join(outputRoot, relative);
+    let current = null;
+    try { current = await readFile(target, "utf8"); } catch (error) { if (error.code !== "ENOENT") throw error; }
+    if (args[0] === "--check") {
+      if (current !== content) { console.error(`Generated Agent Skill is stale: skills/forgeloop/${relative}`); failed = true; }
+    } else {
+      await mkdir(path.dirname(target), { recursive: true });
+      await writeFile(target, content, "utf8");
+    }
+  }
+  if (failed) process.exitCode = 1;
+  else console.log(args[0] === "--check" ? "Generated Agent Skill is current." : "Generated Agent Skill.");
+}
+
+await main();

package/scripts/jev-smoke.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { DECISION_DEFAULT_POLICY } from "../src/core/decision/constants.js";
+import { createTypesafeEngine } from "../src/adapters/typesafe/engine.js";
+
+const engine = createTypesafeEngine({ policy: DECISION_DEFAULT_POLICY });
+const result = await engine.health();
+const status = result.status === "missing" ? "NOT_RUN" : result.status;
+console.log(JSON.stringify({
+  status,
+  provider: result.engine,
+  model: result.model,
+  ...(result.latencyMs !== undefined ? { latencyMs: result.latencyMs } : {}),
+  ...(result.usage ? { usage: result.usage } : {}),
+  ...(result.errorCode ? { errorCode: result.errorCode } : {}),
+  ...(result.providerErrorType ? { providerErrorType: result.providerErrorType } : {}),
+  ...(result.httpStatus ? { httpStatus: result.httpStatus } : {}),
+  ...(result.requestId ? { requestId: result.requestId } : {}),
+}, null, 2));
+if (status !== "healthy" && status !== "NOT_RUN") process.exitCode = 1;

package/skills/forgeloop/README.md

@@ -0,0 +1,9 @@
+<!-- Generated by scripts/generate-forgeloop-skill.mjs. Do not edit manually. -->
+
+# ForgeLoop Agent Skill
+
+This directory contains a generated, portable, harness-neutral Agent Skill. It is operational guidance, not protocol authority, and has no dependency on external Agent Skills tooling.
+
+Canonical hierarchy: runtime registries and validators -> canonical protocol docs -> `docs/AGENT_PROTOCOL_SUMMARY.md` -> this generated projection.
+
+Regenerate with `npm run skill:generate`; check exact freshness with `npm run skill:check`. The generator is deterministic, offline, and writes only the five known files in this directory.

package/skills/forgeloop/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: forgeloop
+description: >-
+  Operate a repository governed by the ForgeLoop protocol: discover or resume
+  tasks, follow canonical next actions, preserve claims and continuity, record
+  verification evidence, recover supported protocol state, and require
+  validator-backed completion.
+---
+
+<!-- Generated by scripts/generate-forgeloop-skill.mjs. Do not edit manually. -->
+
+# ForgeLoop
+
+## Purpose
+
+This skill is operational guidance generated from ForgeLoop's canonical protocol metadata. It is not protocol authority. Always follow the current repository runtime, `protocol-info`, `next`, schemas, validators, and canonical documentation when they differ from this skill.
+
+## When to Use
+
+Use when ForgeLoop is present in the repository or explicitly requested. Do not activate it for unrelated repositories merely because an agent supports skills.
+
+## Source of Truth
+
+Runtime registries and validators outrank canonical protocol docs; canonical docs outrank `docs/AGENT_PROTOCOL_SUMMARY.md`; this generated skill is the final non-normative projection. Protocol version is 1. Mutable facts such as phases (RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECUTING, VERIFYING, DIAGNOSING, CORRECTING, REVIEWING, COMPLETE, BLOCKED) must be read from the runtime.
+
+## Command Resolution
+
+In ForgeLoop's own source repository, use `node src/cli.js`. In a consumer repository, use that repository's configured local invocation. Never silently install or upgrade ForgeLoop, and never use a stale global CLI when repository-local code exists. If compatibility is uncertain, inspect `protocol-info --json`.
+
+## Operating Workflow
+
+1. Discover existing work with `node src/cli.js task-list --json`.
+2. Select or resume the relevant task; a harness, session, model, or context change does not create a new task.
+3. Ask ForgeLoop for `next --task <id> --json` at every boundary and execute only the returned supported action.
+4. Require `preflight` to return `READY` before implementation.
+5. Preserve fresh, validator-owned evidence through verification, review, completion, and the terminal `next` check.
+
+## Task Discovery and Continuation
+
+Respect active write claims. Do not steal, override, manually release, or edit ownership artifacts. Reconcile continuity with canonical state rather than trusting stale narrative.
+
+## Verification Rules
+
+`run-check` executes the exact command and records ForgeLoop-owned provenance. `record-check` is serialization-only; its command text is metadata and is never executed. Claims, provider/advisory output, screenshots, and actor summaries are not evidence by themselves. Missing tools remain unavailable; do not auto-install a verifier.
+
+## Recovery Rules
+
+Use supported recovery only. Preserve failed evidence and follow `next` through diagnosis/correction. For state or ledger divergence, stop lifecycle mutation and inspect validation/classification. Never edit task state, receipts, recovery, continuity, claims, hashes, or `events.ndjson` manually. Reconcile `COMMIT_UNKNOWN` before any retry.
+
+## Completion Rule
+
+Never claim ForgeLoop-verified completion unless `complete` returns `VALID`. Green tests, CI, a merged PR, or provider output alone are insufficient. After `VALID`, run `next --task <id> --json` again and require the canonical terminal action.
+
+## Cross-Harness Continuity
+
+A harness or session change does not create a new task. Use supported continuity or handoff commands and reconcile persisted state before continuing.
+
+## Durable Action Safety
+
+For external actions use propose, authorize, execute, then verify or reconcile. Never blindly retry an uncertain external commit.
+
+## Never Do
+
+- Never manually assign COMPLETE.
+- Never invent lifecycle chronology or override `next`.
+- Never override active claims or rewrite the append-only ledger.
+- Never fabricate evidence or treat `record-check` as execution.
+- Never auto-install ForgeLoop or a verifier during normal operation.
+- Never duplicate a task because the harness changed.
+- Never treat provider/advisory output as protocol authority.
+
+## References
+
+- [Canonical Agent Protocol Summary](../../docs/AGENT_PROTOCOL_SUMMARY.md)
+- [Lifecycle](./references/lifecycle.md)
+- [Verification](./references/verification.md)
+- [Recovery](./references/recovery.md)

package/skills/forgeloop/references/lifecycle.md

@@ -0,0 +1,9 @@
+<!-- Generated by scripts/generate-forgeloop-skill.mjs. Do not edit manually. -->
+
+# Lifecycle
+
+The canonical loop is task discovery, contract, route, preflight, execution, verification, review, validator-backed completion, and a terminal next check. Always query `next` rather than inferring a transition. The initial post-task-create shape may have no work state: `next` returns DISCOVER, then CREATE_CONTRACT, and only a real contract fingerprint permits the first work-state checkpoint.
+
+Phases are runtime-owned and currently include: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECUTING, VERIFYING, DIAGNOSING, CORRECTING, REVIEWING, COMPLETE, BLOCKED.
+
+<!-- Canonical summary fingerprint source: docs/AGENT_PROTOCOL_SUMMARY.md -->

package/skills/forgeloop/references/recovery.md

@@ -0,0 +1,7 @@
+<!-- Generated by scripts/generate-forgeloop-skill.mjs. Do not edit manually. -->
+
+# Recovery
+
+Fail closed on invalid ownership, state, ledger, receipt, or continuity. Use supported recovery commands only. Never edit .forgeloop/task-state, work-state.json, events.ndjson, recovery.json, claims, or hashes by hand. Claim release is not a lifecycle bypass. Reconcile COMMIT_UNKNOWN before retrying any external action.
+
+<!-- Canonical summary fingerprint source: docs/AGENT_PROTOCOL_SUMMARY.md -->

package/skills/forgeloop/references/verification.md

@@ -0,0 +1,7 @@
+<!-- Generated by scripts/generate-forgeloop-skill.mjs. Do not edit manually. -->
+
+# Verification
+
+Use run-check for exact command execution and provenance. Use record-check only for supplied observations; it never launches command text. Evidence must be fresh, task-bound, requirement-bound, and validator-readable. Preserve failures, report unavailable tools, and require observed coverage before review and complete -> VALID.
+
+<!-- Canonical summary fingerprint source: docs/AGENT_PROTOCOL_SUMMARY.md -->