coding-agent-skills 0.2.15 → 0.2.17

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 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
+
+- Optional `--json` output for every public `coding-agent-skills` CLI command.
+- OpenClaw-compatible structured result fields for command identity, skill id, package
+  version, status, findings, warnings, skipped checks, refused behavior, safety summary,
+  `recommendedNextAction`, and exit-code meaning.
+- Release tests that validate the JSON contract across the public CLI surface and confirm
+  redaction of local home paths and secret-like values.
+
+### Changed
+
+- The public wrapper now preserves default human-readable output while offering sanitized
+  machine-readable results for orchestrator callers.
+- Usage, release, testing, roadmap, ledger, and run-log docs now describe the exit-code
+  contract and OpenClaw integration boundary.
+- Stale v0.2.15 ledger and run-log entries now reflect that the deployment-preflight
+  release was published, smoke-tested, and released.
+
 ## [0.2.15] - 2026-07-03
 
 ### Added

package/README.md

@@ -52,12 +52,16 @@ Every skill emits the evidence-pack contract. A command being attempted is never
 - Review static migration and schema evidence with `coding-agent-skills migration-review <project-root>`.
 - Prepare local Git handoff evidence with `coding-agent-skills github-handoff <project-root>`.
 - Map static deployment readiness evidence with `coding-agent-skills deployment-preflight <project-root>`.
+- Add `--json` to any public CLI command when an OpenClaw-style orchestrator
+  needs a sanitized machine-readable result with `success`, `status`,
+  `recommendedNextAction`, safety flags, and exit-code meaning.
 - Validate project adapters against [the formal adapter schema](schemas/project-adapter.schema.json).
 - Review [external adapter discovery](docs/adapters/discovery.md).
 - 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>`.
@@ -92,6 +96,35 @@ Every skill emits the evidence-pack contract. A command being attempted is never
 Governance lives in [CONTRIBUTING.md](CONTRIBUTING.md), [ROADMAP.md](ROADMAP.md), and the [release policy](docs/release/README.md).
 The [harness guide](docs/testing/README.md) explains trigger, command, mutation, privacy, adapter, and completion checks.
 
+## Orchestrator Output
+
+The default CLI output remains human-readable. OpenClaw-style callers can request a
+structured result with `--json`:
+
+```bash
+coding-agent-skills repo-map /path/to/project --json
+```
+
+JSON output is read-only and sanitized. It includes command identity, package version,
+skill id, status, findings, warnings, skipped checks, refused behavior, safety flags,
+and `recommendedNextAction`. Exit codes follow the public contract:
+
+- `0`: handled execution path, including complete, partial, blocked, or controlled audit results
+- `2`: usage error
+- `3`: safety refusal
+- `4`: missing required input or file
+- `5`: unexpected internal or runtime failure
+
+OpenClaw should remain the owner of memory, routing, permissions, scheduling, user
+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/ROADMAP.md

@@ -42,6 +42,8 @@ execution constraints remain unchanged.
   evidence before separately approved GitHub work.
 - `v0.2.15`: audit-only `deployment-preflight` skill and CLI renderer for static
   deployment readiness evidence before separately approved deployment work.
+- `v0.2.16`: OpenClaw-compatible optional `--json` output and documented exit-code
+  semantics for every public CLI command.
 
 The next milestone is recorded in [work-ledger.md](work-ledger.md). The
 [maintainer loop](RUNBOOK.md) may select and evidence that milestone, but it must stop
@@ -89,6 +91,7 @@ Next safe milestone options:
 | `migration-review-skill` | General with platform adapters | Audit-only | Implemented in `v0.2.13` |
 | `github-handoff-skill` | General | Audit-only | Implemented in `v0.2.14` |
 | `deployment-preflight-skill` | General | Audit-only | Implemented in `v0.2.15` |
+| `orchestrator-json-output-contract` | General tooling | Read-only CLI contract | Implemented in `v0.2.16` |
 | `cloudflare-preflight-skill` | Platform-specific | Audit-only | Builder-mode approved; later in wave |
 | `cloudflare-deploy-skill` | Platform-specific | Action-capable | Blocked on approval model |
 | `supabase-rls-audit-skill` | Platform-specific | Audit-only | Builder-mode approved; later in wave |

package/bin/coding-agent-skills

@@ -1,9 +1,125 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
+import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { externalAdapterCliResult } from "../scripts/lib/adapter-discovery.mjs";
+import { adapterRepoMapCliResult } from "../scripts/lib/adapter-repo-map.mjs";
+import { apiContractAuditCliResult } from "../scripts/lib/api-contract-audit.mjs";
+import { deploymentPreflightCliResult } from "../scripts/lib/deployment-preflight.mjs";
+import { envAuditCliResult } from "../scripts/lib/env-audit.mjs";
+import { githubHandoffCliResult } from "../scripts/lib/github-handoff.mjs";
+import { migrationReviewCliResult } from "../scripts/lib/migration-review.mjs";
+import { redactSensitiveText } from "../scripts/lib/pack-rules.mjs";
+import { projectAdapterCliResult } from "../scripts/lib/project-adapter-installation.mjs";
+import { routeTraceCliResult } from "../scripts/lib/route-trace.mjs";
+import { secretAuditCliResult } from "../scripts/lib/secret-audit.mjs";
+
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const packageJson = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8"));
+
+const commandMetadata = {
+  "validate-pack": {
+    skillId: "pack-validation",
+    mode: "validation",
+    next: {
+      label: "Select a read-only audit command",
+      reason: "The package is structurally valid; choose the narrowest command for the target task.",
+      requiresApproval: false,
+    },
+  },
+  "validate-project": {
+    skillId: "project-adapter-validation",
+    mode: "validation",
+    next: {
+      label: "Run an adapter-aware read-only report",
+      reason: "The project adapter declaration is valid; use a scoped report command next.",
+      requiresApproval: false,
+    },
+  },
+  "repo-map": {
+    skillId: "repo-map",
+    mode: "audit-only",
+    next: {
+      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,
+    },
+  },
+  "route-trace": {
+    skillId: "route-trace",
+    mode: "audit-only",
+    next: {
+      label: "Review static route findings",
+      reason: "Inspect verified and inferred route surfaces before approving code or runtime work.",
+      requiresApproval: false,
+    },
+  },
+  "env-audit": {
+    skillId: "env-audit",
+    mode: "audit-only",
+    next: {
+      label: "Review variable-name inventory",
+      reason: "Use value-free environment names to plan documentation or configuration review without reading secrets.",
+      requiresApproval: false,
+    },
+  },
+  "secret-audit": {
+    skillId: "secret-audit",
+    mode: "audit-only",
+    next: {
+      label: "Review redacted secret-risk findings",
+      reason: "Any remediation, credential rotation, or repository mutation needs separate approval.",
+      requiresApproval: true,
+    },
+  },
+  "api-contract-audit": {
+    skillId: "api-contract-audit",
+    mode: "audit-only",
+    next: {
+      label: "Review static API contract surfaces",
+      reason: "Use contract, endpoint, client, and schema evidence before editing API code.",
+      requiresApproval: false,
+    },
+  },
+  "migration-review": {
+    skillId: "migration-review",
+    mode: "audit-only",
+    next: {
+      label: "Review migration evidence",
+      reason: "Database access, migration edits, generation, or execution require separate approval.",
+      requiresApproval: true,
+    },
+  },
+  "github-handoff": {
+    skillId: "github-handoff",
+    mode: "audit-only",
+    next: {
+      label: "Request explicit GitHub handoff approval",
+      reason: "Commit, push, tag, pull request, or API mutation work is outside this read-only report.",
+      requiresApproval: true,
+    },
+  },
+  "deployment-preflight": {
+    skillId: "deployment-preflight",
+    mode: "audit-only",
+    next: {
+      label: "Request explicit deployment approval",
+      reason: "Deployment, provider API, provider CLI, build, runtime, or migration work is outside this read-only report.",
+      requiresApproval: true,
+    },
+  },
+  "validate-adapters": {
+    skillId: "external-adapter-validation",
+    mode: "validation",
+    next: {
+      label: "Use accepted adapters only as narrowing metadata",
+      reason: "Adapters may narrow safe context but must not grant new powers or weaken shared restrictions.",
+      requiresApproval: false,
+    },
+  },
+};
 
 const commands = {
   "validate-pack": {
@@ -73,6 +189,29 @@ const commands = {
   },
 };
 
+const jsonHandlers = {
+  "validate-project": ([projectRoot]) => projectAdapterCliResult(projectRoot, { coreRoot: repoRoot }),
+  "repo-map": ([projectRoot]) => adapterRepoMapCliResult(projectRoot, { coreRoot: repoRoot }),
+  "route-trace": ([projectRoot]) => routeTraceCliResult(projectRoot, { coreRoot: repoRoot }),
+  "env-audit": ([projectRoot]) => envAuditCliResult(projectRoot, { coreRoot: repoRoot }),
+  "secret-audit": ([projectRoot]) => secretAuditCliResult(projectRoot, { coreRoot: repoRoot }),
+  "api-contract-audit": ([projectRoot]) => apiContractAuditCliResult(projectRoot, { coreRoot: repoRoot }),
+  "migration-review": ([projectRoot]) => migrationReviewCliResult(projectRoot, { coreRoot: repoRoot }),
+  "github-handoff": ([projectRoot]) => githubHandoffCliResult(projectRoot, { coreRoot: repoRoot }),
+  "deployment-preflight": ([projectRoot]) => deploymentPreflightCliResult(projectRoot, { coreRoot: repoRoot }),
+  "validate-adapters": ([adapterRoot]) => externalAdapterCliResult(adapterRoot, { coreRoot: repoRoot }),
+};
+
+function stripJsonFlag(args) {
+  let json = false;
+  const rest = [];
+  for (const arg of args) {
+    if (arg === "--json") json = true;
+    else rest.push(arg);
+  }
+  return { json, args: rest };
+}
+
 function usage(exitCode = 0) {
   const lines = [
     "usage: coding-agent-skills <command> [args]",
@@ -97,7 +236,192 @@ function usage(exitCode = 0) {
   process.exitCode = exitCode;
 }
 
-const [commandName, ...args] = process.argv.slice(2);
+function sanitizedLines(text) {
+  return redactSensitiveText(text)
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter((line) => line.length > 0);
+}
+
+function sectionLines(lines, heading) {
+  const result = [];
+  let active = false;
+  for (const line of lines) {
+    if (line === `## ${heading}`) {
+      active = true;
+      continue;
+    }
+    if (active && line.startsWith("## ")) break;
+    if (active && line.trim()) result.push(line.replace(/^- /, ""));
+  }
+  return result.filter((line) => line !== "none" && line !== "none found");
+}
+
+function detectedStatus(lines, exitCode) {
+  for (const line of lines) {
+    const match = /^Status:\s*([a-z-]+)/i.exec(line);
+    if (match) return match[1].toLowerCase();
+  }
+  if (exitCode === 0) return "complete";
+  if (exitCode === 2) return "failed";
+  return "failed";
+}
+
+function exitCodeMeaning(exitCode) {
+  if (exitCode === 0) return "handled";
+  if (exitCode === 2) return "usage-error";
+  if (exitCode === 3) return "safety-refusal";
+  if (exitCode === 4) return "missing-required-input";
+  return "unexpected-internal-or-runtime-failure";
+}
+
+function adapterSummary(lines) {
+  const adapter = {};
+  const adapterLines = [
+    ...sectionLines(lines, "Adapter Scope"),
+    ...sectionLines(lines, "Adapter Bounds"),
+  ];
+  for (const line of adapterLines) {
+    const match = /^([^:]+):\s*(.*)$/.exec(line);
+    if (!match) continue;
+    const key = match[1]
+      .trim()
+      .replace(/[^a-zA-Z0-9]+([a-zA-Z0-9])/g, (_, char) => char.toUpperCase())
+      .replace(/^[A-Z]/, (char) => char.toLowerCase());
+    adapter[key] = match[2].trim();
+  }
+  return adapter;
+}
+
+function summaryLines(lines) {
+  return lines
+    .filter((line) => line.trim().length > 0)
+    .filter((line) => !line.startsWith("#"))
+    .filter((line) => !line.startsWith("## "))
+    .filter((line) => !line.startsWith("- "))
+    .slice(0, 12);
+}
+
+function findingLines(lines) {
+  const ignoredSections = new Set([
+    "Git State",
+    "Adapter Scope",
+    "Adapter Bounds",
+    "Scope Paths",
+    "Ignored Paths",
+    "Summary",
+    "Skipped",
+    "Not Verified",
+    "Warnings",
+    "Refused Behavior",
+  ]);
+  const findings = [];
+  let current = null;
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      current = line.replace(/^## /, "");
+      continue;
+    }
+    if (!current || ignoredSections.has(current)) continue;
+    if (line.startsWith("- ") && !line.includes("none found")) findings.push(line.slice(2));
+  }
+  return findings.slice(0, 100);
+}
+
+function normalizeOutcome(outcome) {
+  if (Array.isArray(outcome.lines)) {
+    return {
+      exitCode: outcome.exitCode ?? 5,
+      lines: outcome.lines
+        .map((line) => redactSensitiveText(line))
+        .filter((line) => line.trim().length > 0),
+      report: outcome.report ?? outcome.result ?? null,
+    };
+  }
+
+  return {
+    exitCode: outcome.status ?? 5,
+    lines: [
+      ...sanitizedLines(outcome.stdout ?? ""),
+      ...sanitizedLines(outcome.stderr ?? ""),
+    ],
+    report: null,
+  };
+}
+
+function buildJsonResult(commandName, args, outcome) {
+  const normalized = normalizeOutcome(outcome);
+  const lines = normalized.lines;
+  const metadata = commandMetadata[commandName] ?? {
+    skillId: commandName,
+    mode: "unknown",
+    next: null,
+  };
+  const status = normalized.report?.status ?? detectedStatus(lines, normalized.exitCode);
+  const summary = summaryLines(lines);
+  const warnings = [
+    ...(Array.isArray(normalized.report?.warnings)
+      ? normalized.report.warnings.map((line) => redactSensitiveText(line))
+      : []),
+    ...sectionLines(lines, "Warnings"),
+    ...lines.filter((line) => /\bwarning\b/i.test(line) && !line.startsWith("## ")),
+  ];
+
+  return {
+    success: normalized.exitCode === 0,
+    status,
+    tool: "coding-agent-skills",
+    command: commandName,
+    skillId: metadata.skillId,
+    packageVersion: packageJson.version,
+    mode: metadata.mode,
+    changedState: false,
+    summary: summary.length > 0
+      ? summary
+      : [
+          normalized.exitCode === 0
+            ? `${commandName} completed successfully`
+            : `${commandName} did not complete successfully`,
+        ],
+    findings: Array.isArray(normalized.report?.findings)
+      ? normalized.report.findings.map((finding) => redactSensitiveText(JSON.stringify(finding)))
+      : findingLines(lines),
+    warnings: [...new Set(warnings)],
+    risks: Array.isArray(normalized.report?.riskIndicators)
+      ? normalized.report.riskIndicators.map((risk) => redactSensitiveText(JSON.stringify(risk)))
+      : sectionLines(lines, "Risk Indicators"),
+    skipped: Array.isArray(normalized.report?.skipped)
+      ? normalized.report.skipped.map((item) => redactSensitiveText(JSON.stringify(item)))
+      : sectionLines(lines, "Skipped"),
+    notVerified: Array.isArray(normalized.report?.notVerified)
+      ? normalized.report.notVerified.map((item) => redactSensitiveText(String(item)))
+      : sectionLines(lines, "Not Verified"),
+    refusedBehavior: Array.isArray(normalized.report?.refusedBehavior)
+      ? normalized.report.refusedBehavior.map((item) => redactSensitiveText(String(item)))
+      : sectionLines(lines, "Refused Behavior"),
+    adapter: adapterSummary(lines),
+    recommendedNextAction: metadata.next,
+    safety: {
+      readOnly: true,
+      secretsRead: false,
+      targetCommandsRun: false,
+      mutationsPerformed: false,
+    },
+    exitCode: normalized.exitCode,
+    exitCodeMeaning: exitCodeMeaning(normalized.exitCode),
+    invocation: {
+      args: args.map((arg) => redactSensitiveText(arg)),
+      outputFormat: "json",
+    },
+  };
+}
+
+function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+const { json, args: rawArgs } = stripJsonFlag(process.argv.slice(2));
+const [commandName, ...args] = rawArgs;
 if (!commandName || commandName === "help" || commandName === "--help" || commandName === "-h") {
   usage(commandName ? 0 : 2);
 } else if (!Object.hasOwn(commands, commandName)) {
@@ -108,6 +432,10 @@ if (!commandName || commandName === "help" || commandName === "--help" || comman
   if ((command.requiredArgs ?? 0) !== args.length) {
     process.stderr.write(`usage: ${command.usage}\n`);
     process.exitCode = 2;
+  } else if (json && jsonHandlers[commandName]) {
+    const outcome = jsonHandlers[commandName](args);
+    printJson(buildJsonResult(commandName, args, outcome));
+    process.exitCode = outcome.exitCode ?? 5;
   } else {
     const result = spawnSync(
       process.execPath,
@@ -115,10 +443,13 @@ if (!commandName || commandName === "help" || commandName === "--help" || comman
       {
         cwd: repoRoot,
         encoding: "utf8",
-        stdio: "inherit",
+        stdio: json ? "pipe" : "inherit",
         shell: false,
       },
     );
+    if (json) {
+      printJson(buildJsonResult(commandName, args, result));
+    }
     process.exitCode = result.status ?? 1;
   }
 }

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/README.md

@@ -19,20 +19,23 @@
 13. Inspect tarball contents for local-only files, credentials, `.env` files, dependency
     folders, generated output, and unrelated repositories.
 14. Install the tarball into a temporary npm prefix and smoke-test the installed CLI.
-15. Smoke-test any new CLI command such as `coding-agent-skills route-trace`,
+15. Smoke-test human-readable and `--json` output for public commands touched by the
+    release. JSON output must include safety flags, `recommendedNextAction`, and
+    `exitCodeMeaning` without secrets or `.env` contents.
+16. Smoke-test any new CLI command such as `coding-agent-skills route-trace`,
     `coding-agent-skills env-audit`, `coding-agent-skills secret-audit`,
     `coding-agent-skills api-contract-audit`, `coding-agent-skills migration-review`,
     `coding-agent-skills github-handoff`, or `coding-agent-skills deployment-preflight`
     against synthetic fixtures only unless a real project read-only smoke is explicitly
     approved.
-16. Review changelog, ledger, run evidence, and versioning impact.
-17. Commit with approved identity.
-18. Push `main` using credential-free remotes.
-19. Confirm a clean synchronized worktree.
-20. Create and push the annotated version tag.
-21. Publish with `npm publish --access public --registry=https://registry.npmjs.org/`.
-22. Install the published package into a temporary prefix and smoke-test the installed CLI.
-23. Create the GitHub Release for the pushed tag.
+17. Review changelog, ledger, run evidence, and versioning impact.
+18. Commit with approved identity.
+19. Push `main` using credential-free remotes.
+20. Confirm a clean synchronized worktree.
+21. Create and push the annotated version tag.
+22. Publish with `npm publish --access public --registry=https://registry.npmjs.org/`.
+23. Install the published package into a temporary prefix and smoke-test the installed CLI.
+24. Create the GitHub Release for the pushed tag.
 
 Deployments, migrations, runtime mutation, platform actions, and target-project builds or
 tests remain outside this release process unless separately approved.

package/docs/release/npm-package.md

@@ -7,7 +7,7 @@ safety model.
 ## Current Package Shape
 
 - Package name: `coding-agent-skills`.
-- Package version: `0.2.15`.
+- Package version: `0.2.17`.
 - CLI bin: `coding-agent-skills` mapped to `bin/coding-agent-skills`.
 - Module type: `module`.
 - Dependencies: none.
@@ -37,6 +37,18 @@ coding-agent-skills deployment-preflight /path/to/project
 coding-agent-skills validate-adapters /path/to/adapter-root
 ```
 
+Each public command also supports optional machine-readable output:
+
+```bash
+coding-agent-skills repo-map /path/to/project --json
+```
+
+The JSON contract is intended for OpenClaw-style orchestrators that already own memory,
+routing, approvals, scheduling, and workflow state. It includes `success`, `status`,
+`command`, `skillId`, `packageVersion`, sanitized findings and warnings, safety flags,
+`recommendedNextAction`, and `exitCodeMeaning`. The default human-readable output is
+unchanged.
+
 The package can also be executed without a repo-local install:
 
 ```bash
@@ -112,3 +124,11 @@ already permits a bounded local validation action. The installed `repo-map`,
 
 Project adapters narrow context for safer repository understanding; they do not weaken
 shared restrictions or authorize additional command families.
+
+## Exit Codes
+
+- `0`: handled execution path, including complete, partial, blocked, or controlled audit result
+- `2`: usage error
+- `3`: safety refusal
+- `4`: missing required input or file
+- `5`: unexpected internal or runtime failure

package/docs/testing/README.md

@@ -126,6 +126,14 @@ compatibility, schema drift, restriction weakening, evidence removal, failure su
 completion override, mode escalation, `.env` avoidance, traversal, symlinks, and mutation
 snapshots. Chain summaries use ordinal revision labels rather than directory names.
 
+## OpenClaw-Compatible CLI JSON
+
+Public CLI tests exercise `--json` for every exposed command. The contract must remain
+valid JSON, preserve default human-readable output, include safety flags and
+`recommendedNextAction`, use handled exit semantics for successful/partial audit results,
+redact local home paths, and avoid token, private-key, authorization-header, or `.env`
+contents.
+
 ## Evidence Bundles
 
 Disposable evidence bundles cover valid replay, hash mismatch, missing entries,

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.
@@ -117,6 +119,50 @@ The installed CLI does not run target project builds or tests, perform runtime c
 deploy, migrate, mutate services or processes, or read `.env` files. Project adapters
 narrow context; they do not grant additional power or weaken shared restrictions.
 
+## Machine-Readable Output
+
+Every public CLI command accepts optional `--json` for OpenClaw-style tool callers:
+
+```bash
+coding-agent-skills repo-map /path/to/project --json
+coding-agent-skills validate-pack --json
+```
+
+The default human-readable output is unchanged. JSON output is sanitized and includes:
+
+- `success`
+- `status`
+- `tool`
+- `command`
+- `skillId`
+- `packageVersion`
+- `mode`
+- `changedState`
+- `summary`
+- `findings`
+- `warnings`
+- `risks`
+- `skipped`
+- `notVerified`
+- `refusedBehavior`
+- `adapter`
+- `recommendedNextAction`
+- `safety`
+- `exitCode`
+- `exitCodeMeaning`
+
+Exit-code semantics:
+
+- `0`: handled execution path, including complete, partial, blocked, or controlled audit result
+- `2`: usage error
+- `3`: safety refusal
+- `4`: missing required input or file
+- `5`: unexpected internal or runtime failure
+
+OpenClaw or another orchestrator should own memory, routing, permissions, scheduling,
+chat/user interaction, and workflow state. This package remains a read-only external tool
+and evidence producer.
+
 ## Local Command Surface
 
 From the shared skill repository root, the same wrapper can be used directly:

package/package.json

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

package/runs/skill-runs.md

@@ -277,6 +277,23 @@ This file records bounded maintainer-loop runs. Entries must not contain secrets
   API calls, no provider CLI execution, no package installs, no builds, no tests, no
   runtime checks, no service mutation, no deployments, no migrations, and no target-project
   mutation.
+- Validation commands: full source validation, package dry-run, tarball smoke, registry
+  install smoke, npm exec, and GitHub Release verification.
+- Result: passed; `v0.2.15` was committed, pushed, tagged, published to npm, smoke-tested
+  from the registry, and released on GitHub.
+- Commit/tag/push status: complete.
+
+## implementation-v0.2.16-openclaw-json-output
+
+- Run ID: `implementation-v0.2.16-openclaw-json-output`
+- Repository: `/home/oneclickwebsitedesignfactory/coding-agent-skills`
+- Command used: `bounded approval for OpenClaw-compatible JSON output and exit-code contract`
+- Files changed: CLI wrapper, release tests, usage/release/testing docs, changelog,
+  roadmap, work ledger, run log, and package metadata.
+- Safety boundary: read-only machine-readable output only; no `.env` reads, no OpenClaw
+  modification, no OpenClaw plugin code, no cron or memory integration, no real project
+  repository mutation, no target-project builds/tests/runtime checks, no deployments, no
+  migrations, and no dependency changes.
 - Validation commands: pending final release validation matrix.
 - Result: pass pending final publication evidence.
 - Commit/tag/push status: pending approved release workflow.

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,6 +221,39 @@ function snapshotAbsoluteDirectory(directory) {
   return digest.digest("hex");
 }
 
+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);
+  assert.equal(value.success, true);
+  assert.match(value.status, /^(complete|partial|blocked|failed|empty)$/);
+  assert.equal(value.changedState, false);
+  assert.equal(value.safety?.readOnly, true);
+  assert.equal(value.safety?.secretsRead, false);
+  assert.equal(value.safety?.targetCommandsRun, false);
+  assert.equal(value.safety?.mutationsPerformed, false);
+  assert.equal(value.exitCode, 0);
+  assert.equal(value.exitCodeMeaning, "handled");
+  assert.ok(value.recommendedNextAction);
+  assert.equal(typeof value.recommendedNextAction.label, "string");
+  assert.equal(typeof value.recommendedNextAction.reason, "string");
+  assert.equal(typeof value.recommendedNextAction.requiresApproval, "boolean");
+  for (const key of [
+    "summary",
+    "findings",
+    "warnings",
+    "risks",
+    "skipped",
+    "notVerified",
+    "refusedBehavior",
+  ]) {
+    assert.ok(Array.isArray(value[key]), `${command}.${key} must be an array`);
+  }
+  const encoded = JSON.stringify(value);
+  assert.doesNotMatch(encoded, /github_pat_|ghp_|Authorization:\s*Bearer|BEGIN .*PRIVATE KEY/i);
+  assert.doesNotMatch(encoded, /\/home\/oneclickwebsitedesignfactory\//);
+}
+
 const manifestSchema = readJson("schemas/skill-manifest.schema.json");
 const policySchema = readJson("schemas/command-policy.schema.json");
 const adapterSchema = readJson("schemas/project-adapter.schema.json");
@@ -345,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/,
@@ -394,10 +431,69 @@ test("local CLI maps approved commands to existing safe scripts", () => {
   assert.match(unknown.stderr, /unknown command: deploy/);
 });
 
+test("local CLI emits OpenClaw-compatible JSON for public commands", () => {
+  const cliPath = path.join(root, "bin", "coding-agent-skills");
+  const fixtureRoot = path.join(root, "tests", "fixtures");
+  const githubHandoffFixture = createGitFixture(
+    path.join("tests", "fixtures", "github-handoff", "static-project"),
+  );
+  fs.appendFileSync(path.join(githubHandoffFixture, "README.md"), "\nLocal handoff change.\n");
+
+  const commands = [
+    ["validate-pack"],
+    ["validate-adapters", path.join(fixtureRoot, "external-adapters", "valid-basic")],
+    [
+      "validate-project",
+      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")],
+    ["api-contract-audit", path.join(fixtureRoot, "api-contract-audit", "static-project")],
+    ["migration-review", path.join(fixtureRoot, "migration-review", "static-project")],
+    ["github-handoff", githubHandoffFixture],
+    ["deployment-preflight", path.join(fixtureRoot, "deployment-preflight", "static-project")],
+  ];
+
+  for (const args of commands) {
+    const result = spawnSync(cliPath, [...args, "--json"], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: "pipe",
+    });
+    assert.equal(result.status, 0, `${args.join(" ")}\n${result.stderr}`);
+    assert.equal(result.stderr, "");
+    const parsed = JSON.parse(result.stdout);
+    assertOpenClawJsonContract(parsed, args[0]);
+  }
+
+  const partial = spawnSync(
+    cliPath,
+    [
+      "deployment-preflight",
+      path.join(fixtureRoot, "project-adapter-installation", "valid-exact-pin"),
+      "--json",
+    ],
+    {
+      cwd: root,
+      encoding: "utf8",
+      stdio: "pipe",
+    },
+  );
+  assert.equal(partial.status, 0);
+  const parsedPartial = JSON.parse(partial.stdout);
+  assertOpenClawJsonContract(parsedPartial, "deployment-preflight");
+  assert.equal(parsedPartial.status, "partial");
+  assert.ok(parsedPartial.skipped.length > 0);
+  assert.ok(parsedPartial.refusedBehavior.includes("no deployments"));
+});
+
 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.15");
+  assert.equal(packageJson.version, "0.2.17");
   assert.equal(
     packageJson.description,
     "Evidence-first, read-only coding-agent skills and project adapter tooling.",
@@ -1678,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.15") {
-    failures.push("package.json version must be 0.2.15 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) {

package/work-ledger.md

@@ -10,8 +10,10 @@
 - First external project-owned adapter adoption completed for `/home/oneclickwebsitedesignfactory/tax-lien-platform` at candidate commit `c548b1a6cbb3455a70b89d0e301e22435bfccac9`.
 - The adopted adapter is `repo-map` only, docs/metadata-only, and contains no commands, runtime checks, build/test/package behavior, platform/deployment behavior, or secret-aware behavior.
 - The shared repository does not contain real adapter manifests; real project adapters remain owned by their project repositories.
-- Public npm package release `v0.2.15` exposes the dependency-free
+- Public npm package release `v0.2.16` exposes the dependency-free
   `coding-agent-skills` CLI under MIT license.
+- `v0.2.16` adds optional OpenClaw-compatible `--json` output and documented
+  exit-code semantics for every public CLI command.
 - `route-trace` is implemented as an audit-only static route tracing skill.
 - `env-audit` is implemented as an audit-only value-free environment variable name mapping
   skill.
@@ -28,14 +30,14 @@
 
 ## Last Completed Version
 
-`v0.2.15`
+`v0.2.16`
 
 ## Current Recommended Milestone
 
-The `deployment-preflight` public npm release is in progress under builder-mode approval.
-Continue the remaining read-only skill wave one release at a time unless a real safety,
-validation, publication, or authentication boundary appears. The next approved wave item is
-`cloudflare-preflight-skill`.
+The OpenClaw-compatible JSON output contract is the current release milestone. After
+`v0.2.16` is published and verified, continue the remaining read-only skill wave one
+release at a time unless a real safety, validation, publication, or authentication
+boundary appears. The next approved wave item remains `cloudflare-preflight-skill`.
 
 ## Allowed Next Actions
 
@@ -122,9 +124,20 @@ No autonomous maintainer-loop run has been recorded yet.
 - Implemented milestone: `deployment-preflight` audit-only static deployment readiness
   evidence skill and CLI command.
 - Required permission: `builder-mode-skill-implementation`
-- Validation result: pass pending final publication evidence
+- Validation result: passed; `v0.2.15` commit, tag, npm publication, registry smoke,
+  npm exec, and GitHub Release completed
+- Next recommended milestone: implement the OpenClaw-compatible JSON output and exit-code
+  contract before continuing to `cloudflare-preflight-skill`.
+
+### 2026-07-03T15:00:00Z
+
+- Latest tag observed: `v0.2.15`
+- Implemented milestone: OpenClaw-compatible optional `--json` output and documented
+  exit-code semantics for every public CLI command.
+- Required permission: `orchestrator-output-contract`
+- Validation result: pass pending final release validation matrix
 - Next recommended milestone: continue builder-mode wave with `cloudflare-preflight-skill`
-  after `v0.2.15` publication completes.
+  after `v0.2.16` publication completes.
 
 ### 2026-07-03T12:00:00Z