coding-agent-skills 0.2.16 → 0.2.17

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes follow [Semantic Versioning](docs/versioning/README.md).
 
+## [0.2.17] - 2026-07-04
+
+### Changed
+
+- `repo-map` now supports generic safe discovery when no `.coding-agent` project declaration exists.
+- JSON output now reports `adapterPresent: false`, `mode: generic-safe-discovery`, reduced confidence, `changedState: false`, no target-project commands, and no secret-file reads for no-adapter repo-map runs.
+- Invalid or unsafe project adapters still fail closed instead of falling back silently.
+- Usage, adapter, and release documentation now clarify that adapters are optional hints, not mandatory requirements.
+
 ## [0.2.16] - 2026-07-03
 
 ### Added

package/README.md

@@ -60,7 +60,8 @@ Every skill emits the evidence-pack contract. A command being attempted is never
 - Run `node scripts/validate-adapters.mjs <adapter-root>` for a disposable external root.
 - Review [project-owned installation and pinning](docs/adapters/project-installation.md).
 - Run `node scripts/validate-project-adapters.mjs <project-root>` for a declared project root.
-- Render adapter-aware `repo-map` orientation with
+- Render repo-map orientation with optional adapter hints and generic safe
+  discovery when no adapter is present:
   `node scripts/render-adapter-repo-map.mjs <project-root>`.
 - Render a static route-trace report with
   `node scripts/render-route-trace.mjs <project-root>`.
@@ -118,6 +119,12 @@ OpenClaw should remain the owner of memory, routing, permissions, scheduling, us
 interaction, and workflow state. `coding-agent-skills` is a safe callable evidence
 producer, not an orchestrator.
 
+Adapters are optional hints, not a prerequisite for safe orientation. `repo-map`
+falls back to `generic-safe-discovery` when no `.coding-agent` declaration exists,
+marks `adapterPresent: false`, reduces confidence, and still refuses target project
+builds, tests, runtime checks, deploys, migrations, package installs, and secret-file
+reads.
+
 ## Autonomous Maintainer Loop
 
 The local maintainer loop reads Git tags, `ROADMAP.md`, `CHANGELOG.md`, and

package/bin/coding-agent-skills

@@ -42,8 +42,8 @@ const commandMetadata = {
     skillId: "repo-map",
     mode: "audit-only",
     next: {
-      label: "Review adapter-declared repo boundaries",
-      reason: "Use the reported docs, safe paths, ignored paths, and evidence requirements before choosing another action.",
+      label: "Review reported repo boundaries",
+      reason: "Use the reported docs, safe paths, ignored paths, adapter status, confidence, and evidence requirements before choosing another action.",
       requiresApproval: false,
     },
   },

package/docs/adapters/README.md

@@ -35,6 +35,12 @@ ignored paths, required evidence, package-manager hints, repository bounds, and
 Git branch state. It does not read target project file contents, run project tests or
 builds, install packages, perform runtime checks, deploy, migrate, or read `.env` files.
 
+Adapters are optional hints, not mandatory gates. If no `.coding-agent` declaration is
+present, `repo-map` falls back to `generic-safe-discovery`, reports `adapterPresent: false`,
+uses reduced confidence, applies built-in ignored paths, and still refuses target project
+builds, tests, runtime checks, deployments, migrations, package installs, and secret-file
+reads. Invalid or weakening adapters still fail closed.
+
 This is agent context for safer repository understanding. It is not target-application
 product behavior.
 

package/docs/adapters/project-installation.md

@@ -109,6 +109,12 @@ The renderer is metadata-only. It does not read target project file contents, ru
 project tests, run builds, install packages, perform runtime checks, deploy, migrate, read
 `.env` files, or modify project state.
 
+Project adapters are optional hints. If no project declaration exists, `repo-map` still
+runs a bounded `generic-safe-discovery` report with `adapterPresent: false`, reduced
+confidence, built-in ignored paths, and explicit no-secret/no-build/no-runtime safety
+warnings. A declared adapter that is invalid, unsafe, or incompatible remains a hard
+failure.
+
 A project-owned adapter can also enable read-only `route-trace` context:
 
 ```bash

package/docs/release/npm-package.md

@@ -7,7 +7,7 @@ safety model.
 ## Current Package Shape
 
 - Package name: `coding-agent-skills`.
-- Package version: `0.2.16`.
+- Package version: `0.2.17`.
 - CLI bin: `coding-agent-skills` mapped to `bin/coding-agent-skills`.
 - Module type: `module`.
 - Dependencies: none.

package/docs/usage/README.md

@@ -41,16 +41,18 @@ Select the least-privileged skill that matches the request:
 
 Every skill emits an evidence pack. Read `status`, skipped checks, failures, confidence, and changed state before relying on a completion claim.
 
-When a project owns a compatible adapter, render read-only adapter-aware `repo-map` context
-with:
+Render read-only `repo-map` context with:
 
 ```bash
 node scripts/render-adapter-repo-map.mjs <project-root>
 ```
 
-This validates the project adapter first, then reports adapter-declared documentation
-precedence, safe read paths, ignored paths, and required evidence. It is not a build,
-test, runtime, deployment, migration, package-install, or secret-reading flow.
+When a project owns a compatible adapter, this validates the adapter first and reports
+adapter-declared documentation precedence, safe read paths, ignored paths, and required
+evidence. When no `.coding-agent` declaration exists, adapters remain optional: `repo-map`
+uses `generic-safe-discovery`, reports `adapterPresent: false`, reduces confidence, and
+still refuses builds, tests, runtime checks, deployments, migrations, package installs, and
+secret-file reads.
 
 See [examples](../../examples/README.md) for safe concrete inputs and outputs.
 
@@ -85,8 +87,8 @@ npx coding-agent-skills validate-pack
 ```
 
 These commands wrap the same validated scripts shipped in the repository. `repo-map`
-validates the project adapter first, then renders adapter-declared documentation
-precedence, safe read paths, ignored paths, and required evidence.
+uses adapter metadata when present and valid; otherwise it falls back to generic safe
+discovery with reduced confidence and clear adapter-absence warnings.
 `route-trace` validates a project adapter when present, uses adapter-declared safe paths
 when enabled, and statically reports verified route files, inferred route declarations,
 skipped items, and not-verified runtime-dependent route classes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coding-agent-skills",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "description": "Evidence-first, read-only coding-agent skills and project adapter tooling.",
   "type": "module",
   "private": false,

package/scripts/lib/adapter-repo-map.mjs

@@ -30,6 +30,87 @@ const REFUSED_BEHAVIOR = [
   "no project writes",
 ];
 
+const GENERIC_IGNORED_PATHS = [
+  ".git",
+  ".env",
+  ".env.*",
+  ".next",
+  ".nuxt",
+  ".output",
+  ".turbo",
+  ".cache",
+  "node_modules",
+  "dist",
+  "build",
+  "coverage",
+  "validation-output",
+  "supabase/.temp",
+  "secrets",
+  "tokens",
+  "credentials",
+  "private",
+];
+
+const GENERIC_DOCUMENTATION_PRECEDENCE = [
+  "README.md",
+  "docs/README.md",
+  "docs/kb/README.md",
+  "AGENTS.md",
+  "CLAUDE.md",
+  "RUNBOOK.md",
+  "CONTRIBUTING.md",
+];
+
+const GENERIC_SAFE_READ_PATHS = [
+  "README.md",
+  "docs",
+  "app",
+  "apps",
+  "src",
+  "lib",
+  "pages",
+  "components",
+  "server",
+  "api",
+  "routes",
+  "services",
+  "packages",
+  "schemas",
+  "scripts",
+  "tests",
+  "package.json",
+  "tsconfig.json",
+  "vite.config.ts",
+  "vite.config.js",
+  "next.config.ts",
+  "next.config.js",
+];
+
+const GENERIC_ROOT_MARKERS = [
+  "README.md",
+  "package.json",
+  "pnpm-lock.yaml",
+  "package-lock.json",
+  "yarn.lock",
+  "bun.lockb",
+  "tsconfig.json",
+  "vite.config.ts",
+  "vite.config.js",
+  "next.config.ts",
+  "next.config.js",
+  "pyproject.toml",
+  "Cargo.toml",
+  "go.mod",
+];
+
+const PACKAGE_MANAGER_MARKERS = [
+  ["pnpm-lock.yaml", "pnpm"],
+  ["package-lock.json", "npm"],
+  ["yarn.lock", "yarn"],
+  ["bun.lockb", "bun"],
+  ["package.json", "npm-compatible"],
+];
+
 function inside(root, candidate) {
   const relative = path.relative(root, candidate);
   return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
@@ -90,6 +171,28 @@ function describeApprovedPath(projectRoot, relativePath) {
   };
 }
 
+function existingPathRecords(projectRoot, candidates) {
+  return candidates
+    .map((relativePath) => describeApprovedPath(projectRoot, relativePath))
+    .filter((record) => record.status === "present");
+}
+
+function genericRootMarkers(projectRoot) {
+  return GENERIC_ROOT_MARKERS
+    .map((relativePath) => describeApprovedPath(projectRoot, relativePath))
+    .filter((record) => record.status === "present")
+    .map((record) => ({
+      kind: record.type,
+      path: record.path,
+    }));
+}
+
+function genericPackageManagers(projectRoot) {
+  return PACKAGE_MANAGER_MARKERS
+    .filter(([relativePath]) => describeApprovedPath(projectRoot, relativePath).status === "present")
+    .map(([, manager]) => manager);
+}
+
 function gitSummary(projectRoot) {
   const summary = {
     root: null,
@@ -174,30 +277,92 @@ function loadRepoMapAdapters(loaded) {
 
 export function buildAdapterRepoMapReport(projectRootInput, options = {}) {
   const coreRoot = path.resolve(options.coreRoot ?? DEFAULT_CORE_ROOT);
-  const validation = validateProjectAdapters(projectRootInput, { coreRoot });
-  if (!validation.ok) {
+  const loaded = readProjectAdapterDeclaration(projectRootInput);
+  if (!loaded.ok) {
+    if (loaded.codes.length === 1 && loaded.codes[0] === "missing-project-declaration") {
+      const projectRoot = fs.realpathSync(path.resolve(projectRootInput));
+      const git = gitSummary(projectRoot);
+      return {
+        ok: true,
+        status: "complete",
+        coreVersion: PILOT_VERSION,
+        projectRoot,
+        declarationPath: "not present",
+        adapterRoot: "not present",
+        projectId: "not declared",
+        adapterIds: [],
+        manifestPaths: [],
+        enabledSkills: ["repo-map"],
+        adapter: {
+          present: false,
+          enabled: false,
+          mode: "generic-safe-discovery",
+          codes: ["missing-project-declaration"],
+        },
+        adapterPresent: false,
+        mode: "generic-safe-discovery",
+        confidence: "reduced",
+        rootMarkers: genericRootMarkers(projectRoot),
+        maximumDepth: 2,
+        scope: "generic-project-root",
+        requireApprovalOutsideScope: true,
+        documentationPrecedence: existingPathRecords(projectRoot, GENERIC_DOCUMENTATION_PRECEDENCE),
+        safeReadPaths: existingPathRecords(projectRoot, GENERIC_SAFE_READ_PATHS),
+        ignoredPaths: GENERIC_IGNORED_PATHS,
+        requiredEvidence: [
+          "repository root markers",
+          "bounded generic file/directory inventory",
+          "adapter absence evidence",
+        ],
+        packageManagers: unique(genericPackageManagers(projectRoot)),
+        git,
+        warnings: unique([
+          ...git.warnings,
+          "adapterPresent: false",
+          "mode: generic-safe-discovery",
+          "reduced confidence; adapter-provided project intent is unavailable",
+          "no project adapter declaration found; repo-map used generic bounded discovery",
+          "no target project build, test, runtime, deployment, migration, package, or secret-reading command was performed",
+          "no secrets read",
+        ]),
+        refusedBehavior: REFUSED_BEHAVIOR,
+        validation: {
+          ok: false,
+          status: "failed",
+          acceptedAdapters: 0,
+          acceptedSkills: [],
+          codes: ["missing-project-declaration"],
+        },
+      };
+    }
     return {
       ok: false,
       status: "failed",
-      codes: validation.codes,
-      validation,
+      codes: loaded.codes,
+      validation: {
+        ok: false,
+        status: "failed",
+        acceptedAdapters: 0,
+        acceptedSkills: [],
+        codes: loaded.codes,
+      },
     };
   }
-  if (!validation.acceptedSkills.includes("repo-map")) {
+
+  const validation = validateProjectAdapters(loaded.projectRoot, { coreRoot });
+  if (!validation.ok) {
     return {
       ok: false,
       status: "failed",
-      codes: ["repo-map-not-enabled"],
+      codes: validation.codes,
       validation,
     };
   }
-
-  const loaded = readProjectAdapterDeclaration(projectRootInput);
-  if (!loaded.ok) {
+  if (!validation.acceptedSkills.includes("repo-map")) {
     return {
       ok: false,
       status: "failed",
-      codes: loaded.codes,
+      codes: ["repo-map-not-enabled"],
       validation,
     };
   }
@@ -246,6 +411,15 @@ export function buildAdapterRepoMapReport(projectRootInput, options = {}) {
     adapterIds: adapters.map((adapter) => adapter.manifest.adapterId).sort(),
     manifestPaths: adapters.map((adapter) => adapter.manifestPath).sort(),
     enabledSkills: ["repo-map"],
+    adapter: {
+      present: true,
+      enabled: true,
+      mode: "adapter-limited",
+      codes: [],
+    },
+    adapterPresent: true,
+    mode: "adapter-limited",
+    confidence: "adapter-declared",
     rootMarkers,
     maximumDepth,
     scope: "declared-project-root",
@@ -294,10 +468,16 @@ export function renderAdapterRepoMapReport(report) {
     `Project root: ${redactSensitiveText(report.projectRoot)}`,
     `Declaration: ${report.declarationPath}`,
     `Adapter root: ${report.adapterRoot}`,
-    `Adapter IDs: ${report.adapterIds.join(", ")}`,
-    `Adapter manifests: ${report.manifestPaths.join(", ")}`,
+    `Adapter IDs: ${report.adapterIds.length ? report.adapterIds.join(", ") : "none"}`,
+    `Adapter manifests: ${report.manifestPaths.length ? report.manifestPaths.join(", ") : "none"}`,
     `Enabled skills: ${report.enabledSkills.join(", ")}`,
     "",
+    "## Adapter Scope",
+    `- Adapter present: ${report.adapterPresent ? "yes" : "no"}`,
+    `- Repo-map enabled: ${report.adapter?.enabled ? "yes" : "generic fallback"}`,
+    `- Mode: ${report.mode}`,
+    `- Confidence: ${report.confidence}`,
+    "",
     "## Git State",
     `- Git root: ${redactSensitiveText(report.git.root ?? "not detected")}`,
     `- Branch state: ${redactSensitiveText(report.git.branchState ?? "not detected")}`,
@@ -334,6 +514,8 @@ export function renderAdapterRepoMapReport(report) {
     ...formatList("Refused Behavior", report.refusedBehavior),
     "",
     "No target project build, test, runtime, deployment, migration, package installation, or secret-file read was performed.",
+    "No project commands beyond safe repository metadata inspection were performed.",
+    "No secrets were read.",
   ];
 
   return lines.join("\n");

package/scripts/test-pack.mjs

@@ -221,7 +221,7 @@ function snapshotAbsoluteDirectory(directory) {
   return digest.digest("hex");
 }
 
-function assertOpenClawJsonContract(value, command, packageVersion = "0.2.16") {
+function assertOpenClawJsonContract(value, command, packageVersion = "0.2.17") {
   assert.equal(value.tool, "coding-agent-skills");
   assert.equal(value.command, command);
   assert.equal(value.packageVersion, packageVersion);
@@ -378,6 +378,10 @@ test("local CLI maps approved commands to existing safe scripts", () => {
       ["repo-map", path.join(fixtureRoot, "project-adapter-installation", "valid-exact-pin")],
       /# Adapter-Aware Repo Map/,
     ],
+    [
+      ["repo-map", path.join(fixtureRoot, "sample-repo")],
+      /generic-safe-discovery/,
+    ],
     [
       ["route-trace", path.join(fixtureRoot, "route-trace", "static-project")],
       /# Route Trace Report/,
@@ -443,6 +447,7 @@ test("local CLI emits OpenClaw-compatible JSON for public commands", () => {
       path.join(fixtureRoot, "project-adapter-installation", "valid-exact-pin"),
     ],
     ["repo-map", path.join(fixtureRoot, "project-adapter-installation", "valid-exact-pin")],
+    ["repo-map", path.join(fixtureRoot, "sample-repo")],
     ["route-trace", path.join(fixtureRoot, "route-trace", "static-project")],
     ["env-audit", path.join(fixtureRoot, "env-audit", "static-project")],
     ["secret-audit", path.join(fixtureRoot, "secret-audit", "static-project")],
@@ -488,7 +493,7 @@ test("local CLI emits OpenClaw-compatible JSON for public commands", () => {
 test("npm package metadata is public-ready and dependency-free", () => {
   const packageJson = readJson("package.json");
   assert.equal(packageJson.name, "coding-agent-skills");
-  assert.equal(packageJson.version, "0.2.16");
+  assert.equal(packageJson.version, "0.2.17");
   assert.equal(
     packageJson.description,
     "Evidence-first, read-only coding-agent skills and project adapter tooling.",
@@ -1769,6 +1774,42 @@ test("adapter-aware repo-map consumes validated project adapter metadata", () =>
   assert.match(rendered, /No target project build, test, runtime, deployment/);
 });
 
+test("repo-map supports generic safe discovery without a project adapter", () => {
+  const report = buildAdapterRepoMapReport(
+    path.join(root, "tests", "fixtures", "sample-repo"),
+    { coreRoot: root },
+  );
+
+  assert.equal(report.ok, true, report.codes?.join(","));
+  assert.equal(report.adapter.present, false);
+  assert.equal(report.adapter.enabled, false);
+  assert.equal(report.mode, "generic-safe-discovery");
+  assert.equal(report.confidence, "reduced");
+  assert.equal(report.adapterPresent, false);
+  assert.ok(report.validation.codes.includes("missing-project-declaration"));
+  assert.ok(report.warnings.includes("adapterPresent: false"));
+  assert.ok(report.warnings.includes("mode: generic-safe-discovery"));
+  assert.ok(report.warnings.includes("no secrets read"));
+  assert.ok(report.ignoredPaths.includes(".env"));
+  assert.ok(report.ignoredPaths.includes(".env.*"));
+  assert.ok(
+    report.documentationPrecedence.some((record) => record.path === "README.md"),
+  );
+
+  const rendered = renderAdapterRepoMapReport(report);
+  assert.match(rendered, /Adapter present: no/);
+  assert.match(rendered, /Mode: generic-safe-discovery/);
+  assert.match(rendered, /Confidence: reduced/);
+  assert.match(rendered, /No secrets were read/);
+
+  const cli = adapterRepoMapCliResult(path.join(root, "tests", "fixtures", "sample-repo"), {
+    coreRoot: root,
+  });
+  assert.equal(cli.exitCode, 0);
+  assert.equal(cli.stream, "stdout");
+  assert.match(cli.lines.join("\n"), /generic-safe-discovery/);
+});
+
 test("adapter-aware repo-map fails closed without repo-map compatibility", () => {
   const fixtureRoot = path.join(
     root,

package/scripts/validate-pack.mjs

@@ -687,8 +687,8 @@ if (packageJson) {
   if (packageJson.name !== "coding-agent-skills") {
     failures.push("package.json has unexpected package name");
   }
-  if (packageJson.version !== "0.2.16") {
-    failures.push("package.json version must be 0.2.16 for public package validation");
+  if (packageJson.version !== "0.2.17") {
+    failures.push("package.json version must be 0.2.17 for public package validation");
   }
   if (packageJson.type !== "module") failures.push("package.json must preserve ESM mode");
   if (packageJson.private !== false) {