coding-agent-skills 0.2.11 → 0.2.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/README.md +4 -0
  3. package/ROADMAP.md +5 -3
  4. package/bin/coding-agent-skills +7 -0
  5. package/docs/adapters/README.md +19 -0
  6. package/docs/adapters/project-installation.md +12 -0
  7. package/docs/adapters/real-project-adoption.md +2 -2
  8. package/docs/architecture/README.md +1 -0
  9. package/docs/release/README.md +2 -2
  10. package/docs/release/npm-package.md +6 -2
  11. package/docs/safety/README.md +6 -1
  12. package/docs/testing/README.md +7 -0
  13. package/docs/usage/README.md +14 -5
  14. package/examples/command-policies/api-contract-audit.json +70 -0
  15. package/examples/evidence-packs/api-contract-audit.json +60 -0
  16. package/examples/manifests/api-contract-audit.json +14 -0
  17. package/examples/workflows/api-contract-audit.md +8 -0
  18. package/package.json +2 -1
  19. package/runs/skill-runs.md +16 -0
  20. package/schemas/project-adapter-installation.schema.json +2 -0
  21. package/schemas/project-adapter.schema.json +2 -0
  22. package/scripts/lib/api-contract-audit.mjs +651 -0
  23. package/scripts/lib/pack-rules.mjs +11 -2
  24. package/scripts/render-api-contract-audit.mjs +8 -0
  25. package/scripts/test-pack.mjs +62 -1
  26. package/scripts/validate-pack.mjs +5 -2
  27. package/skills/api-contract-audit/SKILL.md +85 -0
  28. package/skills/api-contract-audit/adapter-interface.md +16 -0
  29. package/skills/api-contract-audit/agents/openai.yaml +4 -0
  30. package/skills/api-contract-audit/checklist.md +7 -0
  31. package/skills/api-contract-audit/evidence-template.md +13 -0
  32. package/skills/api-contract-audit/examples.md +20 -0
  33. package/skills/api-contract-audit/failure-modes.md +5 -0
  34. package/tests/fixtures/api-contract-audit/adapter-project/.coding-agent/adapters/api-contract-audit-fixture/adapter.json +53 -0
  35. package/tests/fixtures/api-contract-audit/adapter-project/.coding-agent/skills.json +23 -0
  36. package/tests/fixtures/api-contract-audit/adapter-project/README.md +3 -0
  37. package/tests/fixtures/api-contract-audit/adapter-project/package.json +4 -0
  38. package/tests/fixtures/api-contract-audit/adapter-project/src/routes.ts +1 -0
  39. package/tests/fixtures/api-contract-audit/static-project/README.md +3 -0
  40. package/tests/fixtures/api-contract-audit/static-project/app/api/users/route.ts +7 -0
  41. package/tests/fixtures/api-contract-audit/static-project/docs/openapi.yaml +10 -0
  42. package/tests/fixtures/api-contract-audit/static-project/package.json +4 -0
  43. package/tests/fixtures/api-contract-audit/static-project/schemas/user.schema.ts +4 -0
  44. package/tests/fixtures/api-contract-audit/static-project/src/client.ts +3 -0
  45. package/tests/fixtures/triggers/cases.json +13 -1
  46. package/tests/trigger/README.md +2 -0
  47. package/work-ledger.md +19 -7
package/CHANGELOG.md CHANGED
@@ -2,6 +2,26 @@
2
2
 
3
3
  All notable changes follow [Semantic Versioning](docs/versioning/README.md).
4
4
 
5
+ ## [0.2.12] - 2026-07-03
6
+
7
+ ### Added
8
+
9
+ - `api-contract-audit` audit-only skill for static API contract surface mapping.
10
+ - `coding-agent-skills api-contract-audit <project-root>` CLI command.
11
+ - Dependency-free API contract audit renderer for contract files, endpoint declarations,
12
+ client-call patterns, schema/type files, skipped paths, not-verified runtime behavior,
13
+ adapter-limited scope, and safety refusals.
14
+ - Synthetic API contract fixtures and release tests for generic static scans,
15
+ adapter-scoped scans, OpenAPI files, route handlers, client calls, schema/type files,
16
+ and repo-map-only adapter skips.
17
+
18
+ ### Changed
19
+
20
+ - Adapter schemas and validators now recognize `api-contract-audit` as an audit-only skill
21
+ while preserving the existing `0.2.3` adapter contract compatibility baseline.
22
+ - Usage, release, safety, architecture, adapter, roadmap, ledger, and run-log docs now
23
+ describe the new static read-only API contract audit command.
24
+
5
25
  ## [0.2.11] - 2026-07-03
6
26
 
7
27
  ### Added
package/README.md CHANGED
@@ -9,6 +9,7 @@ The pilot pack contains:
9
9
  - `route-trace`: audit-only static route surface tracing.
10
10
  - `env-audit`: audit-only environment variable name mapping without values.
11
11
  - `secret-audit`: audit-only high-confidence secret exposure detection without values.
12
+ - `api-contract-audit`: audit-only static API contract surface mapping.
12
13
  - `build-verify`: controlled local validation using existing project commands.
13
14
  - `git-preflight`: audit-only Git readiness inspection.
14
15
  - `runtime-truth`: audit-only runtime evidence collection.
@@ -44,6 +45,7 @@ Every skill emits the evidence-pack contract. A command being attempted is never
44
45
  - Trace static route surfaces with `coding-agent-skills route-trace <project-root>`.
45
46
  - Map environment variable names with `coding-agent-skills env-audit <project-root>`.
46
47
  - Find redacted secret exposure risks with `coding-agent-skills secret-audit <project-root>`.
48
+ - Map static API contract surfaces with `coding-agent-skills api-contract-audit <project-root>`.
47
49
  - Validate project adapters against [the formal adapter schema](schemas/project-adapter.schema.json).
48
50
  - Review [external adapter discovery](docs/adapters/discovery.md).
49
51
  - Run `node scripts/validate-adapters.mjs <adapter-root>` for a disposable external root.
@@ -55,6 +57,8 @@ Every skill emits the evidence-pack contract. A command being attempted is never
55
57
  `node scripts/render-route-trace.mjs <project-root>`.
56
58
  - Render a redacted secret-audit report with
57
59
  `node scripts/render-secret-audit.mjs <project-root>`.
60
+ - Render a static API contract audit report with
61
+ `node scripts/render-api-contract-audit.mjs <project-root>`.
58
62
  - Review [adapter upgrade checks](docs/adapters/upgrades.md).
59
63
  - Run `node scripts/check-adapter-upgrade.mjs <before-project-root> <after-project-root>`
60
64
  for disposable project revisions.
package/ROADMAP.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Roadmap
2
2
 
3
- The public package now contains eight approved shared skills. Builder-mode approval is
3
+ The public package now contains nine approved shared skills. Builder-mode approval is
4
4
  active for the remaining read-only skill wave in this repository; real-world project
5
5
  execution constraints remain unchanged.
6
6
 
@@ -34,6 +34,8 @@ execution constraints remain unchanged.
34
34
  variable name mapping.
35
35
  - `v0.2.11`: audit-only `secret-audit` skill and CLI renderer for redacted secret
36
36
  exposure detection.
37
+ - `v0.2.12`: audit-only `api-contract-audit` skill and CLI renderer for static API
38
+ contract surface mapping.
37
39
 
38
40
  The next milestone is recorded in [work-ledger.md](work-ledger.md). The
39
41
  [maintainer loop](RUNBOOK.md) may select and evidence that milestone, but it must stop
@@ -77,8 +79,8 @@ Next safe milestone options:
77
79
  | `route-trace-skill` | General | Audit-only | Implemented in `v0.2.9` |
78
80
  | `env-audit-skill` | General | Audit-only | Implemented in `v0.2.10` |
79
81
  | `secret-audit-skill` | General | Audit-only | Implemented in `v0.2.11` |
80
- | `api-contract-audit-skill` | General | Audit-only | Builder-mode approved; next in wave |
81
- | `migration-review-skill` | General with platform adapters | Audit-only | Builder-mode approved; later in wave |
82
+ | `api-contract-audit-skill` | General | Audit-only | Implemented in `v0.2.12` |
83
+ | `migration-review-skill` | General with platform adapters | Audit-only | Builder-mode approved; next in wave |
82
84
  | `github-handoff-skill` | General | Audit-only | Builder-mode approved; later in wave |
83
85
  | `deployment-preflight-skill` | General | Audit-only | Builder-mode approved; later in wave |
84
86
  | `cloudflare-preflight-skill` | Platform-specific | Audit-only | Builder-mode approved; later in wave |
@@ -41,6 +41,12 @@ const commands = {
41
41
  usage: "coding-agent-skills secret-audit <project-root>",
42
42
  requiredArgs: 1,
43
43
  },
44
+ "api-contract-audit": {
45
+ script: "scripts/render-api-contract-audit.mjs",
46
+ args: ([projectRoot]) => [projectRoot],
47
+ usage: "coding-agent-skills api-contract-audit <project-root>",
48
+ requiredArgs: 1,
49
+ },
44
50
  "validate-adapters": {
45
51
  script: "scripts/validate-adapters.mjs",
46
52
  args: ([adapterRoot]) => [adapterRoot],
@@ -60,6 +66,7 @@ function usage(exitCode = 0) {
60
66
  " route-trace <project-root>",
61
67
  " env-audit <project-root>",
62
68
  " secret-audit <project-root>",
69
+ " api-contract-audit <project-root>",
63
70
  " validate-adapters <adapter-root>",
64
71
  "",
65
72
  "local wrapper for the published coding-agent-skills package",
@@ -87,6 +87,23 @@ reports finding paths, types, and counts. It never prints matched values, valida
87
87
  credentials, rotates secrets, contacts APIs, deploys, migrates, builds, tests, or mutates
88
88
  project files.
89
89
 
90
+ ## Adapter-Aware API Contract Audit Consumption
91
+
92
+ The shared pack can consume a validated project-owned adapter as bounded context for
93
+ `api-contract-audit`:
94
+
95
+ ```bash
96
+ node scripts/render-api-contract-audit.mjs <project-root>
97
+ ```
98
+
99
+ The renderer validates the project declaration when present. If an adapter is present but
100
+ does not enable `api-contract-audit`, it reports an adapter-limited skip instead of
101
+ broadening scope. When enabled, it reads only adapter-declared safe paths, excludes `.env`,
102
+ secret-bearing files, generated output, dependency paths, and oversized files, then
103
+ reports contract files, endpoint declarations, client-call patterns, schema/type files,
104
+ skipped paths, and not-verified runtime behavior. It never runs servers, calls APIs,
105
+ generates schemas or clients, builds, tests, deploys, migrates, or mutates project files.
106
+
90
107
  ## What Adapters May Do
91
108
 
92
109
  - Add bounded relative read paths and ignored paths.
@@ -96,6 +113,8 @@ project files.
96
113
  - Add env-audit safe read paths for static source, docs, sample, and config files.
97
114
  - Add secret-audit safe read paths for static source, docs, sample, and config files
98
115
  while relying on the shared scanner to exclude secret-bearing paths.
116
+ - Add api-contract-audit safe read paths for static API docs, contract files, route
117
+ handlers, client calls, and schema/type files.
99
118
  - Add command aliases that already satisfy the shared command policy.
100
119
  - Add status-only runtime commands and manager hints.
101
120
  - Require additional evidence or named approval for exceptional reads.
@@ -145,6 +145,18 @@ enabled, it reads only adapter-declared safe paths, refuses `.env` and secret-be
145
145
  files, and reports high-confidence finding paths, types, and counts without matched
146
146
  values or credential validation.
147
147
 
148
+ A project-owned adapter can also enable read-only `api-contract-audit` context:
149
+
150
+ ```bash
151
+ node scripts/render-api-contract-audit.mjs <project-root>
152
+ ```
153
+
154
+ The API contract audit renderer validates the project declaration when present. If the
155
+ adapter is present but does not enable `api-contract-audit`, it reports an adapter-limited
156
+ skip. When enabled, it reads only adapter-declared safe paths and reports static contract
157
+ files, endpoint declarations, client-call patterns, schema/type files, and not-verified
158
+ runtime behavior without running servers, calling APIs, or generating code.
159
+
148
160
  ## Safety Boundary
149
161
 
150
162
  Project adapters are extension-only. They cannot remove denied operations, change an
@@ -21,8 +21,8 @@ project repository is touched:
21
21
  - The project can declare exactly one installation file: `.coding-agent/skills.json` or
22
22
  `coding-agent.skills.json`.
23
23
  - The adapter need is bounded to existing pilot skills: `repo-map`, `route-trace`,
24
- `env-audit`, `secret-audit`, `build-verify`, `git-preflight`, `runtime-truth`, or
25
- `llm-drift-control`.
24
+ `env-audit`, `secret-audit`, `api-contract-audit`, `build-verify`, `git-preflight`,
25
+ `runtime-truth`, or `llm-drift-control`.
26
26
  - The adapter can narrow context with relative paths, documentation precedence, safe
27
27
  aliases, status-only hints, or extra evidence requirements.
28
28
  - The adapter does not require deployment, migration, package installation, Git
@@ -15,6 +15,7 @@ Audit-only:
15
15
  - `route-trace`
16
16
  - `env-audit`
17
17
  - `secret-audit`
18
+ - `api-contract-audit`
18
19
  - `git-preflight`
19
20
  - `runtime-truth`
20
21
  - `llm-drift-control`
@@ -20,8 +20,8 @@
20
20
  folders, generated output, and unrelated repositories.
21
21
  14. Install the tarball into a temporary npm prefix and smoke-test the installed CLI.
22
22
  15. Smoke-test any new CLI command such as `coding-agent-skills route-trace`,
23
- `coding-agent-skills env-audit`, or `coding-agent-skills secret-audit` against
24
- synthetic fixtures only unless a real project
23
+ `coding-agent-skills env-audit`, `coding-agent-skills secret-audit`, or
24
+ `coding-agent-skills api-contract-audit` against synthetic fixtures only unless a real project
25
25
  read-only smoke is explicitly approved.
26
26
  16. Review changelog, ledger, run evidence, and versioning impact.
27
27
  17. Commit with approved identity.
@@ -7,7 +7,7 @@ safety model.
7
7
  ## Current Package Shape
8
8
 
9
9
  - Package name: `coding-agent-skills`.
10
- - Package version: `0.2.11`.
10
+ - Package version: `0.2.12`.
11
11
  - CLI bin: `coding-agent-skills` mapped to `bin/coding-agent-skills`.
12
12
  - Module type: `module`.
13
13
  - Dependencies: none.
@@ -30,6 +30,7 @@ coding-agent-skills repo-map /path/to/project
30
30
  coding-agent-skills route-trace /path/to/project
31
31
  coding-agent-skills env-audit /path/to/project
32
32
  coding-agent-skills secret-audit /path/to/project
33
+ coding-agent-skills api-contract-audit /path/to/project
33
34
  coding-agent-skills validate-adapters /path/to/adapter-root
34
35
  ```
35
36
 
@@ -47,6 +48,9 @@ printing values.
47
48
  `secret-audit` is static and audit-only; it reports high-confidence secret-like finding
48
49
  paths, types, and counts without printing matched values, reading `.env` files, or
49
50
  validating credentials.
51
+ `api-contract-audit` is static and audit-only; it reports contract files, endpoint
52
+ declarations, client-call patterns, schema/type files, and not-verified runtime behavior
53
+ without running servers, calling APIs, or generating clients or schemas.
50
54
 
51
55
  `coding-agent-skills validate-pack` is package-aware. In a source checkout, it keeps
52
56
  source-only checks such as `.gitignore` validation. In an installed package tree, where
@@ -81,7 +85,7 @@ included.
81
85
 
82
86
  The public CLI remains read-only for target projects unless a specific underlying skill
83
87
  already permits a bounded local validation action. The installed `repo-map`,
84
- `route-trace`, `env-audit`, `secret-audit`, and adapter flows do not:
88
+ `route-trace`, `env-audit`, `secret-audit`, `api-contract-audit`, and adapter flows do not:
85
89
 
86
90
  - deploy
87
91
  - run migrations
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## Audit-Only Rule
4
4
 
5
- `repo-map`, `route-trace`, `env-audit`, `secret-audit`, `git-preflight`, `runtime-truth`, and `llm-drift-control` must not alter project files, Git state, dependencies, processes, services, databases, remote systems, or deployment state.
5
+ `repo-map`, `route-trace`, `env-audit`, `secret-audit`, `api-contract-audit`, `git-preflight`, `runtime-truth`, and `llm-drift-control` must not alter project files, Git state, dependencies, processes, services, databases, remote systems, or deployment state.
6
6
 
7
7
  `route-trace` is static only. It may read bounded non-secret route files and route
8
8
  configuration, but it must not execute app code, run servers, hit URLs, claim runtime
@@ -17,6 +17,11 @@ files and report high-confidence secret-like finding paths, types, and counts, b
17
17
  not print matched values, read `.env` or secret-bearing files, inspect credential stores,
18
18
  validate or rotate credentials, contact APIs, or broaden adapter scope.
19
19
 
20
+ `api-contract-audit` is static only. It may read bounded non-secret API docs, contract
21
+ files, route handlers, client calls, and schema/type files, but it must not run servers,
22
+ call APIs, probe URLs, generate schemas or clients, build, test, deploy, migrate, inspect
23
+ databases, or broaden adapter scope.
24
+
20
25
  `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.
21
26
 
22
27
  ## Restricted Categories
@@ -52,6 +52,13 @@ behavior. Secret-audit tests construct synthetic secret-like values only in temp
52
52
  directories and assert that rendered reports include paths, types, and counts without
53
53
  printing matched values.
54
54
 
55
+ ## API Contract Audit
56
+
57
+ Synthetic api-contract-audit projects cover OpenAPI file detection, static route handler
58
+ declarations, client-call patterns, schema/type files, adapter-declared scope, and
59
+ adapter-present-but-not-enabled behavior. Tests must never run servers, call endpoints,
60
+ generate schemas or clients, build, test, deploy, migrate, or read `.env` files.
61
+
55
62
  ## Privacy And Redaction
56
63
 
57
64
  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.
@@ -8,6 +8,7 @@ Select the least-privileged skill that matches the request:
8
8
  | Trace statically visible route surfaces | `route-trace` |
9
9
  | Map environment variable names without values | `env-audit` |
10
10
  | Find high-confidence secret exposure risks without values | `secret-audit` |
11
+ | Map static API contract surfaces | `api-contract-audit` |
11
12
  | Run existing local validation checks | `build-verify` |
12
13
  | Assess Git handoff readiness | `git-preflight` |
13
14
  | Determine what is actually running | `runtime-truth` |
@@ -21,11 +22,13 @@ Select the least-privileged skill that matches the request:
21
22
  mapped without reading values.
22
23
  4. Use `secret-audit` when high-confidence tracked secret exposure risk must be reported
23
24
  by path, type, and count without printing matched values.
24
- 5. Perform implementation outside this pilot pack.
25
- 6. Use `build-verify` for approved project-native checks.
26
- 7. Use `git-preflight` before handoff or publication.
27
- 8. Use `runtime-truth` only when live local state matters.
28
- 9. Use `llm-drift-control` when claims and evidence may disagree.
25
+ 5. Use `api-contract-audit` when OpenAPI/Swagger files, endpoint declarations, client
26
+ calls, and schema/type files must be mapped without runtime behavior.
27
+ 6. Perform implementation outside this pilot pack.
28
+ 7. Use `build-verify` for approved project-native checks.
29
+ 8. Use `git-preflight` before handoff or publication.
30
+ 9. Use `runtime-truth` only when live local state matters.
31
+ 10. Use `llm-drift-control` when claims and evidence may disagree.
29
32
 
30
33
  Every skill emits an evidence pack. Read `status`, skipped checks, failures, confidence, and changed state before relying on a completion claim.
31
34
 
@@ -59,6 +62,7 @@ coding-agent-skills repo-map /path/to/project
59
62
  coding-agent-skills route-trace /path/to/project
60
63
  coding-agent-skills env-audit /path/to/project
61
64
  coding-agent-skills secret-audit /path/to/project
65
+ coding-agent-skills api-contract-audit /path/to/project
62
66
  coding-agent-skills validate-adapters /path/to/adapter-root
63
67
  ```
64
68
 
@@ -81,6 +85,9 @@ stores without printing values.
81
85
  `secret-audit` validates a project adapter when present, uses adapter-declared safe paths
82
86
  when enabled, and statically reports high-confidence secret-like finding paths, types, and
83
87
  counts without printing matched values or validating credentials.
88
+ `api-contract-audit` validates a project adapter when present, uses adapter-declared safe
89
+ paths when enabled, and statically reports contract files, endpoint declarations,
90
+ client-call patterns, schema/type files, skipped paths, and not-verified runtime behavior.
84
91
 
85
92
  The installed CLI does not run target project builds or tests, perform runtime checks,
86
93
  deploy, migrate, mutate services or processes, or read `.env` files. Project adapters
@@ -97,6 +104,7 @@ bin/coding-agent-skills repo-map /path/to/project
97
104
  bin/coding-agent-skills route-trace /path/to/project
98
105
  bin/coding-agent-skills env-audit /path/to/project
99
106
  bin/coding-agent-skills secret-audit /path/to/project
107
+ bin/coding-agent-skills api-contract-audit /path/to/project
100
108
  bin/coding-agent-skills validate-adapters /path/to/adapter-root
101
109
  ```
102
110
 
@@ -110,6 +118,7 @@ coding-agent-skills repo-map /path/to/project
110
118
  coding-agent-skills route-trace /path/to/project
111
119
  coding-agent-skills env-audit /path/to/project
112
120
  coding-agent-skills secret-audit /path/to/project
121
+ coding-agent-skills api-contract-audit /path/to/project
113
122
  coding-agent-skills validate-adapters /path/to/adapter-root
114
123
  ```
115
124
 
@@ -0,0 +1,70 @@
1
+ {
2
+ "version": "0.2.3",
3
+ "mode": "audit-only",
4
+ "parserPolicy": {
5
+ "inspectEverySegment": true,
6
+ "inspectScriptBodies": true,
7
+ "rejectUnknownExecutables": true,
8
+ "rejectShellWrappers": true,
9
+ "rejectHeredocs": true,
10
+ "rejectRedirection": true,
11
+ "providerSpecificNpx": true,
12
+ "authenticatedCurlRequiresApproval": true,
13
+ "boundedReadsRequired": true,
14
+ "allowedComposition": "read-only"
15
+ },
16
+ "allowedFamilies": [
17
+ {
18
+ "name": "bounded-api-contract-inspection",
19
+ "executables": ["pwd", "ls", "rg", "find", "sed", "head"],
20
+ "argumentPolicy": {
21
+ "strategy": "pattern",
22
+ "allowedPatterns": ["bounded repository-local static contract, route, client, and schema inspection"],
23
+ "deniedPatterns": ["runtime calls, API calls, generation, secret files, credential stores, and unbounded traversal"]
24
+ },
25
+ "constraints": [
26
+ "Remain inside the declared project scope.",
27
+ "Bound traversal depth and output.",
28
+ "Exclude .env, secret-bearing, generated, dependency, build, and runtime-output paths."
29
+ ]
30
+ },
31
+ {
32
+ "name": "git-identity-inspection",
33
+ "executables": ["git"],
34
+ "argumentPolicy": {
35
+ "strategy": "exact",
36
+ "allowedPatterns": ["rev-parse and status --short --branch"],
37
+ "deniedPatterns": ["all Git mutation and publication subcommands"]
38
+ },
39
+ "constraints": ["Allow only read-only repository identity and branch-state inspection."]
40
+ },
41
+ {
42
+ "name": "api-contract-audit-renderer",
43
+ "executables": ["node", "coding-agent-skills"],
44
+ "argumentPolicy": {
45
+ "strategy": "exact",
46
+ "allowedPatterns": ["node scripts/render-api-contract-audit.mjs <project-root>; coding-agent-skills api-contract-audit <project-root>"],
47
+ "deniedPatterns": ["runtime calls, URL probes, API calls, generation, builds, tests, deployment, migration, package installation, and secret-file reads"]
48
+ },
49
+ "constraints": [
50
+ "The renderer must remain static and read-only.",
51
+ "Do not run servers, call endpoints, or generate clients or schemas."
52
+ ]
53
+ }
54
+ ],
55
+ "restrictedCategories": [
56
+ "file-write",
57
+ "package-install",
58
+ "deployment",
59
+ "git-mutation",
60
+ "unrestricted-scan",
61
+ "secret-read",
62
+ "process-mutation",
63
+ "service-mutation",
64
+ "migration-apply",
65
+ "privileged-api"
66
+ ],
67
+ "approvalExceptions": [
68
+ "A named-file approval may permit one otherwise excluded non-mutating static read when the file is not secret-bearing."
69
+ ]
70
+ }
@@ -0,0 +1,60 @@
1
+ {
2
+ "contractVersion": "1.0.0",
3
+ "skill": {"name": "api-contract-audit", "version": "0.2.3"},
4
+ "invocation": {
5
+ "id": "example-api-contract-audit",
6
+ "startedAt": "2026-07-03T12:00:00Z",
7
+ "endedAt": "2026-07-03T12:01:00Z"
8
+ },
9
+ "repository": {
10
+ "root": "/workspace/example-project",
11
+ "branch": "main",
12
+ "head": "0123456789abcdef",
13
+ "workingTreeState": "clean"
14
+ },
15
+ "userIntent": "Map static API contract surfaces before API handoff.",
16
+ "declaredScope": ["/workspace/example-project"],
17
+ "projectAdapter": "example-api-contract-adapter",
18
+ "environmentSummary": {"platform": "linux", "shell": "bash"},
19
+ "status": "complete",
20
+ "confidence": {
21
+ "level": "medium",
22
+ "reason": "Static contract, route, client, and schema files were inspected, but runtime behavior was not verified."
23
+ },
24
+ "commands": [
25
+ {
26
+ "command": "coding-agent-skills api-contract-audit /workspace/example-project",
27
+ "family": "api-contract-audit-renderer",
28
+ "workingDirectory": "/workspace/example-project",
29
+ "startedAt": "2026-07-03T12:00:20Z",
30
+ "endedAt": "2026-07-03T12:00:21Z",
31
+ "exitStatus": 0,
32
+ "resultStatus": "success",
33
+ "safetyClass": "allowed",
34
+ "approvalReference": null,
35
+ "purpose": "Render a static API contract audit report.",
36
+ "outputSummary": "Reported static contract files, endpoint declarations, client calls, schemas, skipped items, and not-verified runtime areas."
37
+ }
38
+ ],
39
+ "skippedChecks": [],
40
+ "findings": [
41
+ {
42
+ "summary": "Static API contract surfaces were mapped without runtime verification.",
43
+ "evidence": ["docs/openapi.yaml", "app/api/example/route.ts", "src/client.ts"]
44
+ }
45
+ ],
46
+ "risks": [
47
+ {
48
+ "summary": "Runtime API behavior may differ from static contract evidence.",
49
+ "evidence": ["runtime route registration was not executed", "deployed API behavior was not probed"]
50
+ }
51
+ ],
52
+ "failures": [],
53
+ "unresolvedQuestions": [],
54
+ "changedState": {
55
+ "changed": false,
56
+ "summary": "No project, Git, dependency, runtime, generated-code, service, or remote state changed."
57
+ },
58
+ "handoffSummary": "Static API contract evidence is mapped; runtime equivalence remains unverified.",
59
+ "recommendedNextAction": "Review reported contract surfaces before editing API handlers or clients."
60
+ }
@@ -0,0 +1,14 @@
1
+ {
2
+ "name": "api-contract-audit",
3
+ "version": "0.2.3",
4
+ "mode": "audit-only",
5
+ "evidenceContract": "../../contracts/evidence-pack/evidence-pack.schema.json",
6
+ "commandPolicy": "../command-policies/api-contract-audit.json",
7
+ "adapterSchema": "../../schemas/project-adapter.schema.json",
8
+ "adapterCompatibility": {
9
+ "contractVersion": "1.0.0",
10
+ "compatibleAdapterVersions": ["1.0.0"]
11
+ },
12
+ "adapterInterface": "../../skills/api-contract-audit/adapter-interface.md",
13
+ "description": "Map static API contract surfaces without runtime calls or generation."
14
+ }
@@ -0,0 +1,8 @@
1
+ Use `api-contract-audit` before API work or handoff:
2
+
3
+ ```bash
4
+ coding-agent-skills api-contract-audit /workspace/project
5
+ ```
6
+
7
+ Review contract files, endpoint declarations, client-call patterns, schema/type files,
8
+ skipped paths, and not-verified runtime behavior before making API claims.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "coding-agent-skills",
3
- "version": "0.2.11",
3
+ "version": "0.2.12",
4
4
  "description": "Evidence-first, read-only coding-agent skills and project adapter tooling.",
5
5
  "type": "module",
6
6
  "private": false,
@@ -12,6 +12,7 @@
12
12
  "route-trace",
13
13
  "env-audit",
14
14
  "secret-audit",
15
+ "api-contract-audit",
15
16
  "project-adapters",
16
17
  "code-validation",
17
18
  "cli"
@@ -213,3 +213,19 @@ This file records bounded maintainer-loop runs. Entries must not contain secrets
213
213
  - Validation commands: pending final release validation matrix.
214
214
  - Result: pass pending final publication evidence.
215
215
  - Commit/tag/push status: pending approved release workflow.
216
+
217
+ ## implementation-v0.2.12-api-contract-audit
218
+
219
+ - Run ID: `implementation-v0.2.12-api-contract-audit`
220
+ - Repository: `/home/oneclickwebsitedesignfactory/coding-agent-skills`
221
+ - Command used: `builder-mode approval for api-contract-audit-skill implementation and release`
222
+ - Files changed: `api-contract-audit` skill, API contract audit renderer and library,
223
+ CLI wrapper, adapter schemas, pack rules, release tests, synthetic API contract fixtures,
224
+ usage/release/safety/adapter docs, changelog, roadmap, work ledger, run log, and package
225
+ metadata.
226
+ - Safety boundary: read-only, static-analysis only, no `.env` reads, no target runtime,
227
+ no URL probes, no API calls, no schema/client generation, no builds, no tests in target
228
+ projects, no deploys, no migrations, and no target-project mutation.
229
+ - Validation commands: pending final release validation matrix.
230
+ - Result: pass pending final publication evidence.
231
+ - Commit/tag/push status: pending approved release workflow.
@@ -68,6 +68,7 @@
68
68
  "route-trace",
69
69
  "env-audit",
70
70
  "secret-audit",
71
+ "api-contract-audit",
71
72
  "build-verify",
72
73
  "git-preflight",
73
74
  "runtime-truth",
@@ -103,6 +104,7 @@
103
104
  "route-trace",
104
105
  "env-audit",
105
106
  "secret-audit",
107
+ "api-contract-audit",
106
108
  "build-verify",
107
109
  "git-preflight",
108
110
  "runtime-truth",
@@ -92,6 +92,7 @@
92
92
  "route-trace",
93
93
  "env-audit",
94
94
  "secret-audit",
95
+ "api-contract-audit",
95
96
  "build-verify",
96
97
  "git-preflight",
97
98
  "runtime-truth",
@@ -171,6 +172,7 @@
171
172
  "route-trace",
172
173
  "env-audit",
173
174
  "secret-audit",
175
+ "api-contract-audit",
174
176
  "build-verify",
175
177
  "git-preflight",
176
178
  "runtime-truth",