@cassiomc1/forgeloop 1.2.4 → 1.5.0

package/docs/UNIVERSAL_INTEGRATION.md

@@ -0,0 +1,48 @@
+# Universal ForgeLoop Integration
+
+ForgeLoop applies to any agent, harness, IDE, or orchestration runtime — with
+or without MCP. The universal rule:
+
+> If the active host exposes an official ForgeLoop structured integration,
+> prefer it for protocol operations. Otherwise use the project-local ForgeLoop
+> CLI. Never manually synthesize ForgeLoop-managed lifecycle, claim, recovery,
+> ledger, or completion state because an integration is unavailable.
+
+## The programmatic integration API
+
+`@cassiomc1/forgeloop/integration` (integration API version 1) is the
+transport-neutral entrypoint:
+
+```js
+import {
+  executeForgeLoopCommand,
+  validateForgeLoopCommandInput,
+  getForgeLoopCapabilities,
+  classifyForgeLoopInvocation,
+  readForgeLoopIntegrationResource,
+} from "@cassiomc1/forgeloop/integration";
+```
+
+- `executeForgeLoopCommand({command, projectPath, input})` returns a
+  deterministic envelope: `{ok, command, exitCode, result, error, metadata}`.
+  Domain rejections (preflight BLOCKED, audit INVALID) keep `ok:true` with a
+  non-zero exit code; `ok:false` means the command could not be executed and
+  preserves the canonical public error code.
+- Ownership values always come from `resolveTaskClaimState()` through the
+  `task/ownership` resource — never derived from raw artifacts.
+- Invocation risk classes (READ_ONLY, LOOP_MUTATION, CLAIM_REACQUISITION,
+  EXTERNAL_EXECUTION, MAINTENANCE, CLAIM_RELEASE_RECOVERY, LEGACY_MIGRATION,
+  FORCE_DESTRUCTIVE) describe what an invocation would do; launch policy
+  decides what is allowed.
+
+## Consumers
+
+| Surface | Entry |
+| --- | --- |
+| ForgeLoop CLI | human terminal rendering over the same executors |
+| ForgeLoop MCP | `@cassiomc1/forgeloop-mcp`: stdio (default/recommended) plus optional strict-modern loopback-only HTTP; see [MCP.md](./MCP.md) |
+| Studio / IDE / CI adapters | the same integration subpath |
+
+All consumers share one protocol authority: `.forgeloop/` state written only
+by canonical ForgeLoop commands, so cross-harness continuity and recovery work
+identically regardless of transport.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "1.2.4",
+  "version": "1.5.0",
   "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",
@@ -54,25 +54,39 @@
     "docs/TROUBLESHOOTING.md",
     "docs/RECIPES.md",
     "docs/DOCUMENTATION_GUIDE.md",
-    "scripts/CI_VALIDATORS.md"
+    "docs/RELEASE_CHECKLIST_1_4.md",
+    "scripts/CI_VALIDATORS.md",
+    "docs/MCP.md",
+    "docs/UNIVERSAL_INTEGRATION.md",
+    "docs/RELEASE_CHECKLIST_1_5_MCP.md"
   ],
   "scripts": {
     "test": "node scripts/run-tests.js",
     "pack:check": "node --test tests/package.test.js",
+    "pack:smoke": "node scripts/package_smoke.mjs",
     "release:identity": "node scripts/verify_release_identity.mjs",
     "docs:flow": "node scripts/generate-readme-flow.mjs",
     "docs:diagram:check": "node scripts/check-generated-diagram.mjs",
     "docs:generate": "node scripts/generate_documentation_reference.mjs --write",
     "docs:generated:check": "node scripts/generate_documentation_reference.mjs --check",
     "docs:conformance": "node scripts/validate_documentation_conformance.mjs",
+    "docs:examples:check": "node scripts/validate_documentation_examples.mjs",
+    "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 --check-coverage --lines=80 --functions=75 --branches=70 --statements=80 node scripts/run-tests.js",
-    "dependency:policy": "node scripts/check-dependency-policy.mjs"
+    "dependency:policy": "node scripts/check-dependency-policy.mjs",
+    "mcp:test": "node --test integrations/mcp/tests/*.test.js",
+    "mcp:setup": "node scripts/mcp-setup.mjs",
+    "mcp:pack:check": "node scripts/mcp-package-smoke.mjs"
   },
   "devDependencies": {
     "@mermaid-js/mermaid-cli": "^11.16.0",
     "c8": "^12.0.0",
     "eslint": "^9.39.5"
+  },
+  "exports": {
+    ".": "./src/cli.js",
+    "./integration": "./src/integration.js"
   }
 }

package/schemas/execution.schema.json

@@ -57,7 +57,17 @@
     "startedAt": { "type": "string", "minLength": 1 },
     "finishedAt": { "type": "string", "minLength": 1 },
     "status": { "enum": ["passed", "failed"] },
-    "exitCode": { "oneOf": [{ "type": "integer", "minimum": 0 }, { "type": "null" }] }
+    "exitCode": { "oneOf": [{ "type": "integer", "minimum": 0 }, { "type": "null" }] },
+    "durationMs": { "type": "integer", "minimum": 0 },
+    "termination": { "enum": ["exit", "signal", "timeout", "spawn-error"] },
+    "signal": { "oneOf": [{ "type": "string", "minLength": 1 }, { "type": "null" }] },
+    "stdoutSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "stderrSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "stdoutBytes": { "type": "integer", "minimum": 0 },
+    "stderrBytes": { "type": "integer", "minimum": 0 },
+    "outputTruncated": { "type": "boolean" }
+    ,"timeoutMs": { "type": "integer", "minimum": 1 }
+    ,"terminationGraceMs": { "type": "integer", "minimum": 1 }
   },
   "additionalProperties": false
 }

package/schemas/task-recovery.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeloop://schemas/task-recovery.schema.json",
+  "title": "ForgeLoop Task Recovery State",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "protocolVersion",
+    "taskId",
+    "status",
+    "recoveredAt",
+    "recoveryId",
+    "recoveryEventSeq",
+    "classificationAtRecovery",
+    "reasonCodes",
+    "releasedClaims",
+    "previousPhase",
+    "previousRevision",
+    "repositoryFingerprint",
+    "authority"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "taskId": { "type": "string", "minLength": 1 },
+    "status": { "const": "RECOVERED" },
+    "recoveredAt": { "type": "string", "format": "date-time" },
+    "recoveryId": { "type": "string", "pattern": "^recovery-[A-Za-z0-9-]+$" },
+    "recoveryEventSeq": { "type": "integer", "minimum": 1 },
+    "classificationAtRecovery": { "enum": ["STALE", "ABANDONED", "LEGACY_BOUNDARY_MIGRATED"] },
+    "reasonCodes": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "releasedClaims": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "previousPhase": { "type": "string", "minLength": 1 },
+    "previousRevision": { "type": "integer", "minimum": 0 },
+    "repositoryFingerprint": {
+      "type": "object",
+      "required": ["branch", "head"],
+      "additionalProperties": false,
+      "properties": {
+        "branch": { "type": ["string", "null"] },
+        "head": { "type": ["string", "null"] }
+      }
+    },
+    "authority": {
+      "type": "object",
+      "required": ["kind"],
+      "additionalProperties": false,
+      "properties": {
+        "kind": { "enum": ["CALLER_ACKNOWLEDGED", "HOST_ATTESTED"] },
+        "grantRef": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/schemas/work-state.schema.json

@@ -59,6 +59,7 @@
     "failures": { "type": "array", "items": { "type": "object" } },
     "blockers": { "type": "array", "items": { "type": "object" } },
     "lastUpdated": { "type": "string", "minLength": 1 },
+    "revision": { "type": "integer", "minimum": 0 },
     "previousPhase": { "type": "string" },
     "diagnosedHypothesis": { "type": "string", "minLength": 1 },
     "verificationEvidence": { "type": "array", "items": { "type": "object" } },