coding-agent-skills 0.2.14 → 0.2.16

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 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
+
+- `deployment-preflight` audit-only skill for static deployment readiness evidence
+  mapping before separately approved deployment work.
+- `coding-agent-skills deployment-preflight <project-root>` CLI command.
+- Dependency-free deployment preflight renderer for deployment config files, deployment
+  docs, package script keys without command values, platform indicators, static risk
+  indicators, adapter-limited scope, skipped paths, not-verified provider/runtime areas,
+  and safety refusals.
+- Synthetic deployment-preflight fixtures and release tests for generic static scans,
+  adapter-scoped scans, package script key detection, platform indicators, and
+  repo-map-only adapter skips.
+
+### Changed
+
+- Adapter schemas and validators now recognize `deployment-preflight` as an audit-only
+  skill while preserving the existing `0.2.3` adapter contract compatibility baseline.
+- Usage, release, safety, architecture, adapter, roadmap, ledger, and run-log docs now
+  describe the new static read-only deployment preflight command.
+
 ## [0.2.14] - 2026-07-03
 
 ### Added

package/README.md

@@ -12,12 +12,13 @@ The pilot pack contains:
 - `api-contract-audit`: audit-only static API contract surface mapping.
 - `migration-review`: audit-only static migration and schema evidence review.
 - `github-handoff`: audit-only local Git handoff evidence before separately approved GitHub work.
+- `deployment-preflight`: audit-only static deployment readiness evidence mapping.
 - `build-verify`: controlled local validation using existing project commands.
 - `git-preflight`: audit-only Git readiness inspection.
 - `runtime-truth`: audit-only runtime evidence collection.
 - `llm-drift-control`: audit-only claim reconciliation.
 
-It does not contain deployment, package installation, Git publication, runtime mutation, migration, privileged API, platform-specific, or project-specific skills.
+It does not contain deployment execution, package installation, Git publication, runtime mutation, migration application, privileged API, platform-specific deployment automation, or project-specific skills.
 
 Project-specific adapters will live in their owning repositories and may narrow, but never weaken, shared safety rules.
 
@@ -50,6 +51,10 @@ Every skill emits the evidence-pack contract. A command being attempted is never
 - Map static API contract surfaces with `coding-agent-skills api-contract-audit <project-root>`.
 - 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.
@@ -67,6 +72,8 @@ Every skill emits the evidence-pack contract. A command being attempted is never
   `node scripts/render-migration-review.mjs <project-root>`.
 - Render a local GitHub handoff report with
   `node scripts/render-github-handoff.mjs <project-root>`.
+- Render a static deployment preflight report with
+  `node scripts/render-deployment-preflight.mjs <project-root>`.
 - Review [adapter upgrade checks](docs/adapters/upgrades.md).
 - Run `node scripts/check-adapter-upgrade.mjs <before-project-root> <after-project-root>`
   for disposable project revisions.
@@ -88,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

@@ -1,6 +1,6 @@
 # Roadmap
 
-The public package now contains eleven approved shared skills. Builder-mode approval is
+The public package now contains twelve approved shared skills. Builder-mode approval is
 active for the remaining read-only skill wave in this repository; real-world project
 execution constraints remain unchanged.
 
@@ -40,6 +40,10 @@ execution constraints remain unchanged.
   and schema evidence review.
 - `v0.2.14`: audit-only `github-handoff` skill and CLI renderer for local Git handoff
   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
@@ -86,7 +90,8 @@ Next safe milestone options:
 | `api-contract-audit-skill` | General | Audit-only | Implemented in `v0.2.12` |
 | `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 | Builder-mode approved; next in wave |
+| `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": {
@@ -59,6 +175,12 @@ const commands = {
     usage: "coding-agent-skills github-handoff <project-root>",
     requiredArgs: 1,
   },
+  "deployment-preflight": {
+    script: "scripts/render-deployment-preflight.mjs",
+    args: ([projectRoot]) => [projectRoot],
+    usage: "coding-agent-skills deployment-preflight <project-root>",
+    requiredArgs: 1,
+  },
   "validate-adapters": {
     script: "scripts/validate-adapters.mjs",
     args: ([adapterRoot]) => [adapterRoot],
@@ -67,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]",
@@ -81,6 +226,7 @@ function usage(exitCode = 0) {
     "  api-contract-audit <project-root>",
     "  migration-review <project-root>",
     "  github-handoff <project-root>",
+    "  deployment-preflight <project-root>",
     "  validate-adapters <adapter-root>",
     "",
     "local wrapper for the published coding-agent-skills package",
@@ -90,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)) {
@@ -101,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,
@@ -108,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

@@ -138,6 +138,24 @@ tags at HEAD, remote names, and changed-file summaries. It never prints remote U
 reads tokens, creates pull requests, commits, pushes, tags, calls GitHub APIs, or mutates
 project files.
 
+## Adapter-Aware Deployment Preflight Consumption
+
+The shared pack can consume a validated project-owned adapter as bounded context for
+`deployment-preflight`:
+
+```bash
+node scripts/render-deployment-preflight.mjs <project-root>
+```
+
+The renderer validates the project declaration when present. If an adapter is present but
+does not enable `deployment-preflight`, it reports an adapter-limited skip instead of
+broadening scope. When enabled, it reads only adapter-declared safe paths, excludes `.env`,
+secret-bearing files, generated output, dependency paths, build output, runtime output,
+and oversized files, then reports deployment config files, deployment docs, package
+script keys, platform indicators, risk indicators, skipped paths, and not-verified
+provider/runtime behavior. It never deploys, calls provider APIs, installs packages,
+builds, tests, runs services, migrates, or mutates project files.
+
 ## What Adapters May Do
 
 - Add bounded relative read paths and ignored paths.
@@ -153,6 +171,9 @@ project files.
   files while relying on the shared reviewer to exclude secret-bearing paths.
 - Add github-handoff required evidence labels and ignored path labels while relying on the
   shared renderer to avoid remote URLs, tokens, and GitHub mutation.
+- Add deployment-preflight safe read paths for static deployment config, docs, and package
+  metadata while relying on the shared preflight renderer to exclude secret-bearing paths
+  and avoid deployment behavior.
 - Add command aliases that already satisfy the shared command policy.
 - Add status-only runtime commands and manager hints.
 - Require additional evidence or named approval for exceptional reads.

package/docs/adapters/project-installation.md

@@ -182,6 +182,20 @@ When enabled, it reports local Git metadata and changed-file summaries without p
 remote URLs, reading tokens, creating pull requests, committing, pushing, tagging, calling
 GitHub APIs, or changing project files.
 
+A project-owned adapter can also enable read-only `deployment-preflight` context:
+
+```bash
+node scripts/render-deployment-preflight.mjs <project-root>
+```
+
+The deployment preflight renderer validates the project declaration when present. If the
+adapter is present but does not enable `deployment-preflight`, it reports an
+adapter-limited skip. When enabled, it reads only adapter-declared safe paths and reports
+static deployment config files, deployment docs, package script keys, platform indicators,
+risk indicators, and not-verified provider/runtime behavior without deploying, calling
+provider APIs, installing packages, building, testing, running services, or reading
+secrets.
+
 ## Safety Boundary
 
 Project adapters are extension-only. They cannot remove denied operations, change an

package/docs/adapters/real-project-adoption.md

@@ -22,8 +22,8 @@ project repository is touched:
   `coding-agent.skills.json`.
 - The adapter need is bounded to existing pilot skills: `repo-map`, `route-trace`,
   `env-audit`, `secret-audit`, `api-contract-audit`, `migration-review`,
-  `github-handoff`, `build-verify`, `git-preflight`, `runtime-truth`, or
-  `llm-drift-control`.
+  `github-handoff`, `deployment-preflight`, `build-verify`, `git-preflight`,
+  `runtime-truth`, or `llm-drift-control`.
 - The adapter can narrow context with relative paths, documentation precedence, safe
   aliases, status-only hints, or extra evidence requirements.
 - The adapter does not require deployment, migration, package installation, Git

package/docs/architecture/README.md

@@ -18,6 +18,7 @@ Audit-only:
 - `api-contract-audit`
 - `migration-review`
 - `github-handoff`
+- `deployment-preflight`
 - `git-preflight`
 - `runtime-truth`
 - `llm-drift-control`
@@ -26,6 +27,6 @@ Controlled local validation:
 
 - `build-verify`
 
-The evidence pack is a shared output contract, not an executable skill. Deployment
-preflight, provider operations, and additional project adapters remain separate future
+The evidence pack is a shared output contract, not an executable skill. Provider
+operations, deployment execution, and additional project adapters remain separate future
 work.

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`,
-    or `coding-agent-skills github-handoff`
+    `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.