@mmerterden/multi-agent-pipeline 13.5.0 → 14.0.0

package/pipeline/schemas/criteria-manifest.schema.json

@@ -0,0 +1,228 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/criteria-manifest.schema.json",
+  "title": "Criteria manifest",
+  "description": "What the changed code was supposed to honour, resolved deterministically by skill-conformance.mjs BEFORE any reviewer runs. Produced in Phase 4 Step 1.78, consumed by the reviewer prompt assembly (the ${CRITERIA} block) and by the triage merge. Written to disk so the denominator of 'was this done completely' is fixed in advance and cannot be renegotiated by a reviewer after the fact.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "ledger",
+    "languages",
+    "registries",
+    "selectedRules",
+    "selectedRuleCount",
+    "coverage",
+    "findings"
+  ],
+  "properties": {
+    "schemaVersion": { "type": "string", "const": "1.0.0" },
+    "generatedFor": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "repoRoot": { "type": "string" },
+        "changedFileCount": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "ledger": {
+      "type": "object",
+      "description": "Phase 3's self-report about which skills it consulted, and how much of it the resolver could corroborate. Never the source of coverage: an unrecorded consultation and no consultation are byte-identical in state, so a percentage computed from self-report reads green over an empty set.",
+      "additionalProperties": false,
+      "required": ["source", "selfReport", "entryCount"],
+      "properties": {
+        "source": {
+          "type": "string",
+          "enum": ["derived", "mixed", "declared"],
+          "description": "derived = resolver only, no usable self-report (the default and the fail-safe). mixed = a self-report existed and was cross-checked against the resolver. declared = reserved; no consumer may treat self-report as sufficient on its own."
+        },
+        "selfReport": {
+          "type": "string",
+          "enum": ["absent", "empty", "declared"],
+          "description": "Three distinct states, deliberately not collapsed. absent = no telemetry.skillCalls[] key at all. empty = the key exists and is []. declared = at least one entry. Rendering absent as 'nothing was applied' would make the completeness claim unfalsifiable."
+        },
+        "entryCount": { "type": "integer", "minimum": 0 },
+        "entriesMissingTargetFiles": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Entries with no targetFiles[]. A skill applied to the wrong files still counts as 'applied' without this, so coverage cannot be attributed and the entry is corroborating nothing."
+        },
+        "declaredButNotResolved": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Skills Phase 3 claims it used that the resolver could not bind to any changed file. Flagged, not trusted."
+        },
+        "note": { "type": "string" }
+      }
+    },
+    "languages": {
+      "type": "object",
+      "description": "Language census of the diff by file extension, the deterministic substitute for Phase 1 detectedStack (which does not exist in the dev modes). Describes what the diff CONTAINS rather than what the repo is nominally built in.",
+      "additionalProperties": { "type": "integer", "minimum": 1 }
+    },
+    "registries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["name", "totalRules", "selectedRules", "droppedRules", "loadedAs"],
+        "properties": {
+          "name": { "type": "string" },
+          "rulesPath": { "type": "string" },
+          "version": { "type": ["string", "null"] },
+          "totalRules": { "type": "integer", "minimum": 0 },
+          "selectedRules": { "type": "integer", "minimum": 0 },
+          "droppedRules": { "type": "integer", "minimum": 0 },
+          "droppedReasons": {
+            "type": "object",
+            "additionalProperties": { "type": "integer", "minimum": 1 },
+            "description": "Reason to count. A dropped rule is reported, never silent: silently narrowing the rule set is indistinguishable from the code passing it."
+          },
+          "scopeDeclared": {
+            "type": "boolean",
+            "description": "False means the registry did not declare languages or paths. Such a registry loads as reference-only and contributes no rule IDs, because applying an undeclared rule set to an unknown language manufactures findings and buries the real ones."
+          },
+          "scopeLanguages": { "type": "array", "items": { "type": "string" } },
+          "languagesMatched": { "type": "array", "items": { "type": "string" } },
+          "inScopeFileCount": { "type": "integer", "minimum": 0 },
+          "notCovered": {
+            "type": "object",
+            "additionalProperties": { "type": "string" },
+            "description": "Languages the registry explicitly disclaims. Quoted into the coverage gap so the report names WHY nothing applied."
+          },
+          "loadedAs": {
+            "type": "string",
+            "enum": ["rule-checklist", "reference-only", "not-applicable"],
+            "description": "rule-checklist = its rule IDs entered the denominator. reference-only = readable context, no IDs (undeclared scope). not-applicable = in scope by language but no changed file matched its paths."
+          },
+          "referenceOnlyReason": { "type": "string" },
+          "toolchains": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "tool": { "type": "string" },
+                "wired": { "type": "boolean" },
+                "configCandidates": { "type": "array", "items": { "type": "string" } }
+              }
+            },
+            "description": "Linters the registry delegates its mechanical rules to. An unwired toolchain is itself a finding: those rules are unverified, and a review reporting no violations for them is reporting that nothing was measured."
+          },
+          "exceptionMarker": { "type": ["string", "null"] }
+        }
+      }
+    },
+    "unparseableRegistries": {
+      "type": "array",
+      "description": "Declared registries that could not be read. Non-empty makes the gate exit 2 (fail closed): continuing would drop a whole rule set from the denominator and report a clean review over criteria never loaded.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string" },
+          "path": { "type": "string" },
+          "reason": { "type": "string" }
+        }
+      }
+    },
+    "selectedRules": {
+      "type": "array",
+      "description": "The denominator. Every entry must come back from the reviewers with a verdict or an explicit waiver; an ID that is neither checked nor waived fails the stage.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["ruleId", "registry", "severity", "enforcement", "files"],
+        "properties": {
+          "ruleId": { "type": "string", "minLength": 1 },
+          "registry": { "type": "string" },
+          "severity": { "type": "string", "enum": ["blocking", "important", "suggestion"] },
+          "enforcement": { "type": "string", "enum": ["format", "lint", "scan", "judgement"] },
+          "files": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
+          "statusDeclared": {
+            "type": "boolean",
+            "description": "Whether the rule carried an explicit status. No shipped registry populates status today, so a missing one means active and is recorded rather than assumed."
+          }
+        }
+      }
+    },
+    "selectedRuleCount": { "type": "integer", "minimum": 0 },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "changedFiles",
+        "filesWithRuleCriteria",
+        "filesWithoutRuleCriteria",
+        "declaredGaps"
+      ],
+      "properties": {
+        "changedFiles": { "type": "integer", "minimum": 0 },
+        "filesWithRuleCriteria": { "type": "integer", "minimum": 0 },
+        "filesWithoutRuleCriteria": { "type": "integer", "minimum": 0 },
+        "uncoveredFiles": { "type": "array", "items": { "type": "string" } },
+        "declaredGaps": {
+          "type": "array",
+          "description": "A language in the diff that no registry covers. Declared explicitly so 'no rule applied' is distinguishable from 'every rule passed'.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["language", "fileCount", "reason"],
+            "properties": {
+              "language": { "type": "string" },
+              "fileCount": { "type": "integer", "minimum": 1 },
+              "files": { "type": "array", "items": { "type": "string" } },
+              "reason": { "type": "string" },
+              "consequence": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "moduleGuides": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "guides": { "type": "array", "items": { "type": "string" } },
+        "dropped": { "type": "array", "items": { "type": "string" } },
+        "cap": { "type": "integer", "minimum": 1 }
+      },
+      "description": "In-repo convention guides on the changed files' directory chains. One criteria source inside this manifest, not a parallel list."
+    },
+    "findings": {
+      "type": "array",
+      "description": "Deterministic findings, reviewer-shaped so Step 3.0 merges them alongside the test-integrity set and triage adjudicates them instead of never seeing them.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["severity", "file", "line", "issue", "fix"],
+        "properties": {
+          "severity": { "type": "string", "enum": ["blocking", "important", "suggestion"] },
+          "file": { "type": "string", "minLength": 1 },
+          "line": { "type": "integer", "minimum": 0 },
+          "issue": { "type": "string", "minLength": 4 },
+          "fix": { "type": "string", "minLength": 4 },
+          "ruleId": { "type": "string" },
+          "criteriaSource": { "type": "string" }
+        }
+      }
+    },
+    "skillsRootsSearched": {
+      "type": "array",
+      "description": "Every candidate root that was PROBED, each flagged with whether it existed. Recorded because the skills root differs per host and scripts/ is installed without path rewriting, so an empty result must be attributable to a root rather than to an absence of registries. Earlier this listed only the roots that existed, which made it empty in exactly the case it exists to explain: zero roots produced [], leaving 'no registries installed' and 'wrong root' indistinguishable.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "existed"],
+        "properties": {
+          "path": { "type": "string" },
+          "existed": { "type": "boolean" }
+        }
+      }
+    },
+    "resolutionFailure": {
+      "type": ["string", "null"],
+      "description": "Non-null when criteria could not be resolved at all (no skills root existed). The gate exits 2 in that case: a manifest with zero selected rules makes validate-reviewer.mjs skip the conformance check, so the review would read as clean over criteria that were never loaded. An empty registry set inside a root that DOES exist is the different, legitimate case and stays exit 0 with a declared coverage gap."
+    }
+  }
+}

package/pipeline/schemas/migrations/prefs-2.4.0-to-2.5.0.mjs

@@ -0,0 +1,64 @@
+/**
+ * prefs-2.4.0-to-2.5.0.mjs  -  preference schema upgrade 2.4.0 -> 2.5.0
+ *
+ * v14.0.0 put Phase 4 Review into the four `--dev` mode phase sets and added the
+ * criteria-resolution stage (Phase 4 Step 1.78). Two preference keys follow:
+ *
+ *   - global.skillConformance.blockOnCoverageGap  (default FALSE)
+ *       Whether a declared coverage gap  -  a language in the diff that no rule
+ *       registry covers  -  halts the run. Default false on purpose: today only
+ *       Swift, plus the two store-compliance catalogs, ship a scoped registry, so
+ *       defaulting this true would block every Kotlin, Python, Node and
+ *       Objective-C run from the moment it lands. The gap is always REPORTED
+ *       either way; this only controls whether it stops the pipeline.
+ *
+ *       There is deliberately no key for the stage itself, and none for the
+ *       exception-expiry check, on the same grounds as Phase 4 Step 1.76: a run
+ *       that can switch off its own anti-reward-hacking control cannot be
+ *       trusted to report a pass.
+ *
+ *   - global.ship.autoFix  (default FALSE)
+ *       Already referenced by the tail command's spec as `prefs.global.finish
+ *       .autoFix` but never declared in the schema, so it could not validate and
+ *       a user setting it got no protection from `additionalProperties: false`.
+ *       Declared here under the command's new name (`finish` -> `ship`), and any
+ *       value the user had under the old key is carried over rather than dropped.
+ *
+ * Idempotent: safe on already-2.5.0 input. Non-destructive: an existing explicit
+ * value for either key is preserved.
+ *
+ * @param {object} data  -  parsed JSON content of the preferences file
+ * @returns {object}     -  same data with schemaVersion = "2.5.0"
+ */
+export default function migrate(data) {
+  const out = JSON.parse(JSON.stringify(data));
+
+  out.schemaVersion = "2.5.0";
+
+  if (!out.global) out.global = {};
+
+  if (typeof out.global.skillConformance !== "object" || out.global.skillConformance === null) {
+    out.global.skillConformance = {};
+  }
+  if (typeof out.global.skillConformance.blockOnCoverageGap !== "boolean") {
+    out.global.skillConformance.blockOnCoverageGap = false;
+  }
+
+  if (typeof out.global.ship !== "object" || out.global.ship === null) {
+    out.global.ship = {};
+  }
+  if (typeof out.global.ship.autoFix !== "boolean") {
+    // Carry the value across the finish -> ship rename instead of resetting it:
+    // a user who opted into auto-fix did so deliberately.
+    const legacy = out.global.finish?.autoFix;
+    out.global.ship.autoFix = typeof legacy === "boolean" ? legacy : false;
+  }
+  // The old key is not a declared property, so leaving it behind would fail
+  // validation against a closed `global`.
+  if (out.global.finish && typeof out.global.finish === "object") {
+    delete out.global.finish.autoFix;
+    if (Object.keys(out.global.finish).length === 0) delete out.global.finish;
+  }
+
+  return out;
+}