coding-agent-skills 0.2.14 → 0.2.16

package/docs/release/npm-package.md

@@ -7,7 +7,7 @@ safety model.
 ## Current Package Shape
 
 - Package name: `coding-agent-skills`.
-- Package version: `0.2.14`.
+- Package version: `0.2.16`.
 - CLI bin: `coding-agent-skills` mapped to `bin/coding-agent-skills`.
 - Module type: `module`.
 - Dependencies: none.
@@ -33,9 +33,22 @@ coding-agent-skills secret-audit /path/to/project
 coding-agent-skills api-contract-audit /path/to/project
 coding-agent-skills migration-review /path/to/project
 coding-agent-skills github-handoff /path/to/project
+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
@@ -60,6 +73,10 @@ secrets.
 `github-handoff` is local Git metadata only; it reports branch state, HEAD, tags at HEAD,
 remote names, and changed-file summaries without printing remote URLs, reading tokens,
 creating pull requests, committing, pushing, tagging, or calling GitHub APIs.
+`deployment-preflight` is static and audit-only; it reports 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, or reading secrets.
 
 `coding-agent-skills validate-pack` is package-aware. In a source checkout, it keeps
 source-only checks such as `.gitignore` validation. In an installed package tree, where
@@ -95,7 +112,7 @@ included.
 The public CLI remains read-only for target projects unless a specific underlying skill
 already permits a bounded local validation action. The installed `repo-map`,
 `route-trace`, `env-audit`, `secret-audit`, `api-contract-audit`, `migration-review`,
-`github-handoff`, and adapter flows do not:
+`github-handoff`, `deployment-preflight`, and adapter flows do not:
 
 - deploy
 - run migrations
@@ -107,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/safety/README.md

@@ -2,7 +2,7 @@
 
 ## Audit-Only Rule
 
-`repo-map`, `route-trace`, `env-audit`, `secret-audit`, `api-contract-audit`, `migration-review`, `github-handoff`, `git-preflight`, `runtime-truth`, and `llm-drift-control` must not alter project files, Git state, dependencies, processes, services, databases, remote systems, or deployment state.
+`repo-map`, `route-trace`, `env-audit`, `secret-audit`, `api-contract-audit`, `migration-review`, `github-handoff`, `deployment-preflight`, `git-preflight`, `runtime-truth`, and `llm-drift-control` must not alter project files, Git state, dependencies, processes, services, databases, remote systems, or deployment state.
 
 `route-trace` is static only. It may read bounded non-secret route files and route
 configuration, but it must not execute app code, run servers, hit URLs, claim runtime
@@ -32,6 +32,11 @@ HEAD, remote names, and changed-file status, but it must not print remote URLs,
 tokens, create pull requests, commit, push, tag, call GitHub APIs, mutate Git state, or
 broaden adapter scope.
 
+`deployment-preflight` is static only. It may read bounded non-secret deployment config,
+docs, and package metadata, but it must not deploy, run provider CLIs, call cloud APIs,
+install packages, build, test, run services, migrate databases, read secret files, or
+broaden adapter scope.
+
 `build-verify` may run existing project-native validation commands. Build or test tools may create their normal local artifacts, but the skill must declare observed changes and must reject installation, fix modes, snapshot updates, deployment, migration, or unknown scripts.
 
 ## Restricted Categories

package/docs/testing/README.md

@@ -75,6 +75,14 @@ summary, adapter-declared evidence metadata, and adapter-present-but-not-enabled
 Tests must never commit to the shared repository, push, tag shared history, create pull
 requests, call GitHub APIs, print remote URLs, read tokens, or read `.env` files.
 
+## Deployment Preflight
+
+Synthetic deployment-preflight projects cover deployment config detection, deployment docs,
+package script keys without command values, static platform indicators, risk indicators,
+adapter-declared scope, and adapter-present-but-not-enabled behavior. Tests must never
+deploy, call provider APIs, install packages, build, test, run services, migrate, or read
+`.env` files.
+
 ## Privacy And Redaction
 
 Sensitive shapes are stored as ordered synthetic parts and reconstructed only in memory. Tests verify type detection, redaction, and absence from reusable skill content without printing fixture values.
@@ -118,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

@@ -11,6 +11,7 @@ Select the least-privileged skill that matches the request:
 | Map static API contract surfaces | `api-contract-audit` |
 | Review static migration and schema evidence | `migration-review` |
 | Prepare local GitHub handoff evidence | `github-handoff` |
+| Map static deployment readiness evidence | `deployment-preflight` |
 | Run existing local validation checks | `build-verify` |
 | Assess Git handoff readiness | `git-preflight` |
 | Determine what is actually running | `runtime-truth` |
@@ -30,11 +31,13 @@ Select the least-privileged skill that matches the request:
    and static risk-indicator evidence must be mapped without database access.
 7. Use `github-handoff` when local Git metadata and changed-file summaries are needed
    before separately approved GitHub work.
-8. Perform implementation outside this pilot pack.
-9. Use `build-verify` for approved project-native checks.
-10. Use `git-preflight` before handoff or publication.
-11. Use `runtime-truth` only when live local state matters.
-12. Use `llm-drift-control` when claims and evidence may disagree.
+8. Use `deployment-preflight` when visible deployment config, docs, package script keys,
+   and platform hints must be mapped without deployment behavior.
+9. Perform implementation outside this pilot pack.
+10. Use `build-verify` for approved project-native checks.
+11. Use `git-preflight` before handoff or publication.
+12. Use `runtime-truth` only when live local state matters.
+13. Use `llm-drift-control` when claims and evidence may disagree.
 
 Every skill emits an evidence pack. Read `status`, skipped checks, failures, confidence, and changed state before relying on a completion claim.
 
@@ -71,6 +74,7 @@ coding-agent-skills secret-audit /path/to/project
 coding-agent-skills api-contract-audit /path/to/project
 coding-agent-skills migration-review /path/to/project
 coding-agent-skills github-handoff /path/to/project
+coding-agent-skills deployment-preflight /path/to/project
 coding-agent-skills validate-adapters /path/to/adapter-root
 ```
 
@@ -104,11 +108,59 @@ database access or migration execution.
 state, HEAD, tags at HEAD, remote names, and changed-file summaries without printing
 remote URLs, committing, pushing, tagging, creating pull requests, calling GitHub APIs,
 or reading tokens.
+`deployment-preflight` validates a project adapter when present, uses adapter-declared
+safe paths when enabled, and statically reports deployment config files, deployment docs,
+package script keys, platform indicators, risk indicators, skipped paths, and
+not-verified provider/runtime behavior without deploying or calling provider APIs.
 
 The installed CLI does not run target project builds or tests, perform runtime checks,
 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:
@@ -123,6 +175,7 @@ bin/coding-agent-skills secret-audit /path/to/project
 bin/coding-agent-skills api-contract-audit /path/to/project
 bin/coding-agent-skills migration-review /path/to/project
 bin/coding-agent-skills github-handoff /path/to/project
+bin/coding-agent-skills deployment-preflight /path/to/project
 bin/coding-agent-skills validate-adapters /path/to/adapter-root
 ```
 
@@ -139,6 +192,7 @@ coding-agent-skills secret-audit /path/to/project
 coding-agent-skills api-contract-audit /path/to/project
 coding-agent-skills migration-review /path/to/project
 coding-agent-skills github-handoff /path/to/project
+coding-agent-skills deployment-preflight /path/to/project
 coding-agent-skills validate-adapters /path/to/adapter-root
 ```
 

package/examples/command-policies/deployment-preflight.json

@@ -0,0 +1,70 @@
+{
+  "version": "0.2.3",
+  "mode": "audit-only",
+  "parserPolicy": {
+    "inspectEverySegment": true,
+    "inspectScriptBodies": true,
+    "rejectUnknownExecutables": true,
+    "rejectShellWrappers": true,
+    "rejectHeredocs": true,
+    "rejectRedirection": true,
+    "providerSpecificNpx": true,
+    "authenticatedCurlRequiresApproval": true,
+    "boundedReadsRequired": true,
+    "allowedComposition": "read-only"
+  },
+  "allowedFamilies": [
+    {
+      "name": "bounded-deployment-preflight-inspection",
+      "executables": ["pwd", "ls", "rg", "find", "sed", "head"],
+      "argumentPolicy": {
+        "strategy": "pattern",
+        "allowedPatterns": ["bounded repository-local static deployment config, docs, and package metadata inspection"],
+        "deniedPatterns": ["deployments, provider APIs, package installs, builds, tests, runtime checks, secret files, and unbounded traversal"]
+      },
+      "constraints": [
+        "Remain inside the declared project scope.",
+        "Bound traversal depth and output.",
+        "Exclude .env, secret-bearing, generated, dependency, build, and runtime-output paths."
+      ]
+    },
+    {
+      "name": "git-identity-inspection",
+      "executables": ["git"],
+      "argumentPolicy": {
+        "strategy": "exact",
+        "allowedPatterns": ["rev-parse and status --short --branch"],
+        "deniedPatterns": ["all Git mutation and publication subcommands"]
+      },
+      "constraints": ["Allow only read-only repository identity and branch-state inspection."]
+    },
+    {
+      "name": "deployment-preflight-renderer",
+      "executables": ["node", "coding-agent-skills"],
+      "argumentPolicy": {
+        "strategy": "exact",
+        "allowedPatterns": ["node scripts/render-deployment-preflight.mjs <project-root>; coding-agent-skills deployment-preflight <project-root>"],
+        "deniedPatterns": ["deployments, provider APIs, package installs, builds, tests, runtime checks, migrations, service mutation, and secret-file reads"]
+      },
+      "constraints": [
+        "The renderer must remain static and read-only.",
+        "Do not run provider CLIs, deploy, build, test, or inspect secrets."
+      ]
+    }
+  ],
+  "restrictedCategories": [
+    "file-write",
+    "package-install",
+    "deployment",
+    "git-mutation",
+    "unrestricted-scan",
+    "secret-read",
+    "process-mutation",
+    "service-mutation",
+    "migration-apply",
+    "privileged-api"
+  ],
+  "approvalExceptions": [
+    "A named-file approval may permit one otherwise excluded non-mutating static read when the file is not secret-bearing."
+  ]
+}

package/examples/evidence-packs/deployment-preflight.json

@@ -0,0 +1,60 @@
+{
+  "contractVersion": "1.0.0",
+  "skill": {"name": "deployment-preflight", "version": "0.2.3"},
+  "invocation": {
+    "id": "example-deployment-preflight",
+    "startedAt": "2026-07-03T12:00:00Z",
+    "endedAt": "2026-07-03T12:01:00Z"
+  },
+  "repository": {
+    "root": "/workspace/example-project",
+    "branch": "main",
+    "head": "0123456789abcdef",
+    "workingTreeState": "clean"
+  },
+  "userIntent": "Map static deployment readiness evidence before deployment planning.",
+  "declaredScope": ["/workspace/example-project"],
+  "projectAdapter": "example-deployment-preflight-adapter",
+  "environmentSummary": {"platform": "linux", "shell": "bash"},
+  "status": "complete",
+  "confidence": {
+    "level": "medium",
+    "reason": "Static deployment evidence was inspected, but provider credentials and deployed state were not verified."
+  },
+  "commands": [
+    {
+      "command": "coding-agent-skills deployment-preflight /workspace/example-project",
+      "family": "deployment-preflight-renderer",
+      "workingDirectory": "/workspace/example-project",
+      "startedAt": "2026-07-03T12:00:20Z",
+      "endedAt": "2026-07-03T12:00:21Z",
+      "exitStatus": 0,
+      "resultStatus": "success",
+      "safetyClass": "allowed",
+      "approvalReference": null,
+      "purpose": "Render a static deployment preflight report.",
+      "outputSummary": "Reported static deployment config files, docs, platform indicators, risk indicators, skipped items, and not-verified provider areas."
+    }
+  ],
+  "skippedChecks": [],
+  "findings": [
+    {
+      "summary": "Static deployment evidence was mapped without deployment behavior.",
+      "evidence": ["wrangler.toml", "docs/deployment.md"]
+    }
+  ],
+  "risks": [
+    {
+      "summary": "Provider and deployed service state may differ from static repository evidence.",
+      "evidence": ["provider APIs were not called", "runtime health checks were not performed"]
+    }
+  ],
+  "failures": [],
+  "unresolvedQuestions": [],
+  "changedState": {
+    "changed": false,
+    "summary": "No project, Git, dependency, runtime, service, database, cloud provider, remote, deployment, or generated-output state changed."
+  },
+  "handoffSummary": "Static deployment evidence is mapped; deployment execution and provider state remain unverified.",
+  "recommendedNextAction": "Review reported deployment surfaces before separately approving any platform-specific deployment work."
+}

package/examples/manifests/deployment-preflight.json

@@ -0,0 +1,14 @@
+{
+  "name": "deployment-preflight",
+  "version": "0.2.3",
+  "mode": "audit-only",
+  "evidenceContract": "../../contracts/evidence-pack/evidence-pack.schema.json",
+  "commandPolicy": "../command-policies/deployment-preflight.json",
+  "adapterSchema": "../../schemas/project-adapter.schema.json",
+  "adapterCompatibility": {
+    "contractVersion": "1.0.0",
+    "compatibleAdapterVersions": ["1.0.0"]
+  },
+  "adapterInterface": "../../skills/deployment-preflight/adapter-interface.md",
+  "description": "Map static deployment readiness evidence without deployment behavior."
+}

package/examples/workflows/deployment-preflight.md

@@ -0,0 +1,8 @@
+# Deployment Preflight Workflow
+
+```bash
+coding-agent-skills deployment-preflight /workspace/project
+```
+
+Use the output as static deployment orientation only. It does not deploy, call provider APIs,
+install packages, run builds, run tests, start services, run migrations, or read secrets.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coding-agent-skills",
-  "version": "0.2.14",
+  "version": "0.2.16",
   "description": "Evidence-first, read-only coding-agent skills and project adapter tooling.",
   "type": "module",
   "private": false,
@@ -15,6 +15,7 @@
     "api-contract-audit",
     "migration-review",
     "github-handoff",
+    "deployment-preflight",
     "project-adapters",
     "code-validation",
     "cli"

package/runs/skill-runs.md

@@ -258,6 +258,42 @@ This file records bounded maintainer-loop runs. Entries must not contain secrets
 - Safety boundary: read-only local Git metadata only, no `.env` reads, no token reads, no
   remote URL printing, no commits, no pushes, no tags, no pull request creation, no GitHub
   API calls, 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.14` was committed, pushed, tagged, published to npm, smoke-tested
+  from the registry, and released on GitHub.
+- Commit/tag/push status: complete.
+
+## implementation-v0.2.15-deployment-preflight
+
+- Run ID: `implementation-v0.2.15-deployment-preflight`
+- Repository: `/home/oneclickwebsitedesignfactory/coding-agent-skills`
+- Command used: `builder-mode approval for deployment-preflight-skill implementation and release`
+- Files changed: `deployment-preflight` skill, deployment preflight renderer and library,
+  CLI wrapper, adapter schemas, pack rules, release tests, synthetic deployment fixtures,
+  usage/release/safety/adapter docs, changelog, roadmap, work ledger, run log, and package
+  metadata.
+- Safety boundary: read-only static deployment evidence only, no `.env` reads, no provider
+  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/schemas/project-adapter-installation.schema.json

@@ -71,6 +71,7 @@
           "api-contract-audit",
           "migration-review",
           "github-handoff",
+          "deployment-preflight",
           "build-verify",
           "git-preflight",
           "runtime-truth",
@@ -109,6 +110,7 @@
               "api-contract-audit",
               "migration-review",
               "github-handoff",
+              "deployment-preflight",
               "build-verify",
               "git-preflight",
                 "runtime-truth",

package/schemas/project-adapter.schema.json

@@ -95,6 +95,7 @@
               "api-contract-audit",
               "migration-review",
               "github-handoff",
+              "deployment-preflight",
               "build-verify",
               "git-preflight",
               "runtime-truth",
@@ -177,6 +178,7 @@
                   "api-contract-audit",
                   "migration-review",
                   "github-handoff",
+                  "deployment-preflight",
                   "build-verify",
                   "git-preflight",
                   "runtime-truth",