feat(ecosystem-sync): report-only drift orchestrator + ecosystem.json (safe slice) (#1)

* feat(ecosystem-sync): report-only drift orchestrator + ecosystem.json manifest (safe slice)

Stands up the ecosystem-sync home as a REPORT-ONLY safe slice:
- ecosystem.json — manifest of the 6 IEP repos (core, lab, audit-harness, j-rig,
  rollout-gate, dashboard) with kind + version_source + pinned_version. Lists
  claude-code-plugins under "excluded" (bespoke in-flight CI/CD — coordinate first,
  sequence last; never bolt generic automation on).
- scripts/ecosystem-drift.py — reads the manifest, resolves live upstream (npm / git
  tag), reports drift. Opens NO PRs, mutates nothing, always exits 0 (advisory).
- .github/workflows/ecosystem-drift.yml — weekly + on-manifest-change; contents:read
  only, so it structurally cannot open PRs. Writes report to the run summary.
- README — documents the manifest, the report-only guarantee, and the exclusion.

Deferred (separate, explicitly-reviewed change): live auto-PR authority and folding
in claude-code-plugins.

* harden(ecosystem-drift): UA header + defensive guards per review

Address 6 medium-priority review findings on the report-only drift checker:
- centralize a descriptive User-Agent in _get_json (avoids GitHub/npm
  rejecting/throttling the default urllib UA)
- guard empty package/gh args in npm_latest + newest_tag
- resolve() reads package/gh via .get() (no KeyError on malformed manifest)
- main() / excluded loop read name via .get(..., "unknown")

Safe-slice guarantees unchanged: read-only, opens no PRs, always exits 0.

---------

Co-authored-by: jeremylongshore <jeremylongshore@users.noreply.github.com>

Author: jeremylongshore

.github/workflows/ecosystem-drift.yml

@@ -0,0 +1,36 @@
+name: Ecosystem drift (report-only)
+
+# SAFE SLICE: this workflow only REPORTS drift. It has read-only permissions and
+# opens no PRs. Granting write/PR authority is a separate, explicitly-reviewed change.
+
+on:
+  schedule:
+    - cron: "0 6 * * 1" # Mondays 06:00 UTC — weekly drift report
+  workflow_dispatch: {}
+  push:
+    branches: [main]
+    paths:
+      - "ecosystem.json"
+      - "scripts/ecosystem-drift.py"
+      - ".github/workflows/ecosystem-drift.yml"
+
+permissions:
+  contents: read # read-only by design — no PR/commit authority
+
+concurrency:
+  group: ecosystem-drift-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  drift:
+    name: Report ecosystem version drift
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Run report-only drift checker
+        env:
+          GITHUB_TOKEN: ${{ github.token }} # for GitHub API rate limits on tag lookups (read-only)
+        run: python3 scripts/ecosystem-drift.py

README.md

@@ -107,4 +107,28 @@ You don't have to trust any of it — that's the point. Verify it yourself.
 
 ---
 
+## Ecosystem manifest + drift report (report-only)
+
+[`ecosystem.json`](./ecosystem.json) is the machine-readable map of the six platform
+repos — each repo's kind, its release channel (npm or git tag), and the **pinned
+version** the platform considers current. [`scripts/ecosystem-drift.py`](./scripts/ecosystem-drift.py)
+reads the manifest and reports which repos have drifted behind their live upstream. The
+[`ecosystem-drift`](./.github/workflows/ecosystem-drift.yml) workflow runs it weekly and
+on manifest changes, writing the report to the run summary.
+
+**This is a report-only safe slice.** The checker has read-only permissions, opens no
+PRs, and mutates nothing — it always exits 0 (drift is advisory). Acting on drift means
+re-verifying upstream and bumping `pinned_version` in `ecosystem.json` via a reviewed PR.
+
+`claude-code-plugins` is deliberately listed under `excluded`, not automated: it has
+bespoke in-flight CI/CD, so any future sync automation must be coordinated with that
+pipeline first and sequenced last. Turning on auto-PR (and folding in the excluded repo)
+is a separate, explicitly-reviewed change — not a config flip.
+
+```bash
+python3 scripts/ecosystem-drift.py   # prints the drift table; opens nothing
+```
+
+---
+
 <sub>Intent Solutions · [intentsolutions.io](https://intentsolutions.io) · Apache-2.0</sub>

ecosystem.json

@@ -0,0 +1,72 @@
+{
+  "manifest_version": "0.1.0",
+  "description": "Intent Eval Platform ecosystem manifest. Single source of truth for the report-only drift orchestrator (scripts/ecosystem-drift.py): which repos compose the platform, each repo's kind, and the pinned version the orchestrator compares against live upstream. SAFE SLICE — report-only: the orchestrator NEVER opens PRs in this version. Live auto-PR and inclusion of claude-code-plugins are deferred pending coordination (see the 'excluded' block and README).",
+  "generated": "2026-06-06",
+  "automation": {
+    "mode": "report-only",
+    "auto_pr": false,
+    "note": "Auto-PR is intentionally disabled. Turning it on is a separate, explicitly-reviewed change — not a config flip in this PR."
+  },
+  "repos": [
+    {
+      "name": "intent-eval-core",
+      "gh": "jeremylongshore/intent-eval-core",
+      "kind": "node-package",
+      "version_source": "npm",
+      "package": "@intentsolutions/core",
+      "pinned_version": "0.2.0",
+      "automation": "report-only"
+    },
+    {
+      "name": "intent-eval-lab",
+      "gh": "jeremylongshore/intent-eval-lab",
+      "kind": "docs-methodology",
+      "version_source": "git-tag",
+      "pinned_version": "v0.2.0",
+      "automation": "report-only"
+    },
+    {
+      "name": "intent-audit-harness",
+      "gh": "jeremylongshore/intent-audit-harness",
+      "kind": "polyglot-cli",
+      "version_source": "npm",
+      "package": "@intentsolutions/audit-harness",
+      "pinned_version": "1.1.5",
+      "automation": "report-only"
+    },
+    {
+      "name": "j-rig-skill-binary-eval",
+      "gh": "jeremylongshore/j-rig-skill-binary-eval",
+      "kind": "node-monorepo",
+      "version_source": "git-tag",
+      "pinned_version": "v1.1.0",
+      "automation": "report-only"
+    },
+    {
+      "name": "intent-rollout-gate",
+      "gh": "jeremylongshore/intent-rollout-gate",
+      "kind": "github-action",
+      "version_source": "git-tag",
+      "pinned_version": "v0.0.1",
+      "automation": "report-only"
+    },
+    {
+      "name": "intent-eval-dashboard",
+      "gh": "jeremylongshore/intent-eval-dashboard",
+      "kind": "web-dashboard",
+      "version_source": "git-tag",
+      "pinned_version": null,
+      "automation": "report-only",
+      "note": "No release tag yet; orchestrator reports 'untagged' rather than drift."
+    }
+  ],
+  "excluded": [
+    {
+      "name": "claude-code-plugins",
+      "gh": "jeremylongshore/claude-code-plugins",
+      "kind": "marketplace",
+      "automation": "EXCLUDED",
+      "reason": "Has bespoke in-flight CI/CD that tests plugins. Any sync automation must be studied and coordinated with that pipeline FIRST — never bolt generic automation on top of it. When ecosystem-sync gains write authority, claude-code-plugins is sequenced LAST and only after explicit coordination. The orchestrator must skip this entry entirely."
+    }
+  ]
+}

scripts/ecosystem-drift.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+"""
+ecosystem-drift — REPORT-ONLY drift checker for the Intent Eval Platform.
+
+Reads ecosystem.json and, for each repo whose automation is "report-only",
+resolves the live upstream version (npm latest, or newest git tag) and compares
+it to the manifest's pinned_version. Prints a markdown drift report.
+
+SAFE-SLICE GUARANTEES (do not weaken without an explicit, reviewed change):
+  * NEVER opens a PR, pushes a commit, or mutates any repo. Read-only.
+  * NEVER touches repos in the manifest's "excluded" block (claude-code-plugins) —
+    they are listed for visibility and skipped by design.
+  * ALWAYS exits 0. Drift is advisory; this script has no exit authority.
+
+Stdlib only. Network: registry.npmjs.org (no auth) + api.github.com (optional
+GITHUB_TOKEN from env for higher rate limits). Soft-fails per repo.
+"""
+import json
+import os
+import sys
+import urllib.request
+import urllib.error
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+MANIFEST = os.path.join(HERE, "..", "ecosystem.json")
+
+
+# Some registries/APIs (notably api.github.com) reject the default Python
+# urllib User-Agent. Send a descriptive UA on every request, centrally.
+_UA = "ecosystem-drift (+https://github.com/intent-solutions-io/intent-eval-platform)"
+
+
+def _get_json(url, headers=None, timeout=15):
+    hdrs = {"User-Agent": _UA}
+    if headers:
+        hdrs.update(headers)
+    req = urllib.request.Request(url, headers=hdrs)
+    with urllib.request.urlopen(req, timeout=timeout) as r:
+        return json.load(r)
+
+
+def npm_latest(pkg):
+    if not pkg:
+        return None
+    try:
+        return _get_json(f"https://registry.npmjs.org/{pkg}/latest").get("version")
+    except (urllib.error.URLError, ValueError, TimeoutError):
+        return None
+
+
+def newest_tag(gh):
+    if not gh:
+        return None
+    headers = {"Accept": "application/vnd.github+json"}  # UA centralized in _get_json
+    token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    try:
+        tags = _get_json(f"https://api.github.com/repos/{gh}/tags", headers=headers)
+        return tags[0]["name"] if tags else None
+    except (urllib.error.URLError, ValueError, TimeoutError, KeyError, IndexError):
+        return None
+
+
+def _norm(v):
+    return v.lstrip("v") if isinstance(v, str) else v
+
+
+def resolve(repo):
+    src = repo.get("version_source")
+    if src == "npm":
+        return npm_latest(repo.get("package"))
+    if src == "git-tag":
+        return newest_tag(repo.get("gh"))
+    return None
+
+
+def status_for(pinned, latest):
+    if pinned is None and latest is None:
+        return "untagged (no pin / no release)"
+    if latest is None:
+        return "unknown (lookup failed)"
+    if pinned is None:
+        return "untagged (no pin)"
+    if _norm(pinned) == _norm(latest):
+        return "current"
+    return "BEHIND"
+
+
+def main():
+    with open(MANIFEST, encoding="utf-8") as f:
+        doc = json.load(f)
+
+    rows, behind = [], 0
+    for repo in doc.get("repos", []):
+        if repo.get("automation") != "report-only":
+            continue
+        latest = resolve(repo)
+        st = status_for(repo.get("pinned_version"), latest)
+        if st == "BEHIND":
+            behind += 1
+        rows.append((repo.get("name", "unknown"), repo.get("version_source", "—"),
+                     str(repo.get("pinned_version")), str(latest), st))
+
+    lines = []
+    lines.append(f"# Ecosystem drift report (report-only) — manifest v{doc.get('manifest_version')}")
+    lines.append("")
+    lines.append(f"Mode: **{doc.get('automation', {}).get('mode')}** · auto-PR: "
+                 f"**{doc.get('automation', {}).get('auto_pr')}** · repos behind: **{behind}**")
+    lines.append("")
+    lines.append("| Repo | Source | Pinned | Latest upstream | Status |")
+    lines.append("|------|--------|--------|-----------------|--------|")
+    for name, src, pinned, latest, st in rows:
+        lines.append(f"| {name} | {src} | {pinned} | {latest} | {st} |")
+    excluded = doc.get("excluded", [])
+    if excluded:
+        lines.append("")
+        lines.append("## Excluded from automation (skipped by design)")
+        for ex in excluded:
+            lines.append(f"- **{ex.get('name', 'unknown')}** — {ex.get('reason', 'excluded')}")
+    lines.append("")
+    lines.append("_Advisory only. This report opens no PRs and mutates nothing. "
+                 "To act on drift, re-verify upstream and bump `pinned_version` in "
+                 "`ecosystem.json` via a reviewed PR._")
+    report = "\n".join(lines)
+
+    print(report)
+    summary = os.environ.get("GITHUB_STEP_SUMMARY")
+    if summary:
+        try:
+            with open(summary, "a", encoding="utf-8") as f:
+                f.write(report + "\n")
+        except OSError:
+            pass
+
+    # Advisory: never any exit-code authority.
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()