@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/docs/protocol-requirements.json

@@ -0,0 +1,101 @@
+{
+  "version": 1,
+  "requirements": {
+    "FL-CONT-001": {
+      "source": "LOOP_ENGINEERING.md",
+      "statement": "A receiving harness MUST reconcile continuity against the current work state and checkout before acting on it.",
+      "tests": ["tests/continuity.test.js", "tests/documentation-conformance.test.js"],
+      "validator": "src/core/continuity.js"
+    },
+    "FL-CLAIM-001": {
+      "source": "PROTOCOL_INTEGRATION.md",
+      "statement": "Every harness MUST consume the canonical validated claim-state resolver.",
+      "tests": ["tests/task-claim-state.test.js", "tests/task-recovery-tamper.test.js"],
+      "validator": "src/core/task-claim-state.js"
+    },
+    "FL-CLAIM-002": {
+      "source": "LOOP_ENGINEERING.md",
+      "statement": "Readers without task-recovery schema v1 support MUST refuse claim ownership mutation.",
+      "tests": ["tests/protocol-info.test.js", "tests/documentation-conformance.test.js"],
+      "validator": "scripts/validate_documentation_conformance.mjs"
+    },
+    "FL-CLAIM-003": {
+      "source": "PROTOCOL_INTEGRATION.md",
+      "statement": "A reader without validated claim projection MUST fail closed.",
+      "tests": ["tests/protocol-info.test.js", "tests/package.test.js"],
+      "validator": "src/core/protocol-info.js"
+    },
+    "FL-WS-001": {
+      "source": "LOOP_ENGINEERING.md",
+      "statement": "A bound task MUST validate the current workspace before a task mutation or ForgeLoop-owned verification launch.",
+      "tests": ["tests/workspace-binding.test.js", "tests/workspace-binding-run-check.test.js"],
+      "validator": "src/core/workspace-binding.js"
+    },
+    "FL-HANDOFF-001": {
+      "source": "LOOP_ENGINEERING.md",
+      "statement": "A canonical handoff MUST remain an immutable protocol-derived snapshot.",
+      "tests": ["tests/handoff-envelope.test.js"],
+      "validator": "src/core/handoff.js"
+    },
+    "FL-SCOPE-001": {
+      "source": "LOOP_ENGINEERING.md",
+      "statement": "A verification scope MUST narrow execution only from current canonical evidence.",
+      "tests": ["tests/verification-scope.test.js", "tests/verification-scope-freshness.test.js"],
+      "validator": "src/core/verification-scope.js"
+    },
+    "FL-ATTEST-001": {
+      "source": "LOOP_ENGINEERING.md",
+      "statement": "A code attestation MUST bind exact source content to a valid completion receipt and event-ledger checkpoint.",
+      "tests": ["tests/code-manifest.test.js", "tests/attestation.test.js", "tests/attestation-verifier.test.js"],
+      "validator": "src/core/attestation-verifier.js"
+    },
+    "FL-ATTEST-002": {
+      "source": "PROTOCOL_INTEGRATION.md",
+      "statement": "An integration MUST consume the canonical attestation result and preserve its trust distinctions.",
+      "tests": ["tests/generic-ci-attestation.test.js", "tests/integration-runtime.test.js"],
+      "validator": "src/core/command-runtime.js"
+    },
+    "FL-ATTEST-003": {
+      "source": "PROTOCOL_INTEGRATION.md",
+      "statement": "A signing integration MUST keep private keys, OIDC tokens, and credentials outside ForgeLoop artifacts.",
+      "tests": ["tests/signing-provider.test.js"],
+      "validator": "src/core/signing/"
+    },
+    "FL-SQ-001": {
+      "source": "LOOP_ENGINEERING.md",
+      "statement": "Structural-quality evidence MUST remain provider-neutral, task-bound, delta-first, and separate from behavioral, security, performance, accessibility, and publication truth.",
+      "tests": ["tests/structural-quality-policy.test.js", "tests/structural-quality-lifecycle.test.js"],
+      "validator": "src/core/structural-quality/service.js"
+    },
+    "FL-SQ-002": {
+      "source": "PROTOCOL_INTEGRATION.md",
+      "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.12.0",
+  "version": "1.14.0",
   "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",
@@ -51,12 +51,16 @@
     ".github/copilot-instructions.md",
     "README.md",
     "DOCS_INDEX.md",
+    "CONTRIBUTING.md",
+    "docs/documentation-manifest.json",
+    "docs/protocol-requirements.json",
     "docs/diagrams",
     "docs/assets/diagrams",
     "docs/GETTING_STARTED.md",
     "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",
@@ -65,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",
@@ -75,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",
@@ -103,6 +125,10 @@
   ],
   "scripts": {
     "test": "node scripts/run-tests.js",
+    "test:ci": "node scripts/run-tests.js --test-concurrency=2",
+    "test:watch": "node scripts/run-tests.js --watch",
+    "coverage:shard": "c8 --all --include=src/**/*.js --temp-directory=coverage-data npm run test:ci",
+    "coverage:report": "c8 --all --include=src/**/*.js --reporter=text --reporter=lcov --reporter=json-summary --temp-directory=coverage-data --check-coverage --lines=80 --functions=75 --branches=70 --statements=80 report",
     "pack:check": "node --test tests/package.test.js",
     "pack:smoke": "node scripts/package_smoke.mjs",
     "release:identity": "node scripts/verify_release_identity.mjs",
@@ -116,18 +142,20 @@
     "docs:report": "node scripts/report_documentation_health.mjs",
     "docs:check": "node scripts/run-docs-check.js",
     "lint": "eslint .",
-    "coverage": "c8 --all --include=src/**/*.js --reporter=text --reporter=lcov --reporter=json-summary --check-coverage --lines=80 --functions=75 --branches=70 --statements=80 node scripts/run-tests.js",
+    "coverage": "c8 --all --include=src/**/*.js --reporter=text --reporter=lcov --reporter=json-summary --check-coverage --lines=80 --functions=75 --branches=70 --statements=80 npm run test:ci",
     "dependency:policy": "node scripts/check-dependency-policy.mjs",
     "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",
+    "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",
@@ -140,7 +168,17 @@
     "benchmark:profiles:regression": "node scripts/check-efficiency-regression.mjs",
     "transactions:compact": "node scripts/compact-transactions.mjs",
     "complexity:check": "node scripts/check-complexity.mjs",
-    "repository-index:manifest": "node scripts/verify-tgrep-manifest.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",
+    "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",
@@ -148,6 +186,10 @@
     "typescript": "7.0.2",
     "yaml": "2.9.0"
   },
+  "dependencies": {
+    "@typesafe-ai/sdk": "0.6.0",
+    "smol-toml": "1.8.0"
+  },
   "exports": {
     ".": "./src/cli.js",
     "./integration": {

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/routing-input.schema.json

@@ -18,7 +18,7 @@
       "properties": {
         "schemaVersion": { "const": 1 },
         "scope": { "enum": ["MATCH", "UNSCOPED", "NO_MATCH", "NONE"] },
-        "frameworks": { "type": "array", "items": { "enum": ["flutter"] } },
+        "frameworks": { "type": "array", "items": { "enum": ["flutter", "dotnet", "aspnetcore", "abp", "nodejs", "rust", "c", "cpp", "java", "sql", "go", "typescript", "php", "swift"] } },
         "projectRoots": { "type": "array", "items": { "type": "string", "minLength": 1 } },
         "primarySignals": { "type": "array", "items": { "type": "string", "minLength": 1 } },
         "supportingSignals": { "type": "array", "items": { "type": "string", "minLength": 1 } }

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

@@ -41,26 +41,99 @@ Maintainers should distinguish between actual documentation link failures and ex
 - **Link-content failure (`Lychee`)**: The link checking step runs with `--verbose` and outputs the exact failing URL along with the HTTP status code (e.g. 404, 403). If a documentation URL is broken, update the link in the source Markdown. If a legitimate external host blocks shared CI runners or aggressively rate-limits CI automation, add a minimal, targeted exclusion in `.lychee.toml` with an explanatory comment.
 - **Action-download / Runner infrastructure failure (GitHub 429/502/503)**: When GitHub Actions fails during action checkout or tool download before running the test steps, this is a transient infrastructure issue rather than a project defect. Rerun the workflow without modifying project files.
 
-## Node verification and receipt availability
+## Validation tiers
 
-The documentation workflow runs the documentation/tooling gates once on
-Linux with Node 24. Full suites cover Linux 20/22/24 and macOS/Windows 20/24,
-with no repeated platform/version pair in that workflow. Node 24 Linux also
-collects coverage. Package-content tests share one pack listing within their
-process. The dedicated Windows main-branch workflow remains separate.
+The local runner makes the validation boundary explicit and never installs a
+missing tool implicitly:
 
-The historical required status `validate (22)` is retained as an aggregate
-gate over validation, the full portability matrix, and diagram checks. It
-fails if any prerequisite fails, is cancelled, or is skipped. This preserves
-the existing branch ruleset without running another duplicate test suite.
+| Tier | Command | Intended use |
+| --- | --- | --- |
+| 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` |
+
+Run `npm run mcp:setup` explicitly when the MCP package is not installed and
+the MCP checks are in scope. If Python or another external validator is
+unavailable, report `NOT_VERIFIED`; do not turn an unavailable check into a
+pass by installing an unapproved tool.
+
+The release tier reports `NOT_VERIFIED` until both
+`FORGELOOP_RELEASE_VERSION` and `FORGELOOP_RELEASE_COMMIT` are supplied. When
+present, those values are passed to the canonical `release:identity` command;
+the runner never invents a release SHA or treats a pre-publication identity as
+valid.
+
+`npm run verify:prepush` deliberately runs coverage once and does not repeat
+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 approved exact
+runtime dependencies are `@typesafe-ai/sdk` and `smol-toml`.
+
+## GitHub Actions boundary
+
+Ordinary pull requests use `.github/workflows/pr-core.yml`. It preserves the
+ruleset's exact required contexts:
+
+- `audit`
+- `CodeQL`
+- `Verify generated Archify diagram`
+- `validate (22)`
+- `tarball smoke (ubuntu-latest)`
+- `dependency-review`
+
+`validate (22)` is an always-present, fail-closed aggregator over the core
+matrix and the path-applicable documentation, audit, package, and native
+Repository Index jobs. An optional Repository Index job may be skipped only
+when the classifier says that the change cannot affect it; the aggregator
+rejects every unexpected skip, failure, or cancellation. The aggregator is
+the status required by the branch ruleset, not a second copy of the Node
+suite.
+
+The path classifier is deterministic and testable locally:
+
+```bash
+node scripts/ci-scenario-check.mjs
+node scripts/ci-classify.mjs --paths README.md --json
+node scripts/ci-classify.mjs --all --json
+```
+
+Documentation-only pull requests use quick core validation plus the
+documentation/diagram path; the Node 20 matrix steps do not install or run for
+docs-only changes. Runtime and package changes use Node 20 compatibility checks
+and four Node 24 unit shards wrapped by the coverage gate, followed by a
+coverage-only aggregation. Repository Index changes retain the native reusable
+workflow and its platform matrix. Package
+smoke is Ubuntu-only on ordinary PRs and expands to macOS/Windows through the
+explicit release matrix. The main branch retains dedicated documentation,
+Node compatibility, package smoke, audit, and Windows full-suite workflows;
+those workflows are the place for broader post-merge or release validation.
+
+CodeQL and dependency review remain independent GitHub security gates. The
+repository's GitHub secret scanning and push protection remain enabled; the
+custom `scan_secrets.py` check is a local/pre-push compatibility validator and
+is not duplicated in every ordinary PR job.
+
+## Receipts and infrastructure failures
 
 `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.
+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
 `NOT_VERIFIED` when none are supplied. This repository job does not create
 lifecycle evidence from CI test results.
+
+Maintainers should distinguish actual validation failures from external
+CI/action infrastructure errors. A Lychee link failure identifies the exact
+URL and status; update Markdown or add only a targeted, explained exclusion
+for a legitimate shared-runner restriction. An action-download or runner
+failure before project steps begin (for example GitHub 429/502/503) is
+infrastructure and should be retried without changing project files.

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

@@ -7,6 +7,8 @@ import { fileURLToPath } from "node:url";
 import { ARTIFACT_REGISTRY } from "../src/core/artifact-registry.js";
 import { CLI_COMMAND_DEFINITIONS } from "../src/core/cli-command-definitions.js";
 import { PUBLIC_ERROR_REGISTRY } from "../src/core/error-codes.js";
+import { PROJECT_DETECTION_LIMITS, PROJECT_EVIDENCE_SCHEMA_VERSION } from "../src/core/project-detection.js";
+import { GUIDE_REGISTRY } from "../src/core/guide-registry.js";
 import { protocolInfo } from "../src/core/protocol-info.js";
 
 const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -43,6 +45,12 @@ function commandCatalog() {
     .join("\n\n");
 }
 
+function guideCatalog() {
+  const rows = Object.entries(GUIDE_REGISTRY)
+    .map(([id, definition]) => [id, definition.path, definition.install ? "yes" : "no"]);
+  return `## Guide registry\n\n${table(["Guide", "Path", "Installable"], rows)}`;
+}
+
 async function render() {
   const packageJson = JSON.parse(await readFile(path.join(repositoryRoot, "package.json"), "utf8"));
   const info = protocolInfo({ packageVersion: packageJson.version });
@@ -51,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
@@ -62,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.`;
@@ -95,6 +106,32 @@ Package version: ${packageJson.version}
 6. Run forgeloop complete; accept completion only when the validator returns VALID.
 7. Run forgeloop next again and follow the returned lifecycle action to a terminal state or an explicit blocker.
 
+## Project evidence and guide routing
+
+- The canonical guide registry is \`src/config/guides.json\`; the .NET
+  specialist has guide ID \`dotnet\` and resolves to
+  \`ENG/dotnet-aspnetcore-development-eng.md\`.
+- Project evidence schema v${PROJECT_EVIDENCE_SCHEMA_VERSION} recognizes
+  structurally parsed Flutter, SDK-style .NET, Node.js, Rust, C, C++, Java,
+  SQL, Go, TypeScript, PHP, and Swift project evidence. SQL remains a bounded
+  owned-file overlay, while same-root language identities compose. ASP.NET Core
+  and ABP are conditional overlays recorded as reasons on \`dotnet\`; they
+  are not standalone guide IDs, and route validation requires each overlay to
+  include \`dotnet\`.
+- Project detection is bounded by ${PROJECT_DETECTION_LIMITS.maxManifests}
+  manifests, ${PROJECT_DETECTION_LIMITS.maxSolutionFiles} solution files,
+  ${PROJECT_DETECTION_LIMITS.maxManifestBytes} bytes per manifest,
+  ${PROJECT_DETECTION_LIMITS.maxSourceFiles} supporting source files,
+  ${PROJECT_DETECTION_LIMITS.maxSourceBytes} bytes per source file,
+  ${PROJECT_DETECTION_LIMITS.maxVisitedDirectories} visited directories, and
+  ${PROJECT_DETECTION_LIMITS.maxVisitedEntries} visited entries. It skips
+  symlinks and configured generated/vendor directories; exhausted budgets fail
+  closed rather than producing unbounded discovery.
+- Task ownership discovery is a separate exhaustive operation. Task-list
+  filters and pagination project the validated discovery result and do not
+  remove ledger or recovery evidence. See \`GUIDE_ROUTER.md\` and
+  \`docs/CLI_REFERENCE.md\` for the operator-facing contracts.
+
 ## Adaptive execution profiles
 
 \`complianceMode\` controls how strongly project policy is enforced. The
@@ -139,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
 
@@ -151,6 +188,8 @@ ${table(["Feature", "Version", "Supported"], features)}
 
 ${capabilityContracts}
 
+${guideCatalog()}
+
 ## Public artifact registry
 
 ${table(["Key", "Scope", "Path", "Schema", "Trust role"], artifacts)}