@cassiomc1/forgeloop 1.0.0 → 1.1.0

package/docs/forgeloop-flow.mmd

@@ -1,5 +1,5 @@
 %% ForgeLoop canonical architecture flow. Render with npm run docs:flow.
-%%{init: {"look": "classic", "handDrawnSeed": 1, "flowchart": {"curve": "linear"}}}%%
+%%{init: {"look": "classic", "handDrawnSeed": 1, "flowchart": {"curve": "linear", "htmlLabels": false}}}%%
 flowchart LR
   classDef entry fill:#1f2937,stroke:#7dd3fc,color:#f8fafc,stroke-width:2px
   classDef contract fill:#172554,stroke:#60a5fa,color:#dbeafe,stroke-width:2px

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",
@@ -47,6 +47,13 @@
     "DOCS_INDEX.md",
     "docs/forgeloop-flow.mmd",
     "docs/assets/forgeloop-flow.svg",
+    "docs/GETTING_STARTED.md",
+    "docs/CROSS_HARNESS_CONTINUITY.md",
+    "docs/CLI_REFERENCE.md",
+    "docs/ARTIFACT_REFERENCE.md",
+    "docs/TROUBLESHOOTING.md",
+    "docs/RECIPES.md",
+    "docs/DOCUMENTATION_GUIDE.md",
     "scripts/CI_VALIDATORS.md"
   ],
   "scripts": {
@@ -54,7 +61,11 @@
     "pack:check": "node --test tests/package.test.js",
     "release:identity": "node scripts/verify_release_identity.mjs",
     "docs:flow": "node scripts/generate-readme-flow.mjs",
-    "docs:check": "node scripts/check-generated-diagram.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: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"

package/schemas/task-descriptor.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forgeloop.dev/schemas/task-descriptor.schema.json",
+  "title": "ForgeLoop Task Descriptor Schema",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "protocolVersion",
+    "taskId",
+    "taskKey",
+    "createdAt",
+    "updatedAt",
+    "writeClaims"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1,
+      "description": "Task descriptor schema version (must be 1)"
+    },
+    "protocolVersion": {
+      "type": "integer",
+      "const": 1,
+      "description": "ForgeLoop protocol version (must be 1)"
+    },
+    "taskId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Canonical human-readable task identifier"
+    },
+    "taskKey": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$",
+      "description": "SHA-256 hex digest of the canonical taskId (filesystem-safe namespace identifier)"
+    },
+    "createdAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 UTC creation timestamp"
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 UTC last updated timestamp"
+    },
+    "writeClaims": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Normalized project-relative path prefixes claimed for mutations by this task"
+    }
+  }
+}

package/schemas/work-state.schema.json

@@ -19,7 +19,24 @@
       },
       "additionalProperties": false
     },
-    "phase": { "type": "string", "minLength": 1 },
+    "phase": {
+      "type": "string",
+      "enum": [
+        "RECEIVED",
+        "DISCOVERING",
+        "CONTRACT_READY",
+        "ROUTED",
+        "DESIGNING",
+        "PLANNED",
+        "EXECUTING",
+        "VERIFYING",
+        "DIAGNOSING",
+        "CORRECTING",
+        "REVIEWING",
+        "COMPLETE",
+        "BLOCKED"
+      ]
+    },
     "selectedGuides": { "type": "array", "items": { "type": "string" } },
     "requiredGates": { "type": "array", "items": { "type": "string", "minLength": 1 } },
     "satisfiedGates": { "type": "array", "items": { "type": "string", "minLength": 1 } },

package/scripts/CI_VALIDATORS.md

@@ -30,3 +30,10 @@ python3 scripts/scan_secrets.py
 The Node suite and Python suite have separate ownership: Node tests cover CLI,
 protocol behavior, schemas, and execution evidence; Python remains the
 compatibility gate for these repository-wide textual invariants.
+
+## Distinguishing CI Link vs Infrastructure Failures
+
+Maintainers should distinguish between actual documentation link failures and external CI/action infrastructure errors:
+
+- **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.