coding-agent-skills 0.2.15 → 0.2.16

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes follow [Semantic Versioning](docs/versioning/README.md).
 
+## [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,6 +52,9 @@ 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.
@@ -92,6 +95,29 @@ 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.
+
 ## 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 adapter-declared repo boundaries",
+      reason: "Use the reported docs, safe paths, ignored paths, 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/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.16`.
 - 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

@@ -117,6 +117,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.16",
   "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/test-pack.mjs

@@ -221,6 +221,39 @@ function snapshotAbsoluteDirectory(directory) {
   return digest.digest("hex");
 }
 
+function assertOpenClawJsonContract(value, command, packageVersion = "0.2.16") {
+  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");
@@ -394,10 +427,68 @@ 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")],
+    ["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.16");
   assert.equal(
     packageJson.description,
     "Evidence-first, read-only coding-agent skills and project adapter tooling.",

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.16") {
+    failures.push("package.json version must be 0.2.16 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