coding-agent-skills 0.2.11 → 0.2.12

package/scripts/test-pack.mjs

@@ -57,6 +57,11 @@ import {
   renderSecretAuditReport,
   secretAuditCliResult,
 } from "./lib/secret-audit.mjs";
+import {
+  apiContractAuditCliResult,
+  buildApiContractAuditReport,
+  renderApiContractAuditReport,
+} from "./lib/api-contract-audit.mjs";
 import {
   adapterUpgradeCliResult,
   checkAdapterUpgrade,
@@ -274,6 +279,7 @@ test("local CLI maps approved commands to existing safe scripts", () => {
   assert.ok(cliText.includes("scripts/render-route-trace.mjs"));
   assert.ok(cliText.includes("scripts/render-env-audit.mjs"));
   assert.ok(cliText.includes("scripts/render-secret-audit.mjs"));
+  assert.ok(cliText.includes("scripts/render-api-contract-audit.mjs"));
   assert.ok(cliText.includes("scripts/validate-adapters.mjs"));
   assert.ok(!cliText.includes(".env"));
 
@@ -307,6 +313,10 @@ test("local CLI maps approved commands to existing safe scripts", () => {
       ["secret-audit", path.join(fixtureRoot, "secret-audit", "static-project")],
       /# Secret Audit Report/,
     ],
+    [
+      ["api-contract-audit", path.join(fixtureRoot, "api-contract-audit", "static-project")],
+      /# API Contract Audit Report/,
+    ],
   ];
 
   for (const [args, expected] of commands) {
@@ -331,7 +341,7 @@ test("local CLI maps approved commands to existing safe scripts", () => {
 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.11");
+  assert.equal(packageJson.version, "0.2.12");
   assert.equal(
     packageJson.description,
     "Evidence-first, read-only coding-agent skills and project adapter tooling.",
@@ -346,6 +356,7 @@ test("npm package metadata is public-ready and dependency-free", () => {
     "route-trace",
     "env-audit",
     "secret-audit",
+    "api-contract-audit",
     "project-adapters",
     "code-validation",
     "cli",
@@ -589,6 +600,56 @@ test("secret-audit does not broaden a repo-map-only project adapter", () => {
   assert.match(renderSecretAuditReport(result), /secret-audit is not enabled/);
 });
 
+test("api-contract-audit maps static contract surfaces without runtime behavior", () => {
+  const result = buildApiContractAuditReport(
+    path.join(root, "tests", "fixtures", "api-contract-audit", "static-project"),
+    { coreRoot: root },
+  );
+
+  assert.equal(result.status, "complete");
+  assert.ok(result.contractFiles.some((record) => record.path === "docs/openapi.yaml"));
+  assert.ok(
+    result.endpointDeclarations.some(
+      (record) => record.route === "/api/users" && record.method === "GET",
+    ),
+  );
+  assert.ok(result.clientCalls.some((record) => record.target === "/api/users"));
+  assert.ok(result.schemaFiles.some((record) => record.path === "schemas/user.schema.ts"));
+  assert.match(renderApiContractAuditReport(result), /No target project build/);
+});
+
+test("api-contract-audit respects adapter-declared scope", () => {
+  const result = buildApiContractAuditReport(
+    path.join(root, "tests", "fixtures", "api-contract-audit", "adapter-project"),
+    { coreRoot: root },
+  );
+
+  assert.equal(result.status, "complete");
+  assert.equal(result.adapter.enabled, true);
+  assert.deepEqual(result.scopePaths, ["src"]);
+  assert.deepEqual(result.filesScanned, ["src/routes.ts"]);
+  assert.ok(result.endpointDeclarations.some((record) => record.route === "/api/adapter-items"));
+  assert.ok(result.warnings.includes("api-contract-audit used adapter-declared safe read paths only"));
+  const cli = apiContractAuditCliResult(
+    path.join(root, "tests", "fixtures", "api-contract-audit", "adapter-project"),
+    { coreRoot: root },
+  );
+  assert.equal(cli.exitCode, 0);
+  assert.match(cli.lines.join("\n"), /API-contract-audit enabled: yes/);
+});
+
+test("api-contract-audit does not broaden a repo-map-only project adapter", () => {
+  const result = buildApiContractAuditReport(
+    path.join(root, "tests", "fixtures", "project-adapter-installation", "valid-exact-pin"),
+    { coreRoot: root },
+  );
+
+  assert.equal(result.status, "partial");
+  assert.equal(result.filesScanned.length, 0);
+  assert.equal(result.endpointDeclarations.length, 0);
+  assert.match(renderApiContractAuditReport(result), /api-contract-audit is not enabled/);
+});
+
 test("validate-pack accepts installed package trees without source-only gitignore", () => {
   const temporaryRoot = fs.mkdtempSync(path.join(os.tmpdir(), "installed-package-"));
   const installedRoot = path.join(temporaryRoot, "coding-agent-skills");

package/scripts/validate-pack.mjs

@@ -98,6 +98,7 @@ const requiredRootFiles = [
   "scripts/render-route-trace.mjs",
   "scripts/render-env-audit.mjs",
   "scripts/render-secret-audit.mjs",
+  "scripts/render-api-contract-audit.mjs",
   "scripts/check-adapter-upgrade.mjs",
   "scripts/check-adapter-upgrade-chain.mjs",
   "scripts/validate-adapters.mjs",
@@ -106,6 +107,7 @@ const requiredRootFiles = [
   "scripts/lib/route-trace.mjs",
   "scripts/lib/env-audit.mjs",
   "scripts/lib/secret-audit.mjs",
+  "scripts/lib/api-contract-audit.mjs",
   "scripts/lib/adapter-upgrade.mjs",
   "scripts/lib/adapter-upgrade-chain.mjs",
   "scripts/lib/adapter-discovery.mjs",
@@ -679,8 +681,8 @@ if (packageJson) {
   if (packageJson.name !== "coding-agent-skills") {
     failures.push("package.json has unexpected package name");
   }
-  if (packageJson.version !== "0.2.11") {
-    failures.push("package.json version must be 0.2.11 for public package validation");
+  if (packageJson.version !== "0.2.12") {
+    failures.push("package.json version must be 0.2.12 for public package validation");
   }
   if (packageJson.type !== "module") failures.push("package.json must preserve ESM mode");
   if (packageJson.private !== false) {
@@ -701,6 +703,7 @@ if (packageJson) {
       "route-trace",
       "env-audit",
       "secret-audit",
+      "api-contract-audit",
       "project-adapters",
       "code-validation",
       "cli",

package/skills/api-contract-audit/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: api-contract-audit
+description: Audit statically visible API contract surfaces without running servers, calling APIs, generating schemas, or modifying projects. Use when Codex must map OpenAPI or Swagger files, route handler declarations, client request patterns, and schema/type files before API work or handoff; do not use for runtime verification, network probing, code generation, builds, tests, deployments, migrations, or secret-file reads.
+---
+
+# API Contract Audit
+
+Map statically visible API contract evidence and report what is and is not verified. Remain audit-only and avoid turning contract discovery into runtime validation.
+
+This skill must not change project files, Git state, dependencies, runtime state, services,
+databases, remotes, generated clients, schemas, or deployment state.
+
+## Purpose And Use
+
+Use this skill before API work, integration handoff, or contract review when the agent needs
+to understand visible API contracts from source, docs, route handlers, client calls, and
+schema/type files.
+
+Do not use it to prove deployed behavior, call endpoints, generate clients, generate
+schemas, run validators, build, test, migrate, deploy, inspect databases, or read secrets.
+
+## Inputs
+
+Require a project root or starting path. Optionally accept a project adapter, intended scan
+area, documentation precedence, contract-file hints, or known static API boundaries.
+
+Do not assume a missing contract file means no API exists, static route declarations match
+runtime behavior, client calls cover all server routes, generated clients are current, or a
+project adapter enables this skill unless validation proves it.
+
+## Procedure
+
+1. Record user intent, project root, declared scope, adapter state, and safety boundary.
+2. Validate a project adapter when present before reading adapter-declared metadata.
+3. If an adapter is present but does not enable `api-contract-audit`, stop static file
+   reading and report the adapter-limited skip.
+4. Build scan scope from adapter safe read paths when available; otherwise use a bounded
+   generic static scan.
+5. Exclude `.env`, secret-bearing files, generated output, dependency paths, and oversized
+   files before reading.
+6. Identify statically visible OpenAPI/Swagger or API contract files.
+7. Identify route handler declarations and contract path/method declarations from static text.
+8. Identify client request call patterns and schema/type files.
+9. Report skipped items, not-verified runtime surfaces, warnings, and safety refusals.
+10. Emit the shared evidence pack or API contract audit report before claiming completion.
+
+Use [checklist.md](checklist.md). Consult [failure-modes.md](failure-modes.md),
+[adapter-interface.md](adapter-interface.md), and [examples.md](examples.md). Format findings
+with [evidence-template.md](evidence-template.md).
+
+## Evidence, Recovery, And Dependencies
+
+Emit repository identity, adapter state, scan scope, ignored paths, files scanned, contract
+files, endpoint declarations, client-call patterns, schema/type files, skipped items,
+not-verified areas, warnings, and changed-state declaration through the shared evidence-pack
+contract.
+
+Recover from missing specs, ambiguous route declarations, unreadable files, or adapter
+limits by reporting uncertainty. Never recover by running a server, calling an endpoint,
+generating a client, generating schemas, installing dependencies, building, testing,
+deploying, migrating, broadening adapter scope, or reading `.env`.
+
+This skill depends on the evidence-pack contract and may consume validated project adapters.
+Adapters may add safe paths, ignored paths, documentation precedence, and evidence
+requirements, but cannot weaken policy or turn this skill into runtime or generation work.
+
+## Approval Boundary
+
+Explicit approval may permit one named non-secret static file read outside normal source
+paths. Approval does not permit `.env` or secret-file reads, URL probes, API calls, schema
+generation, client generation, package installation, builds, tests, runtime checks,
+deployments, migrations, Git mutation, or project writes.
+
+## Completion
+
+Claim `complete` only when the declared static scan scope was inspected, visible contract
+surfaces are reported, skipped and not-verified areas are explicit, adapter limitations are
+clear, and no project, Git, dependency, runtime, service, remote, generated-code, or
+deployment state changed.
+
+Report `partial`, `failed`, or `blocked` when adapter scope prevents scanning, requested
+evidence requires runtime or network behavior, the project root cannot be established, or
+safety exclusions prevent the requested conclusion.
+
+These conditions are both the acceptance criteria and definition of done.

package/skills/api-contract-audit/adapter-interface.md

@@ -0,0 +1,16 @@
+Adapters may enable `api-contract-audit` only as an audit-only static inspection skill.
+
+Allowed adapter extensions:
+
+- `safeReadPaths` for source, docs, contract, schema, and client files.
+- `ignoredPaths` for generated, dependency, build, coverage, and output directories.
+- `documentationPrecedence` for API docs or contract references.
+- `requiredEvidence` for contract files, route declarations, client calls, schemas, and not-verified areas.
+
+Adapters must not:
+
+- Add commands for `api-contract-audit`.
+- Require runtime servers, URL probes, API calls, schema generation, or client generation.
+- Include `.env`, credential, or secret-bearing paths.
+- Change `api-contract-audit` from `audit-only` to action-capable.
+- Expand scope outside the declared project root without named approval.

package/skills/api-contract-audit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "API Contract Audit"
+  short_description: "Map static API contract surfaces without runtime calls"
+  default_prompt: "Audit static API contract surfaces in this repository without changing project state. Do not run servers, call APIs, generate clients or schemas, read .env files, or run builds/tests."

package/skills/api-contract-audit/checklist.md

@@ -0,0 +1,7 @@
+- Confirm the project root and declared static scope.
+- Validate any project adapter before reading adapter metadata.
+- Stop with `partial` if an adapter is present but does not enable `api-contract-audit`.
+- Exclude `.env`, secret-bearing, dependency, generated, output, and oversized files.
+- Report contract files, endpoint declarations, client calls, and schema/type files.
+- Record not-verified runtime, deployment, database, auth, and semantic equivalence gaps.
+- Declare that no build, test, runtime, URL probe, API call, generation, deployment, migration, package install, secret read, or write occurred.

package/skills/api-contract-audit/evidence-template.md

@@ -0,0 +1,13 @@
+- Skill: `api-contract-audit`
+- Status: `complete`, `partial`, `failed`, or `blocked`
+- Project root and branch state
+- Adapter present/enabled state
+- Scope paths and ignored paths
+- Files scanned
+- Contract files found
+- Endpoint declarations found
+- Client-call patterns found
+- Schema/type files found
+- Skipped items and reasons
+- Not-verified runtime, deployment, database, auth, generation, and semantic-equivalence gaps
+- Changed-state declaration: no project, Git, dependency, runtime, service, remote, generated-code, or deployment state changed

package/skills/api-contract-audit/examples.md

@@ -0,0 +1,20 @@
+Safe examples:
+
+```bash
+coding-agent-skills api-contract-audit /workspace/app
+```
+
+```bash
+node scripts/render-api-contract-audit.mjs tests/fixtures/api-contract-audit/static-project
+```
+
+Expected result: a report listing static contract files, endpoint declarations, client call
+patterns, schema/type files, skipped paths, not-verified runtime behavior, and refused
+actions.
+
+## Unsafe Examples
+
+- Start the API server to verify contract behavior.
+- Call `/api/*` endpoints or remote URLs.
+- Generate an OpenAPI spec or client.
+- Read `.env`, credentials, service keys, or private runtime config.

package/skills/api-contract-audit/failure-modes.md

@@ -0,0 +1,5 @@
+- Adapter present but missing `api-contract-audit`: report `partial` and read no target files.
+- No contract file found: report the absence as static evidence, not proof that no API exists.
+- Route declarations are dynamic: record not-verified runtime behavior.
+- Client calls use variables or generated clients: report the limitation without executing code.
+- Requested proof requires runtime, network, database, generation, build, test, or secret access: stop or report blocked.

package/tests/fixtures/api-contract-audit/adapter-project/.coding-agent/adapters/api-contract-audit-fixture/adapter.json

@@ -0,0 +1,53 @@
+{
+  "adapterId": "api-contract-audit-fixture",
+  "adapterVersion": "1.0.0",
+  "project": {
+    "id": "api-contract-audit-fixture",
+    "detection": {
+      "rootMarkers": [{"kind": "file", "path": "package.json"}],
+      "maximumDepth": 1,
+      "scope": "declared-project-root",
+      "requireApprovalOutsideScope": true
+    }
+  },
+  "supportedSkills": [
+    {
+      "id": "api-contract-audit",
+      "compatibleVersions": ["0.2.3", "0.2.x"],
+      "declaredMode": "audit-only"
+    }
+  ],
+  "extensions": {
+    "safeReadPaths": ["src"],
+    "ignoredPaths": ["dist", "build"],
+    "documentationPrecedence": ["README.md"],
+    "commandAliases": [],
+    "safeStatusCommands": [],
+    "requiredEvidence": ["project root", "adapter scope", "contract surfaces", "not-verified runtime areas"],
+    "expectedRuntimeManagers": [],
+    "expectedPackageManagers": ["npm"]
+  },
+  "approvalRequirements": [],
+  "inheritance": {
+    "sharedRestrictions": "required",
+    "deniedOperationCategories": [
+      "file-write",
+      "package-install",
+      "deployment",
+      "git-mutation",
+      "unrestricted-scan",
+      "secret-read",
+      "process-mutation",
+      "service-mutation",
+      "migration-apply",
+      "privileged-api"
+    ],
+    "allowRestrictionRemoval": false,
+    "allowModeOverride": false,
+    "allowFailureSuppression": false,
+    "allowCompletionOverride": false,
+    "allowSecretExposure": false,
+    "allowRequiredEvidenceRemoval": false,
+    "allowScopeExpansionWithoutApproval": false
+  }
+}

package/tests/fixtures/api-contract-audit/adapter-project/.coding-agent/skills.json

@@ -0,0 +1,23 @@
+{
+  "declarationVersion": "1.0.0",
+  "projectId": "api-contract-audit-fixture",
+  "adapterRoot": ".coding-agent/adapters",
+  "adapterSchemaVersion": "1.0.0",
+  "core": {
+    "id": "coding-agent-skills",
+    "expectedVersion": "0.2.3",
+    "versionPin": ">=0.2.2 <0.3.0"
+  },
+  "compatibleSkillIds": ["api-contract-audit"],
+  "adapters": [
+    {
+      "id": "api-contract-audit-fixture",
+      "version": "1.0.0",
+      "skillIds": ["api-contract-audit"]
+    }
+  ],
+  "validationCommand": "node <shared-core>/scripts/validate-project-adapters.mjs <project-root>",
+  "evidenceOutput": ".coding-agent/evidence",
+  "approvalPolicyReference": ".coding-agent/approval-policy.md",
+  "noSecrets": true
+}

package/tests/fixtures/api-contract-audit/adapter-project/README.md

@@ -0,0 +1,3 @@
+# API Contract Audit Adapter Fixture
+
+Synthetic adapter-scoped fixture.

package/tests/fixtures/api-contract-audit/adapter-project/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "api-contract-audit-adapter-fixture",
+  "type": "module"
+}

package/tests/fixtures/api-contract-audit/adapter-project/src/routes.ts

@@ -0,0 +1 @@
+router.get("/api/adapter-items", () => {});

package/tests/fixtures/api-contract-audit/static-project/README.md

@@ -0,0 +1,3 @@
+# API Contract Audit Static Fixture
+
+Synthetic fixture for static API contract discovery.

package/tests/fixtures/api-contract-audit/static-project/app/api/users/route.ts

@@ -0,0 +1,7 @@
+export async function GET() {
+  return Response.json([]);
+}
+
+export async function POST() {
+  return Response.json({ok: true});
+}

package/tests/fixtures/api-contract-audit/static-project/docs/openapi.yaml

@@ -0,0 +1,10 @@
+openapi: 3.1.0
+info:
+  title: Fixture API
+  version: 1.0.0
+paths:
+  /api/users:
+    get:
+      summary: List users
+    post:
+      summary: Create user

package/tests/fixtures/api-contract-audit/static-project/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "api-contract-audit-static-fixture",
+  "type": "module"
+}

package/tests/fixtures/api-contract-audit/static-project/schemas/user.schema.ts

@@ -0,0 +1,4 @@
+export interface UserDto {
+  id: string;
+  email: string;
+}

package/tests/fixtures/api-contract-audit/static-project/src/client.ts

@@ -0,0 +1,3 @@
+export async function loadUsers() {
+  return fetch("/api/users");
+}

package/tests/fixtures/triggers/cases.json

@@ -55,6 +55,18 @@
       "expectedSkill": "secret-audit",
       "notSkills": ["repo-map", "build-verify"]
     },
+    {
+      "id": "api-contract-audit-openapi",
+      "prompt": "Audit the OpenAPI file, endpoint declarations, client calls, and API schema files without running the server.",
+      "expectedSkill": "api-contract-audit",
+      "notSkills": ["route-trace", "runtime-truth"]
+    },
+    {
+      "id": "api-contract-audit-drift",
+      "prompt": "Map possible API contract drift between static route handlers and client calls before handoff.",
+      "expectedSkill": "api-contract-audit",
+      "notSkills": ["build-verify", "llm-drift-control"]
+    },
     {
       "id": "build-after-implementation",
       "prompt": "The implementation is finished. Run the existing typecheck, tests, and build.",
@@ -107,7 +119,7 @@
       "id": "negative-deploy",
       "prompt": "Deploy this application to production.",
       "expectedSkill": null,
-      "notSkills": ["repo-map", "route-trace", "env-audit", "secret-audit", "build-verify", "git-preflight", "runtime-truth", "llm-drift-control"]
+      "notSkills": ["repo-map", "route-trace", "env-audit", "secret-audit", "api-contract-audit", "build-verify", "git-preflight", "runtime-truth", "llm-drift-control"]
     },
     {
       "id": "negative-install",

package/tests/trigger/README.md

@@ -8,6 +8,8 @@
   secret-value inspection.
 - Redacted high-confidence secret exposure detection must trigger `secret-audit`, not
   environment variable mapping or runtime truth.
+- Static API contract mapping must trigger `api-contract-audit`, not runtime truth or
+  build verification.
 - Local validation must trigger `build-verify` only when project-native checks are requested.
 - Git readiness must trigger `git-preflight`, not publication.
 - Process/listener/health questions must trigger `runtime-truth`, not restart behavior.

package/work-ledger.md

@@ -4,31 +4,33 @@
 
 - Repository: `coding-agent-skills`
 - Branch: `main`
-- Pilot skills: `repo-map`, `route-trace`, `env-audit`, `secret-audit`, `build-verify`, `git-preflight`, `runtime-truth`, `llm-drift-control`
+- Pilot skills: `repo-map`, `route-trace`, `env-audit`, `secret-audit`, `api-contract-audit`, `build-verify`, `git-preflight`, `runtime-truth`, `llm-drift-control`
 - Adapter discovery, project adapter installation, stale-pin detection, upgrade evidence, compatibility-chain validation, evidence-bundle verification, retention policy, provenance design, archive-report rendering, archive-index fixtures, retention-expiry advisory reporting, and detached-signature verification planning are implemented.
 - Real-project adapter adoption readiness is documented as a planning-only approval gate.
 - 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.11` exposes the dependency-free
+- Public npm package release `v0.2.12` exposes the dependency-free
   `coding-agent-skills` CLI under MIT license.
 - `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.
 - `secret-audit` is implemented as an audit-only redacted secret exposure detection skill.
+- `api-contract-audit` is implemented as an audit-only static API contract surface mapping
+  skill.
 - Builder-mode approval: complete the remaining read-only skill wave for
   `coding-agent-skills` itself. Real-world project execution constraints remain unchanged.
 
 ## Last Completed Version
 
-`v0.2.11`
+`v0.2.12`
 
 ## Current Recommended Milestone
 
-The `secret-audit` 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
-`api-contract-audit-skill`.
+The `api-contract-audit` 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
+`migration-review-skill`.
 
 ## Allowed Next Actions
 
@@ -100,6 +102,16 @@ No next runner command is currently queued.
 
 No autonomous maintainer-loop run has been recorded yet.
 
+### 2026-07-03T12:00:00Z
+
+- Latest tag observed: `v0.2.11`
+- Implemented milestone: `api-contract-audit` audit-only static API contract surface mapping skill and CLI command.
+- Required permission: `builder-mode-skill-implementation`
+- Validation result: pass pending final publication evidence
+- Next recommended milestone: continue builder-mode wave with `migration-review-skill`
+  after `v0.2.12` publication completes.
+
+
 ### 2026-07-03T11:00:00Z
 
 - Latest tag observed: `v0.2.10`