@compr/opscontext-mcp 2.4.0 → 2.4.1

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 All notable changes to OpsContext for AI Agents (previously ContextEngine — MCP server + CLI) are documented here.
 
+> 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.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)
+
+- **`score` with no argument now scores only the current project**, walking up from the working
+  directory to the enclosing repo root. It previously scored all discovered projects **and wrote
+  a `SCORE.md` into every one of them** — which dirtied 26 repositories on the author's machine,
+  several of them auto-pushing on commit. Fleet-wide scoring now requires `--all`.
+  Locked as `[SCORE-FLEET-IS-OPT-IN]`.
+- `score --all` prints how many projects it is about to write into before doing it, and
+  `--all` combined with a project argument is now a hard error rather than a silently ignored flag.
+- The MCP `score_project` tool keeps its fleet-wide default — it never writes `SCORE.md`, so it
+  does not carry the hazard. The write is what must be asked for, not the scan.
+
+- **`score` with no argument now refuses to run outside a project** instead of scoring whatever
+  directory it is in. Run from `~/Projects` — a *container* of projects — it previously scored
+  the container and wrote a `SCORE.md` claiming `Projects: 27/100 (F)`; from `/` it would do the
+  same to the filesystem root. It now exits 1 and names the three ways to proceed.
+  Locked as `[SCORE-CWD-MUST-BE-A-PROJECT]`.
+
+### Fixed (documentation that shipped a working footgun)
+
+- **`skills/opscontext/SKILL.md` told agents to run `npx @compr/contextengine-mcp`** — a package
+  name npm freezes at **1.23.1**. Following the shipped skill downloaded a June scorer and ran a
+  fleet-wide write with a 94-point rubric that reports root-level `copilot-instructions.md` as
+  `Missing`. Ten call sites corrected, including three MCP-config blocks that would have
+  installed the frozen version as a long-running server. `skills/` now has zero references to it.
+- Same correction to the `.claude/settings.json` post-push reminder.
+
+### Added
+
+- **`score` accepts a path as well as a project name** — `score ~/Projects/PLANK.io`,
+  `score ../PLANK.io`, or an absolute path. Paths outside configured workspaces work too.
+  Previously `score /Users/yan/Projects/PLANK.io` failed with "Project not found" while listing
+  `PLANK.io` among the available projects — the lookup only ever compared basenames, so the
+  directory was never inspected. Locked as `[SCORE-ACCEPTS-PATH]`.
+- Same path support in the MCP `score_project` tool (strictly more accepting; no default changed).
+- `tests/project-resolution.test.ts` — 11 regression tests covering name/path/symlink/
+  file-not-a-directory/case-insensitivity/dotted names, and `findProjectRoot` termination.
+
+### Fixed
+
+- Polyglot repositories are scored against the languages they actually use (released here; committed
+  in 2.4.0's wake): test directories are aggregated across ecosystems rather than the first match
+  winning, `.dart` tests are counted, and Dart tooling (`analysis_options.yaml`) satisfies the
+  type-checking check instead of the project being marked down for a missing `tsconfig.json`.
+  PLANK.io 98%; KONIVE.com correctly reports 102 test files across two directories.
+
+### Investigated — no change
+
+- A report that the generated pre-commit hook regenerates and re-stages `SCORE.md` mid-commit
+  **does not reproduce**. `generatePreCommitHook()` only stats mtimes and greps staged files for
+  secrets; there is no score invocation and no `git add` in it, nor in the older custom hook the
+  reporting repo actually has installed. The observed empty commit is consistent with the
+  fleet-wide-write default above, which this release removes.
+
 ## [2.1.3] — 2026-06-26 — Tool manifest as single source of truth + server-meta.json for VS Code extension
 
 Tactical fix for a class of silent display drift: the VS Code info panel hardcoded "Active on all 17 MCP tools" while the npm package was at 21 tools. The README was at 20. None of these were tied to the actual `server.tool(...)` registrations, so adding a tool (e.g. `drift_status` in 2.1.0) left all displays stale.

package/README.md

@@ -248,9 +248,14 @@ npx @compr/opscontext-mcp list-sources
 # Discover and analyze all projects
 npx @compr/opscontext-mcp list-projects
 
-# AI-readiness score (one or all projects)
+# AI-readiness score — no argument scores the CURRENT project only
 npx @compr/opscontext-mcp score
-npx @compr/opscontext-mcp score ContextEngine
+npx @compr/opscontext-mcp score ContextEngine          # by project name
+npx @compr/opscontext-mcp score ~/Projects/PLANK.io    # or by path
+
+# Score every discovered project (writes a SCORE.md into each — opt in explicitly)
+npx @compr/opscontext-mcp score --all
+npx @compr/opscontext-mcp score --all --no-save        # scan without writing
 
 # Visual HTML report (opens in browser)
 npx @compr/opscontext-mcp score --html
@@ -436,6 +441,22 @@ The `score` command evaluates project AI-readiness across **documentation, infra
 
 **Grade scale:** A+ (90%+) · A (80%+) · B (70%+) · C (60%+) · D (50%+) · F (<50%)
 
+### What gets scored, and what gets written
+
+`score` writes a `SCORE.md` into each project it scores. Because that is a write into your
+repositories, the scope is never inferred:
+
+| Command | Scores | Writes `SCORE.md` to |
+|---|---|---|
+| `score` | the project you are standing in (walks up to the repo root) | that one project |
+| `score <name>` / `score <path>` | that one project | that one project |
+| `score --all` | every discovered project | **every** discovered project |
+| any of the above `--no-save` | as above | nothing |
+
+A project argument may be a **name** (`PLANK.io`) or a **path** (`~/Projects/PLANK.io`,
+`../PLANK.io`, or an absolute path). A path also works for projects outside your configured
+workspaces.
+
 ### Project Naming & Structure Tips
 
 The scorer discovers projects from your configured `workspaces` directories (default: `~/Projects`).

package/dist/agents.js

@@ -86,22 +86,48 @@ const AGENT_DOC_TOPICS = [
 function matchDocTopics(content, topics) {
     return topics.filter(t => t.patterns.test(content)).map(t => t.label);
 }
-function detectLanguage(p) {
-    if (existsSync(join(p, "package.json")))
-        return "js";
-    const pythonMarkers = ["pyproject.toml", "setup.py", "setup.cfg", "requirements.txt", "Pipfile", "__manifest__.py"];
-    if (pythonMarkers.some(m => existsSync(join(p, m))))
-        return "python";
-    if (existsSync(join(p, "composer.json")))
-        return "php";
-    // Odoo addons and src-layout packages keep their markers one level down.
+/**
+ * ALL languages present, root and one level down — not just a winner.
+ *
+ * A single "primary language" is the wrong model for this fleet. PLANK.io is a Flutter app with a
+ * Node backend: picking one meant scoring a Dart codebase against `tsconfig.json` and calling its
+ * analyzer config missing. Returning the set lets each tooling check pass on whichever ecosystem
+ * actually configures it. Part of [SCORE-LANGUAGE-AWARE].
+ */
+const LANGUAGE_MARKERS = [
+    { lang: "dart", files: ["pubspec.yaml"] },
+    { lang: "python", files: ["pyproject.toml", "setup.py", "setup.cfg", "requirements.txt", "Pipfile", "__manifest__.py"] },
+    { lang: "js", files: ["package.json"] },
+    { lang: "php", files: ["composer.json"] },
+];
+function detectLanguages(p) {
+    const found = new Set();
+    const scan = (base) => {
+        for (const { lang, files } of LANGUAGE_MARKERS) {
+            if (files.some(f => existsSync(join(base, f))))
+                found.add(lang);
+        }
+    };
+    scan(p);
+    for (const sub of safeSubdirs(p))
+        scan(join(p, sub));
+    if (found.size === 0)
+        found.add("other");
+    return found;
+}
+/** First existing path among `candidates`, searched at the root and one level down. */
+function findConfig(p, candidates) {
+    for (const c of candidates) {
+        if (existsSync(join(p, c)))
+            return c;
+    }
     for (const sub of safeSubdirs(p)) {
-        if (pythonMarkers.some(m => existsSync(join(p, sub, m))))
-            return "python";
-        if (existsSync(join(p, sub, "package.json")))
-            return "js";
+        for (const c of candidates) {
+            if (existsSync(join(p, sub, c)))
+                return `${sub}/${c}`;
+        }
     }
-    return "other";
+    return null;
 }
 /** Immediate subdirectories worth searching — skips vendored, hidden and build output. */
 function safeSubdirs(p) {
@@ -184,9 +210,15 @@ function countTestFiles(dirPath, depth = 0) {
                 count += countTestFiles(fullPath, depth + 1);
             }
             else if (entry.isFile()) {
-                if (/\.(test|spec|_test)\.(ts|tsx|js|jsx|py|php)$/.test(entry.name) ||
-                    entry.name.startsWith("test_") ||
-                    entry.name.endsWith("_test.py")) {
+                // 🔒 [SCORE-LANGUAGE-AWARE] — the extension list is part of the language assumption.
+                // `dart` was absent, so PLANK.io's 68 Flutter tests in plank_app/test/ counted as ZERO:
+                // the directory was found, every file was skipped, and the row credited the Node backend
+                // alone. A test counter that silently ignores a language reports "no tests" for a suite
+                // that runs on every build. Add the extension when adding a language, not after someone
+                // notices their tests are invisible.
+                if (/\.(test|spec)\.(ts|tsx|js|jsx|mjs|cjs|py|php|dart)$/.test(entry.name) ||
+                    /_(test|spec)\.(py|dart|go|rb)$/.test(entry.name) ||
+                    entry.name.startsWith("test_")) {
                     count++;
                 }
             }
@@ -1112,7 +1144,7 @@ export function scoreProject(dir) {
     const checks = [];
     const p = dir.path;
     // Language decides which tooling checks apply at all — see [SCORE-LANGUAGE-AWARE].
-    const lang = detectLanguage(p);
+    const langs = detectLanguages(p);
     // --- Documentation (30 points max) ---
     // copilot-instructions.md (6 pts) — scored on CONTENT, not length.
     // 🔒 LOCKED [SCORE-CONTENT-NOT-LENGTH] — 2026-08-14
@@ -1427,74 +1459,86 @@ export function scoreProject(dir) {
     ];
     const foundTests = testDirs.filter(td => existsSync(join(p, td)));
     if (foundTests.length > 0) {
-        const testDirPath = join(p, foundTests[0]);
-        const testIsSymlink = isSymlink(testDirPath);
-        const testFileCount = countTestFiles(testDirPath);
-        if (testIsSymlink) {
-            checks.push({ name: "Tests", category: "Code Quality", points: 3, maxPoints: 8, status: "partial", detail: `${foundTests[0]}/ is a symlink (${testFileCount} test files) — should be real test directory` });
+        // Count across EVERY test directory, not just the first match. PLANK.io has 68 Flutter tests
+        // in plank_app/test/ and 38 backend tests in backend/__tests__/; taking foundTests[0] credited
+        // the backend alone and rendered the larger codebase invisible. Any polyglot or multi-package
+        // repo hit this — the bug was the `[0]`, not the search.
+        const perDir = foundTests.map(td => ({ rel: td, count: countTestFiles(join(p, td)), symlink: isSymlink(join(p, td)) }));
+        const testFileCount = perDir.reduce((sum, d) => sum + d.count, 0);
+        const contributing = perDir.filter(d => d.count > 0);
+        const where = (contributing.length > 0 ? contributing : perDir)
+            .map(d => `${d.rel}/ (${d.count})`)
+            .slice(0, 3)
+            .join(", ") + (perDir.length > 3 ? `, +${perDir.length - 3} more` : "");
+        const allSymlinks = perDir.every(d => d.symlink);
+        if (allSymlinks) {
+            checks.push({ name: "Tests", category: "Code Quality", points: 3, maxPoints: 8, status: "partial", detail: `${where} — symlinked, should be real test directories` });
         }
         else if (testFileCount >= RUBRIC.testsFull) {
-            checks.push({ name: "Tests", category: "Code Quality", points: 8, maxPoints: 8, status: "pass", detail: `${foundTests[0]}/ — ${testFileCount} test files` });
+            checks.push({ name: "Tests", category: "Code Quality", points: 8, maxPoints: 8, status: "pass", detail: `${testFileCount} test files across ${contributing.length} dir(s): ${where}` });
         }
         else if (testFileCount > RUBRIC.testsPartial) {
-            checks.push({ name: "Tests", category: "Code Quality", points: 5, maxPoints: 8, status: "partial", detail: `${foundTests[0]}/ — only ${testFileCount} test files` });
+            checks.push({ name: "Tests", category: "Code Quality", points: 5, maxPoints: 8, status: "partial", detail: `only ${testFileCount} test files: ${where}` });
         }
         else {
-            try {
-                const hasAnyFiles = readdirSync(testDirPath).length > 0;
-                if (hasAnyFiles) {
-                    checks.push({ name: "Tests", category: "Code Quality", points: 4, maxPoints: 8, status: "partial", detail: `${foundTests[0]}/ has files but no standard test files detected` });
-                }
-                else {
-                    checks.push({ name: "Tests", category: "Code Quality", points: 1, maxPoints: 8, status: "partial", detail: `${foundTests[0]}/ exists but empty` });
+            let hasAnyFiles = false;
+            for (const d of perDir) {
+                try {
+                    if (readdirSync(join(p, d.rel)).length > 0) {
+                        hasAnyFiles = true;
+                        break;
+                    }
                 }
+                catch { /* unreadable dir counts as empty */ }
             }
-            catch {
-                checks.push({ name: "Tests", category: "Code Quality", points: 1, maxPoints: 8, status: "partial", detail: `${foundTests[0]}/ exists but unreadable` });
-            }
+            checks.push(hasAnyFiles
+                ? { name: "Tests", category: "Code Quality", points: 4, maxPoints: 8, status: "partial", detail: `${where} has files but no standard test files detected` }
+                : { name: "Tests", category: "Code Quality", points: 1, maxPoints: 8, status: "partial", detail: `${where} exists but empty` });
         }
     }
     else {
         checks.push({ name: "Tests", category: "Code Quality", points: 0, maxPoints: 8, status: "fail", detail: "No test directory" });
     }
-    // TypeScript / type checking (5 pts)
-    const tsconfigPath = join(p, "tsconfig.json");
-    if (existsSync(tsconfigPath)) {
-        const tsconfigContent = readFileSync(tsconfigPath, "utf-8").trim();
-        const tsconfigIsSymlink = isSymlink(tsconfigPath);
-        // Detect minimal/reference-only tsconfigs (just project references with no real config)
-        const isSubstantive = tsconfigContent.length > RUBRIC.tsconfigSubstantive && (tsconfigContent.includes('"compilerOptions"') || tsconfigContent.includes('"extends"'));
-        if (tsconfigIsSymlink) {
-            checks.push({ name: "TypeScript", category: "Code Quality", points: 2, maxPoints: 5, status: "partial", detail: "tsconfig.json is a symlink — create root config" });
+    // TypeScript / type checking (5 pts) — see [SCORE-LANGUAGE-AWARE].
+    // Checks every ecosystem the repo actually uses, so a Flutter app with a Node backend is not
+    // told its Dart analyzer config is a missing tsconfig.
+    {
+        const tsCfg = findConfig(p, ["tsconfig.json"]);
+        const dartCfg = langs.has("dart") ? findConfig(p, ["analysis_options.yaml"]) : null;
+        const pyCfg = langs.has("python") ? findConfig(p, ["mypy.ini", ".mypy.ini", "pyrightconfig.json"]) : null;
+        const pyprojectPath = findConfig(p, ["pyproject.toml"]);
+        const pyproject = pyprojectPath ? readFileSync(join(p, pyprojectPath), "utf-8") : "";
+        const pyInline = langs.has("python") && /\[tool\.(mypy|pyright)\]/.test(pyproject);
+        if (tsCfg) {
+            const content = readFileSync(join(p, tsCfg), "utf-8").trim();
+            const substantive = content.length > RUBRIC.tsconfigSubstantive && (content.includes('"compilerOptions"') || content.includes('"extends"'));
+            if (isSymlink(join(p, tsCfg))) {
+                checks.push({ name: "TypeScript", category: "Code Quality", points: 2, maxPoints: 5, status: "partial", detail: `${tsCfg} is a symlink — create a real config` });
+            }
+            else if (substantive) {
+                checks.push({ name: "TypeScript", category: "Code Quality", points: 5, maxPoints: 5, status: "pass", detail: `${tsCfg} present` });
+            }
+            else {
+                checks.push({ name: "TypeScript", category: "Code Quality", points: 3, maxPoints: 5, status: "partial", detail: `${tsCfg} is minimal — add compilerOptions for full type safety` });
+            }
         }
-        else if (isSubstantive) {
-            checks.push({ name: "TypeScript", category: "Code Quality", points: 5, maxPoints: 5, status: "pass", detail: "tsconfig.json present" });
+        else if (dartCfg) {
+            checks.push({ name: "Type checking", category: "Code Quality", points: 5, maxPoints: 5, status: "pass", detail: `${dartCfg} — Dart analyzer configured` });
         }
-        else {
-            checks.push({ name: "TypeScript", category: "Code Quality", points: 3, maxPoints: 5, status: "partial", detail: "tsconfig.json is minimal — add compilerOptions for full type safety" });
+        else if (pyCfg || pyInline) {
+            checks.push({ name: "Type checking", category: "Code Quality", points: 5, maxPoints: 5, status: "pass", detail: `${pyCfg ?? pyprojectPath} — static type checking configured` });
         }
-    }
-    else if (existsSync(join(p, "jsconfig.json"))) {
-        checks.push({ name: "Type checking", category: "Code Quality", points: 2, maxPoints: 5, status: "partial", detail: "jsconfig.json only" });
-    }
-    else if (lang === "python") {
-        // See [SCORE-LANGUAGE-AWARE]. Python type checking is mypy/pyright, not tsconfig.
-        const pyTypeMarkers = ["mypy.ini", ".mypy.ini", "pyrightconfig.json"];
-        const foundPyType = pyTypeMarkers.filter(m => existsSync(join(p, m)));
-        const pyproject = existsSync(join(p, "pyproject.toml")) ? readFileSync(join(p, "pyproject.toml"), "utf-8") : "";
-        if (foundPyType.length > 0 || /\[tool\.(mypy|pyright)\]/.test(pyproject)) {
-            checks.push({ name: "Type checking", category: "Code Quality", points: 5, maxPoints: 5, status: "pass", detail: `${foundPyType[0] ?? "pyproject.toml"} — static type checking configured` });
+        else if (existsSync(join(p, "jsconfig.json"))) {
+            checks.push({ name: "Type checking", category: "Code Quality", points: 2, maxPoints: 5, status: "partial", detail: "jsconfig.json only" });
+        }
+        else if (langs.has("js") || langs.has("dart") || langs.has("python")) {
+            const want = [langs.has("js") && "tsconfig.json", langs.has("dart") && "analysis_options.yaml", langs.has("python") && "mypy/pyright"].filter(Boolean).join(" or ");
+            checks.push({ name: "Type checking", category: "Code Quality", points: 0, maxPoints: 5, status: "fail", detail: `No ${want} found — add static type checking` });
         }
         else {
-            checks.push({ name: "Type checking", category: "Code Quality", points: 0, maxPoints: 5, status: "fail", detail: "Python project with no mypy/pyright config — add one for static type checking" });
+            checks.push({ name: "Type checking", category: "Code Quality", points: 0, maxPoints: 5, status: "unknown", detail: "❔ No type-checking convention known for this project type — not assessed" });
         }
     }
-    else if (lang === "php" || lang === "other") {
-        checks.push({ name: "Type checking", category: "Code Quality", points: 0, maxPoints: 5, status: "unknown", detail: `❔ No type-checking convention known for this project type (${lang}) — not assessed` });
-    }
-    else {
-        checks.push({ name: "Type checking", category: "Code Quality", points: 0, maxPoints: 5, status: "fail", detail: "No tsconfig/jsconfig" });
-    }
     // Linting config (4 pts) — verifies linting tools are installed, not just config
     const lintConfigs = [".eslintrc.js", ".eslintrc.json", ".eslintrc.yml", "eslint.config.js", "eslint.config.mjs", ".prettierrc", "phpcs.xml"];
     const foundLint = lintConfigs.filter(l => existsSync(join(p, l)));
@@ -1511,10 +1555,16 @@ export function scoreProject(dir) {
             checks.push({ name: "Linting", category: "Code Quality", points: 4, maxPoints: 4, status: "pass", detail: foundLint.join(", ") });
         }
     }
-    else if (lang === "python") {
+    else if (langs.has("dart") && findConfig(p, ["analysis_options.yaml"])) {
+        // Dart's analyzer IS the linter — analysis_options.yaml is enforced on every build.
+        checks.push({ name: "Linting", category: "Code Quality", points: 4, maxPoints: 4, status: "pass", detail: `${findConfig(p, ["analysis_options.yaml"])} — Dart analyzer lints` });
+    }
+    else if (langs.has("python")) {
         // See [SCORE-LANGUAGE-AWARE]. Python linting is ruff/flake8/pylint, not eslint.
-        const pyLint = ["ruff.toml", ".ruff.toml", ".flake8", ".pylintrc", "tox.ini", "setup.cfg"].filter(l => existsSync(join(p, l)));
-        const pyproject = existsSync(join(p, "pyproject.toml")) ? readFileSync(join(p, "pyproject.toml"), "utf-8") : "";
+        const pyLintCfg = findConfig(p, ["ruff.toml", ".ruff.toml", ".flake8", ".pylintrc", "tox.ini", "setup.cfg"]);
+        const pyLint = pyLintCfg ? [pyLintCfg] : [];
+        const pyprojectRel = findConfig(p, ["pyproject.toml"]);
+        const pyproject = pyprojectRel ? readFileSync(join(p, pyprojectRel), "utf-8") : "";
         if (pyLint.length > 0 || /\[tool\.(ruff|flake8|pylint|black)\]/.test(pyproject)) {
             checks.push({ name: "Linting", category: "Code Quality", points: 4, maxPoints: 4, status: "pass", detail: pyLint[0] ?? "pyproject.toml" });
         }
@@ -1522,7 +1572,7 @@ export function scoreProject(dir) {
             checks.push({ name: "Linting", category: "Code Quality", points: 0, maxPoints: 4, status: "fail", detail: "Python project with no ruff/flake8/pylint config — add one" });
         }
     }
-    else if (lang === "other") {
+    else if (langs.has("other") && langs.size === 1) {
         checks.push({ name: "Linting", category: "Code Quality", points: 0, maxPoints: 4, status: "unknown", detail: "❔ No linting convention known for this project type — not assessed" });
     }
     else {

package/dist/cli.d.ts

@@ -10,7 +10,7 @@
  *   contextengine list-projects       Discover and analyze all projects
  *   contextengine list-learnings      List all permanent learnings
  *   contextengine save-learning        Save a learning (terminal fallback for MCP)
- *   contextengine score [project]     AI-readiness score (writes SCORE.md to each project)
+ *   contextengine score [project|path] AI-readiness score for one project (default: cwd; --all for fleet)
  *   contextengine audit               Run compliance audit across all projects
  *   contextengine help                Show this message
  */

package/dist/cli.js

@@ -10,7 +10,7 @@
  *   contextengine list-projects       Discover and analyze all projects
  *   contextengine list-learnings      List all permanent learnings
  *   contextengine save-learning        Save a learning (terminal fallback for MCP)
- *   contextengine score [project]     AI-readiness score (writes SCORE.md to each project)
+ *   contextengine score [project|path] AI-readiness score for one project (default: cwd; --all for fleet)
  *   contextengine audit               Run compliance audit across all projects
  *   contextengine help                Show this message
  */
@@ -517,7 +517,7 @@ async function runInit() {
 // ---------------------------------------------------------------------------
 // CLI Engine — shared initialization for all CLI subcommands
 // ---------------------------------------------------------------------------
-import { loadSources, loadProjectDirs, loadConfig } from "./config.js";
+import { loadSources, loadProjectDirs, loadConfig, resolveProjectDir, findProjectRoot } from "./config.js";
 import { ingestSources } from "./ingest.js";
 import { searchChunks } from "./search.js";
 import { collectProjectOps, collectSystemOps } from "./collectors.js";
@@ -697,12 +697,34 @@ async function cliDeleteLearning(id) {
         process.exit(1);
     }
 }
-async function cliScore(project, html = false, save = true) {
+/**
+ * 🔒 LOCKED [SCORE-FLEET-IS-OPT-IN] — 2026-08-16
+ * ⛔ NEVER make a bare `contextengine score` iterate the whole fleet again, and never
+ *    let the no-argument path write SCORE.md anywhere but the resolved project root.
+ * WHY: `score` with no argument scored all 37 discovered projects AND wrote a SCORE.md
+ *      into every one of them. Three separate agent sessions ran it expecting to score
+ *      the repo they were standing in, and dirtied 26 unrelated repositories — several of
+ *      which auto-push to Google Drive on commit, so the noise propagated off-machine
+ *      before anyone noticed. The blast radius of the default was the entire fleet while
+ *      the intent behind typing it was almost always a single project.
+ * FIX: the destructive-at-scale operation must be *asked for*. `--all` opts in; no
+ *      argument scores the current working directory's project root. A fleet-wide write
+ *      is a deliberate choice, never a default the user backs into.
+ *      Note the MCP `score_project` tool is read-only (it never writes SCORE.md), which
+ *      is why its fleet-wide default is left alone — the hazard here is the write, not
+ *      the scan.
+ */
+async function cliScore(project, html = false, save = true, all = false) {
     const gate = gateCheck("score_project");
     if (gate) {
         console.error(gate);
         process.exit(1);
     }
+    if (project && all) {
+        console.error(`❌ Cannot combine --all with a project argument ("${project}").`);
+        console.error(`   Use --all for the whole fleet, or name one project/path.`);
+        process.exit(1);
+    }
     // [SCORE-CANARY] — every health signal must read exactly as pinned before we are allowed to
     // write a single SCORE.md. A drifting scorer that silently rewrites 37 reports is the failure
     // this blocks; it does not test for one known bug, it refuses to proceed on ANY deviation.
@@ -718,17 +740,44 @@ async function cliScore(project, html = false, save = true) {
     }
     const projectDirs = loadProjectDirs();
     let scores;
-    if (project) {
-        const dir = projectDirs.find((d) => d.name.toLowerCase() === project.toLowerCase());
+    if (all) {
+        if (save) {
+            console.error(`⚠️  --all: scoring ${projectDirs.length} projects and writing a SCORE.md into each.`);
+            console.error(`   Use --no-save to scan without writing.\n`);
+        }
+        scores = projectDirs.map((d) => scoreProject(d));
+    }
+    else if (project) {
+        // [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(", ")}`);
             process.exit(1);
         }
         scores = [scoreProject(dir)];
     }
     else {
-        scores = projectDirs.map((d) => scoreProject(d));
+        // [SCORE-FLEET-IS-OPT-IN] — no argument means "the project I am standing in",
+        // never "every project on this machine".
+        // [SCORE-CWD-MUST-BE-A-PROJECT] — and if I am not standing in a project, say so
+        // rather than scoring whatever directory happens to be here.
+        const root = findProjectRoot(process.cwd());
+        if (!root) {
+            console.error(`❌ Not inside a project: ${process.cwd()}`);
+            console.error(`   No .git or package.json found here or in any parent directory.`);
+            console.error(`   Do one of:`);
+            console.error(`     • cd into a project, then run: contextengine score`);
+            console.error(`     • name it:                     contextengine score <name|path>`);
+            console.error(`     • score the whole fleet:       contextengine score --all`);
+            process.exit(1);
+        }
+        const known = projectDirs.find((d) => resolve(d.path) === resolve(root));
+        const dir = known ?? { name: basename(root), path: root };
+        console.error(`📍 Scoring current project: ${dir.name} (${dir.path})`);
+        console.error(`   Use --all to score every discovered project.\n`);
+        scores = [scoreProject(dir)];
     }
     if (html) {
         const htmlContent = generateScoreHTML(scores);
@@ -2111,7 +2160,11 @@ Usage:
                                        Fetch community-contributed learnings (Tier A = GitHub
                                        public, Tier B = api.compr.ch Pro). Daily run recommended.
                                        Network failures fall back to cached store.
-  contextengine score [project] [--html] [--no-save] AI-readiness score (Pro, writes SCORE.md)
+  contextengine score [project|path] [--all] [--html] [--no-save]
+                                       AI-readiness score (Pro, writes SCORE.md).
+                                       No argument scores the CURRENT project only.
+                                       Accepts a project name or a directory path.
+                                       --all scores every discovered project (writes to each).
   contextengine audit                  Run compliance audit (Pro)
   contextengine activate <key> <email> Activate a Pro license
   contextengine deactivate             Remove license and premium modules
@@ -2195,8 +2248,9 @@ else if (command === "score") {
     const args = process.argv.slice(3);
     const htmlFlag = args.includes("--html");
     const noSaveFlag = args.includes("--no-save");
+    const allFlag = args.includes("--all");
     const project = args.filter(a => !a.startsWith("--"))[0];
-    cliScore(project, htmlFlag, !noSaveFlag).catch((err) => {
+    cliScore(project, htmlFlag, !noSaveFlag, allFlag).catch((err) => {
         console.error("Error:", err);
         process.exit(1);
     });

package/dist/config.d.ts

@@ -66,6 +66,43 @@ export declare function loadSources(): KnowledgeSource[];
  * Returns one entry per top-level project found.
  */
 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`.
+ *
+ * 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`.
+ */
+export declare function findProjectRoot(start: string): string | null;
 /**
  * Load the raw config (for checking flags like collectSystemOps).
  */

package/dist/config.js

@@ -1,4 +1,4 @@
-import { resolve, join } from "path";
+import { resolve, join, basename, dirname, sep } from "path";
 import { homedir } from "os";
 import { readFileSync, existsSync, readdirSync, statSync } from "fs";
 import { discoverClaudeMemory } from "./claude-integration.js";
@@ -227,6 +227,90 @@ export function loadProjectDirs() {
     }
     return dirs;
 }
+/**
+ * Does this token look like a filesystem path rather than a bare project name?
+ *
+ * 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.
+ */
+function looksLikePath(token) {
+    return (token.includes("/") ||
+        token.includes(sep) ||
+        token.startsWith("~") ||
+        token === "." ||
+        token === "..");
+}
+/**
+ * 🔒 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 function resolveProjectDir(token, dirs) {
+    // Name lookup first — preserves pre-existing behaviour exactly.
+    if (!looksLikePath(token)) {
+        const byName = dirs.find((d) => d.name.toLowerCase() === token.toLowerCase());
+        if (byName)
+            return byName;
+    }
+    // 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 };
+        }
+    }
+    catch {
+        // ENOENT / EACCES — not a usable directory. Fall through to null.
+    }
+    return 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`.
+ *
+ * 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`.
+ */
+export function findProjectRoot(start) {
+    let dir = resolve(start);
+    for (;;) {
+        if (existsSync(join(dir, ".git")) || existsSync(join(dir, "package.json"))) {
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null; // reached filesystem root, no marker seen
+        dir = parent;
+    }
+}
 /**
  * Load the raw config (for checking flags like collectSystemOps).
  */

package/dist/index.js

@@ -2,7 +2,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { loadSources, loadProjectDirs, loadConfig } from "./config.js";
+import { loadSources, loadProjectDirs, loadConfig, resolveProjectDir } from "./config.js";
 import { ingestSources } from "./ingest.js";
 import { searchChunks } from "./search.js";
 import { initEmbeddings, embedChunks, vectorSearch, isEmbeddingsReady, } from "./embeddings.js";
@@ -474,7 +474,7 @@ server.tool("score_project", "Score one or all projects on AI-readiness (0-100%)
     project: z
         .string()
         .optional()
-        .describe("Project name to score. Omit to score all projects."),
+        .describe("Project name OR absolute directory path to score. Omit to score all projects."),
 }, async ({ project }) => {
     const gate = gateCheck("score_project");
     if (gate)
@@ -482,13 +482,15 @@ server.tool("score_project", "Score one or all projects on AI-readiness (0-100%)
     const projectDirs = loadProjectDirs();
     let scores;
     if (project) {
-        const dir = projectDirs.find((d) => d.name.toLowerCase() === project.toLowerCase());
+        // [SCORE-ACCEPTS-PATH] — resolve names and paths alike. This tool never writes
+        // SCORE.md, so unlike the CLI its fleet-wide default is harmless and is kept.
+        const dir = resolveProjectDir(project, projectDirs);
         if (!dir) {
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Project "${project}" not found. Available: ${projectDirs.map((d) => d.name).join(", ")}`,
+                        text: `Project "${project}" not found — not a known project name, and not an existing directory. Available: ${projectDirs.map((d) => d.name).join(", ")}`,
                     },
                 ],
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compr/opscontext-mcp",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "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",

package/skills/opscontext/SKILL.md

@@ -14,7 +14,7 @@ ContextEngine turns your project documentation into a **queryable knowledge base
 ### 1. Initialize (one-time per project)
 
 ```bash
-npx @compr/contextengine-mcp init
+npx @compr/opscontext-mcp init
 ```
 
 Creates `contextengine.json` config + `.github/copilot-instructions.md` template in the current directory.
@@ -39,14 +39,16 @@ ContextEngine auto-discovers documentation files from 7 common patterns:
 ContextEngine also works as a standalone CLI tool — no MCP client needed:
 
 ```bash
-npx @compr/contextengine-mcp search "docker nginx"    # Search knowledge base
-npx @compr/contextengine-mcp list-sources              # Show indexed sources
-npx @compr/contextengine-mcp list-projects             # Discover all projects
-npx @compr/contextengine-mcp score                     # AI-readiness score
-npx @compr/contextengine-mcp score --html               # Visual HTML report
-npx @compr/contextengine-mcp list-learnings security   # List learnings by category
-npx @compr/contextengine-mcp audit                     # Compliance audit
-npx @compr/contextengine-mcp help                      # Show all commands
+npx @compr/opscontext-mcp search "docker nginx"      # Search knowledge base
+npx @compr/opscontext-mcp list-sources               # Show indexed sources
+npx @compr/opscontext-mcp list-projects              # Discover all projects
+npx @compr/opscontext-mcp score                      # Score the CURRENT project (writes its SCORE.md)
+npx @compr/opscontext-mcp score ~/Projects/PLANK.io  # Score one project by name or path
+npx @compr/opscontext-mcp score --all --no-save      # Score every project, write nothing
+npx @compr/opscontext-mcp score --html               # Visual HTML report
+npx @compr/opscontext-mcp list-learnings security    # List learnings by category
+npx @compr/opscontext-mcp audit                      # Compliance audit
+npx @compr/opscontext-mcp help                       # Show all commands
 ```
 
 ## MCP Server Setup
@@ -62,7 +64,7 @@ Add to `.vscode/mcp.json` in your project root:
   "servers": {
     "contextengine": {
       "command": "npx",
-      "args": ["-y", "@compr/contextengine-mcp"],
+      "args": ["-y", "@compr/opscontext-mcp"],
       "env": {
         "CONTEXTENGINE_WORKSPACES": "/path/to/your/projects"
       }
@@ -80,7 +82,7 @@ Add to Claude Desktop MCP config:
   "mcpServers": {
     "contextengine": {
       "command": "npx",
-      "args": ["-y", "@compr/contextengine-mcp"],
+      "args": ["-y", "@compr/opscontext-mcp"],
       "env": {
         "CONTEXTENGINE_WORKSPACES": "/path/to/your/projects"
       }
@@ -98,7 +100,7 @@ Add to your OpenClaw `openclaw.json` MCP servers section:
   "mcpServers": {
     "contextengine": {
       "command": "npx",
-      "args": ["-y", "@compr/contextengine-mcp"],
+      "args": ["-y", "@compr/opscontext-mcp"],
       "env": {
         "CONTEXTENGINE_WORKSPACES": "/path/to/your/projects"
       }
@@ -186,7 +188,7 @@ load_session --name "project-x"
 
 ## Configuration
 
-Create `contextengine.json` in your project root (or run `npx @compr/contextengine-mcp init`):
+Create `contextengine.json` in your project root (or run `npx @compr/opscontext-mcp init`):
 
 ```json
 {
@@ -220,14 +222,14 @@ Create `contextengine.json` in your project root (or run `npx @compr/contextengi
 - First run downloads the embedding model (~22MB) — subsequent runs use cache
 - Keyword search is available instantly at startup; semantic search becomes available once the model loads
 - License: BSL-1.1 (Business Source License)
-- npm: `@compr/contextengine-mcp`
+- npm: `@compr/opscontext-mcp`
 
 ### Post-Commit Verification
 
 After every `git push`, call `end_session` to verify nothing was missed:
 
 - **MCP tool**: `end_session` — use when ContextEngine MCP server is connected
-- **CLI fallback**: `npx @compr/contextengine-mcp end-session` — use when MCP is not connected (Cursor, Copilot, terminal sessions)
+- **CLI fallback**: `npx @compr/opscontext-mcp end-session` — use when MCP is not connected (Cursor, Copilot, terminal sessions)
 
 Resolve any FAIL items before finishing. Workflow: `commit → push → end_session → verify → fix anything it catches → re-commit if needed`.