@compr/opscontext-mcp 2.4.1 → 2.4.2

package/CHANGELOG.md

@@ -4,6 +4,53 @@ All notable changes to OpsContext for AI Agents (previously ContextEngine — MC
 
 > Entries for 2.2.0 through 2.4.0 were not backfilled here; see `docs/sessions/SESSION_19` through `SESSION_21` for those releases.
 
+## [2.4.2] — 2026-08-16 — Close the three holes 2.4.1 left in "a directory is not a project"
+
+2.4.1 made `score`'s scope explicit but enforced it on only one of three entry points. An
+adversarial review (30 agents, sandboxed) raised 26 findings, refuted 18, and confirmed 8 —
+clustering into the fixes below. Every repro was reproduced against the shipped build before
+being fixed, and re-run after.
+
+### Fixed
+
+- **`score .` re-created the exact incident 2.4.1's LOCK forbids.** `cd ~/Projects && score .`
+  wrote `~/Projects/SCORE.md` — *"Projects: 27/100 (F), Not a git repo"* — into the container of
+  37 repositories. The identical command *without* the `.` was correctly refused: the guard
+  existed, and the explicit-path entry point walked straight past it. Same for `score ~/Projects`,
+  `score ..` and `score /`. A path must now carry a build/VCS marker
+  (`.git`, `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Makefile`, …) to be
+  scoreable. Locked as `[RESOLVE-PATH-MUST-BE-A-PROJECT]`.
+- **A mistyped project name silently scored a subdirectory.** `score src`, `score dist`,
+  `score docs` no longer errored with the available-projects list — the bare token fell through
+  to path resolution against the cwd, scored the subdirectory, and wrote a `SCORE.md` into it.
+  In this repo `score dist` wrote `dist/SCORE.md`, which then ships inside the npm tarball. A
+  bare name now resolves against the fleet index **only**; the error names the directory it
+  found and offers `score ./src` as the explicit escape hatch.
+- **`score` in a subpackage reported "Not a git repo" from inside a git repo.** `cd server &&
+  score` stopped at the nearest `package.json` and reported *"server — 32% (F), Not a git repo,
+  No CI pipeline, README.md Missing"* — every claim false about the project the user was standing
+  in. `.git` is now the project boundary and wins over any nearer build file; a genuinely
+  standalone package still resolves to itself. Locked as `[GIT-ROOT-IS-THE-PROJECT-BOUNDARY]`.
+- **`CONTEXTENGINE_WORKSPACES` was read and ignored.** It was a fallback that applied only when
+  the config file defined no `workspaces` — so on the documented setup it did nothing, including
+  in every MCP config block this project ships. Precedence is now env var > config file >
+  auto-discovery. Locked as `[ENV-WORKSPACES-WINS]`.
+- Error messages no longer say "not an existing directory" about a directory that exists. Each
+  of the four failure modes (unknown name / no such path / not a directory / not a project) now
+  names the actual reason.
+
+### Documentation
+
+- README's "Config resolution order" table documented the pre-fix precedence and could not
+  describe both surfaces at once. Now split: config-file lookup, project-fleet lookup (env wins),
+  and an explicit note that the *search corpus* still prefers the config file.
+- `CLAUDE.md` still told every agent in this repo that `npx . score` scores all projects.
+
+### Tests
+
+373 pass (8 new). One pre-existing test asserted the old behaviour — a marker-less directory
+resolving as a project — and was corrected rather than deleted.
+
 ## [2.4.1] — 2026-08-16 — `score` scope is now explicit: current project by default, `--all` to opt into the fleet
 
 ### Changed (behaviour — read this before upgrading)

package/README.md

@@ -348,13 +348,33 @@ For full control, create a `contextengine.json`:
 
 ### Config resolution order
 
+Which **config file** is read (both the search corpus and the project fleet):
+
 | Priority | Source |
 |----------|--------|
 | 1 | `CONTEXTENGINE_CONFIG` env var |
 | 2 | `./contextengine.json` |
 | 3 | `~/.contextengine.json` |
-| 4 | `CONTEXTENGINE_WORKSPACES` env var |
-| 5 | `~/Projects` auto-discover |
+
+Which **project fleet** is scanned — this is what `score --all`, `audit`, `list_projects`
+and `check_ports` operate on:
+
+| Priority | Source |
+|----------|--------|
+| 1 | `CONTEXTENGINE_WORKSPACES` env var (colon-separated) |
+| 2 | `workspaces` in the config file |
+| 3 | `~/Projects` auto-discover |
+
+**The env var wins.** It is set per-invocation, so it is the most specific statement of
+intent — and it is what the MCP config blocks in this README set. Use it to scope a run:
+
+```bash
+CONTEXTENGINE_WORKSPACES=/tmp/sandbox npx @compr/opscontext-mcp score --all
+```
+
+> Note: the **search corpus** (`search`, `reindex`, `list-sources`) still prefers the config
+> file's `workspaces` over the env var. If you rely on the env var to scope indexing, set
+> `CONTEXTENGINE_CONFIG` to a config without `workspaces`, or unset `workspaces` there.
 
 ## Plugin Adapters
 

package/dist/cli.js

@@ -517,7 +517,7 @@ async function runInit() {
 // ---------------------------------------------------------------------------
 // CLI Engine — shared initialization for all CLI subcommands
 // ---------------------------------------------------------------------------
-import { loadSources, loadProjectDirs, loadConfig, resolveProjectDir, findProjectRoot } from "./config.js";
+import { loadSources, loadProjectDirs, loadConfig, resolveProjectDir, findProjectRoot, looksLikePath } from "./config.js";
 import { ingestSources } from "./ingest.js";
 import { searchChunks } from "./search.js";
 import { collectProjectOps, collectSystemOps } from "./collectors.js";
@@ -751,9 +751,34 @@ async function cliScore(project, html = false, save = true, all = false) {
         // [SCORE-ACCEPTS-PATH] — a path is as valid an identifier as a name.
         const dir = resolveProjectDir(project, projectDirs);
         if (!dir) {
-            console.error(`❌ Project not found: "${project}"`);
-            console.error(`   Not a known project name, and not an existing directory.`);
-            console.error(`Available: ${projectDirs.map((d) => d.name).join(", ")}`);
+            // Say which of the three failures actually happened. "Not found" for a
+            // directory that plainly exists is the same absence-as-verdict mistake
+            // [SCORE-ACCEPTS-PATH] was written to fix — do not reintroduce it here.
+            const abs = resolve(project.replace(/^~/, homedir()));
+            const exists = existsSync(abs);
+            const isDir = exists && statSync(abs).isDirectory();
+            if (!looksLikePath(project)) {
+                // A bare name that missed the fleet index. Deliberately NOT resolved as a
+                // relative directory — that is what silently scored ./src and ./dist.
+                console.error(`❌ Project not found: "${project}"`);
+                if (isDir) {
+                    console.error(`   A directory named "${project}" exists here, but it is not a`);
+                    console.error(`   project in your fleet. To score it anyway: contextengine score ./${project}`);
+                }
+                console.error(`Available: ${projectDirs.map((d) => d.name).join(", ")}`);
+            }
+            else if (!exists) {
+                console.error(`❌ No such directory: ${abs}`);
+            }
+            else if (!isDir) {
+                console.error(`❌ Not a directory: ${abs}`);
+            }
+            else {
+                console.error(`❌ Not a project: ${abs}`);
+                console.error(`   The directory exists, but has no .git, package.json, pyproject.toml`);
+                console.error(`   or other build file — so it looks like a container, not a project.`);
+                console.error(`   If you meant the projects INSIDE it, use: contextengine score --all`);
+            }
             process.exit(1);
         }
         scores = [scoreProject(dir)];

package/dist/config.d.ts

@@ -67,41 +67,17 @@ export declare function loadSources(): KnowledgeSource[];
  */
 export declare function loadProjectDirs(): ProjectDirectory[];
 /**
- * 🔒 LOCKED [SCORE-ACCEPTS-PATH] — 2026-08-16
- * ⛔ NEVER narrow this back to `dirs.find(d => d.name === token)` alone.
- * WHY: `contextengine score /Users/yan/Projects/PLANK.io` failed with
- *      "Project not found: /Users/yan/Projects/PLANK.io" while listing PLANK.io
- *      among the available projects. A path is the natural first guess for a
- *      tool that prints absolute paths in its own output, and the error named
- *      the one thing the user had clearly just given it. The directory was
- *      never inspected — the lookup only ever compared basenames, so this was
- *      [ABSENCE-IS-NOT-A-VERDICT] at the argument-parsing layer: "not in my
- *      name index" was reported as "does not exist".
- * FIX: resolve names AND paths. A path that exists is a project, whether or not
- *      it sits under a configured workspace — that is what makes the tool usable
- *      outside `~/Projects`.
- */
-export declare function resolveProjectDir(token: string, dirs: ProjectDirectory[]): ProjectDirectory | null;
-/**
- * 🔒 LOCKED [SCORE-CWD-MUST-BE-A-PROJECT] — 2026-08-16
- * ⛔ NEVER fall back to returning `start` when no project marker is found. A directory
- *    that is not a project must produce null, and the caller must refuse to score it.
- * WHY: the first cut of this returned `start` on failure, reasoning that "an un-versioned
- *      directory is still scoreable — it just scores badly." That is exactly the
- *      absence-as-verdict mistake this codebase keeps relearning. Running `score` from
- *      `~/Projects` — a CONTAINER of 37 projects, not a project — walked to the filesystem
- *      root, found nothing, fell back, scored the container as though it were a project,
- *      and wrote `~/Projects/SCORE.md` claiming "Projects: 27/100 (F)". Run from `/` it
- *      would do the same to the filesystem root. "I cannot tell which project you mean" is
- *      an unknown, and the safe response to an unknown scope is to ask, never to write.
- * FIX: return null and let the caller error out with the three things the user can do
- *      instead (cd into a project, name one, or --all). Found by an adversarial review
- *      agent that ran the real CLI from `/` and `~/Projects`.
+ * Does this token look like a filesystem path rather than a bare project name?
  *
- * Walk up from `start` to the enclosing project root. Stops at the first directory
- * holding a `.git` or a `package.json`. Returns null when neither is found anywhere
- * above `start`.
+ * Deliberately conservative: only strings that CANNOT be a directory basename
+ * (they contain a separator, or start with `~`/`.`) are treated as
+ * path-only. Everything else stays eligible for name lookup first, so
+ * `score KONIVE.com` keeps resolving exactly as it did before this existed.
  */
+export declare function looksLikePath(token: string): boolean;
+/** Does this directory carry any build/VCS marker that makes it a project? */
+export declare function hasProjectMarker(dir: string): boolean;
+export declare function resolveProjectDir(token: string, dirs: ProjectDirectory[]): ProjectDirectory | null;
 export declare function findProjectRoot(start: string): string | null;
 /**
  * Load the raw config (for checking flags like collectSystemOps).

package/dist/config.js

@@ -188,12 +188,27 @@ export function loadProjectDirs() {
             workspaceDirs = config.workspaces.map((w) => resolve(configPath, "..", w.replace(/^~/, homedir())));
         }
     }
-    // Env var fallback
-    if (workspaceDirs.length === 0) {
-        const envWorkspaces = process.env.CONTEXTENGINE_WORKSPACES;
-        if (envWorkspaces) {
-            workspaceDirs = envWorkspaces.split(":").filter(Boolean);
-        }
+    /**
+     * 🔒 LOCKED [ENV-WORKSPACES-WINS] — 2026-08-16
+     * ⛔ NEVER demote CONTEXTENGINE_WORKSPACES back to a fallback that only applies when the
+     *    config file happens not to define `workspaces`.
+     * WHY: it WAS such a fallback (`if (workspaceDirs.length === 0)`), so on any machine with a
+     *      contextengine.json defining workspaces — which is the documented setup — the env var
+     *      was read, ignored, and never reported. Every MCP config block we ship in
+     *      skills/opscontext/SKILL.md sets `env: { CONTEXTENGINE_WORKSPACES: ... }`, so our own
+     *      documented integration silently did nothing.
+     *      Caught the hard way: an attempt to sandbox a review agent by pointing this variable at
+     *      a scratch directory was ignored, and `score --all` wrote SCORE.md into 28 real
+     *      repositories instead. The sandbox reported success because the variable was accepted
+     *      without complaint — absence of an error read as confirmation.
+     * FIX: standard precedence — an explicit env var beats a config file beats auto-discovery.
+     *      It is set per-invocation and is therefore the most specific statement of intent.
+     */
+    const envWorkspaces = process.env.CONTEXTENGINE_WORKSPACES;
+    if (envWorkspaces) {
+        const fromEnv = envWorkspaces.split(":").filter(Boolean);
+        if (fromEnv.length > 0)
+            workspaceDirs = fromEnv;
     }
     // Auto-discover fallback
     if (workspaceDirs.length === 0) {
@@ -235,7 +250,7 @@ export function loadProjectDirs() {
  * path-only. Everything else stays eligible for name lookup first, so
  * `score KONIVE.com` keeps resolving exactly as it did before this existed.
  */
-function looksLikePath(token) {
+export function looksLikePath(token) {
     return (token.includes("/") ||
         token.includes(sep) ||
         token.startsWith("~") ||
@@ -253,31 +268,60 @@ function looksLikePath(token) {
  *      never inspected — the lookup only ever compared basenames, so this was
  *      [ABSENCE-IS-NOT-A-VERDICT] at the argument-parsing layer: "not in my
  *      name index" was reported as "does not exist".
- * FIX: resolve names AND paths. A path that exists is a project, whether or not
- *      it sits under a configured workspace — that is what makes the tool usable
- *      outside `~/Projects`.
+ * FIX: resolve names AND paths. A path that exists AND carries a project marker is a
+ *      project, whether or not it sits under a configured workspace — that is what makes
+ *      the tool usable outside `~/Projects`.
+ *
+ * 🔒 LOCKED [RESOLVE-PATH-MUST-BE-A-PROJECT] — 2026-08-16
+ * ⛔ NEVER accept "it is a directory that exists" as proof that a path is a project, and
+ *    NEVER let a bare name that missed the index fall through to path resolution.
+ * WHY: the first cut did both, and an adversarial review reproduced three consequences.
+ *      1. `cd ~/Projects && score .` wrote `~/Projects/SCORE.md` — "Projects: 27/100 (F),
+ *         Not a git repo" — into the CONTAINER of 37 repositories. The identical command
+ *         WITHOUT the `.` was correctly refused, so the guard existed and one entry point
+ *         walked straight past it. Same for `score ~/Projects`, `score ..`, and `score /`.
+ *      2. `score src`, `score dist`, `score docs` — a typo or a half-remembered name — no
+ *         longer errored with "Available: …". The bare token fell through to
+ *         `resolve(token)` against the cwd, so it silently scored a SUBDIRECTORY and wrote
+ *         a SCORE.md into it. In this repo `score dist` writes `dist/SCORE.md`, which then
+ *         ships inside the npm tarball.
+ *      3. It made the sibling LOCK a half-truth: [SCORE-CWD-MUST-BE-A-PROJECT] promises a
+ *         non-project is never scored, but enforced it on the no-argument path only.
+ * FIX: a directory must carry a build/VCS marker to be scoreable, and a bare name resolves
+ *      against the fleet index ONLY. Configured projects always pass — they are the fleet
+ *      by definition. Absence of a marker is a measurement, not permission to write.
  */
+const PROJECT_MARKERS = [
+    ".git", "package.json", "pyproject.toml", "requirements.txt", "setup.py",
+    "composer.json", "pubspec.yaml", "go.mod", "Cargo.toml", "Gemfile",
+    "pom.xml", "build.gradle", "Makefile", "CMakeLists.txt",
+];
+/** Does this directory carry any build/VCS marker that makes it a project? */
+export function hasProjectMarker(dir) {
+    return PROJECT_MARKERS.some((m) => existsSync(join(dir, m)));
+}
 export function resolveProjectDir(token, dirs) {
-    // Name lookup first — preserves pre-existing behaviour exactly.
+    // A bare name resolves against the fleet index ONLY. It must never silently
+    // become a cwd-relative directory — that is how `score src` wrote src/SCORE.md
+    // instead of printing "Project not found. Available: …". Use `./src` to mean a path.
     if (!looksLikePath(token)) {
-        const byName = dirs.find((d) => d.name.toLowerCase() === token.toLowerCase());
-        if (byName)
-            return byName;
+        return (dirs.find((d) => d.name.toLowerCase() === token.toLowerCase()) ?? null);
     }
     // Path resolution — absolute, relative, or `~`-prefixed.
     const abs = resolve(token.replace(/^~/, homedir()));
     try {
-        if (statSync(abs).isDirectory()) {
-            // Prefer the configured entry when the path points at a known project,
-            // so the reported name matches the rest of the fleet output.
-            const known = dirs.find((d) => resolve(d.path) === abs);
-            return known ?? { name: basename(abs), path: abs };
-        }
+        if (!statSync(abs).isDirectory())
+            return null;
     }
     catch {
-        // ENOENT / EACCES — not a usable directory. Fall through to null.
+        return null; // ENOENT / EACCES — not a usable directory.
     }
-    return null;
+    // A configured project is a project by definition, marker or not.
+    const known = dirs.find((d) => resolve(d.path) === abs);
+    if (known)
+        return known;
+    // Otherwise it must look like a project. `~/Projects` and `/` do not.
+    return hasProjectMarker(abs) ? { name: basename(abs), path: abs } : null;
 }
 /**
  * 🔒 LOCKED [SCORE-CWD-MUST-BE-A-PROJECT] — 2026-08-16
@@ -295,21 +339,47 @@ export function resolveProjectDir(token, dirs) {
  *      instead (cd into a project, name one, or --all). Found by an adversarial review
  *      agent that ran the real CLI from `/` and `~/Projects`.
  *
- * Walk up from `start` to the enclosing project root. Stops at the first directory
- * holding a `.git` or a `package.json`. Returns null when neither is found anywhere
- * above `start`.
+ * 🔒 LOCKED [GIT-ROOT-IS-THE-PROJECT-BOUNDARY] — 2026-08-16
+ * ⛔ NEVER return the nearest `package.json` directory without first checking whether a
+ *    `.git` sits above it.
+ * WHY: stopping at the nearest marker meant `cd ContextEngine/server && score` reported
+ *      **"Scoring current project: server ... 32% (F) — Not a git repo, No CI pipeline,
+ *      README.md Missing"** and wrote `server/SCORE.md`. Every one of those statements is
+ *      false about the project the user is standing in: the repo root has `.git`, CI, and
+ *      a README. A build file marks a *package*; `.git` marks the *project*. Reporting
+ *      "Not a git repo" from inside a git repo is the scorer describing a boundary it
+ *      invented — absence-as-verdict again, this time about where the project ends.
+ * FIX: `.git` wins. Walk up looking for it, remembering the nearest build file on the way,
+ *      and fall back to that remembered directory only if no `.git` exists anywhere above.
+ *      A genuinely standalone package (no git anywhere) still resolves to itself.
+ *
+ * Walk up from `start` to the enclosing project root. Returns null when nothing is
+ * found anywhere above `start`.
  */
+const BUILD_FILE_MARKERS = [
+    "package.json", "pyproject.toml", "requirements.txt", "setup.py",
+    "composer.json", "pubspec.yaml", "go.mod", "Cargo.toml", "Gemfile",
+    "pom.xml", "build.gradle", "Makefile", "CMakeLists.txt",
+];
 export function findProjectRoot(start) {
     let dir = resolve(start);
+    let nearestBuildFile = null;
     for (;;) {
-        if (existsSync(join(dir, ".git")) || existsSync(join(dir, "package.json"))) {
+        // .git is the project boundary and always wins, however far up it sits.
+        if (existsSync(join(dir, ".git")))
             return dir;
+        if (nearestBuildFile === null &&
+            BUILD_FILE_MARKERS.some((m) => existsSync(join(dir, m)))) {
+            nearestBuildFile = dir;
         }
         const parent = dirname(dir);
         if (parent === dir)
-            return null; // reached filesystem root, no marker seen
+            break; // reached filesystem root
         dir = parent;
     }
+    // No .git anywhere above — a standalone package resolves to itself; a plain
+    // directory (a container, or /) resolves to nothing at all.
+    return nearestBuildFile;
 }
 /**
  * Load the raw config (for checking flags like collectSystemOps).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compr/opscontext-mcp",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "description": "OpsContext for AI Agents — read-only fleet visibility (PM2/nginx/Docker/git/cron) + tamper-evident audit log + policy-as-code hooks. The ops + compliance layer Claude Code can't grow natively.",
   "type": "module",
   "main": "dist/index.js",