coding-agent-skills 0.2.8 → 0.2.10

package/scripts/render-env-audit.mjs

@@ -0,0 +1,8 @@
+import { envAuditCliResult } from "./lib/env-audit.mjs";
+
+const outcome = envAuditCliResult(process.argv[2]);
+for (const line of outcome.lines) {
+  if (outcome.stream === "stdout") console.log(line);
+  else console.error(line);
+}
+process.exitCode = outcome.exitCode;

package/scripts/render-route-trace.mjs

@@ -0,0 +1,8 @@
+import { routeTraceCliResult } from "./lib/route-trace.mjs";
+
+const outcome = routeTraceCliResult(process.argv[2]);
+for (const line of outcome.lines) {
+  if (outcome.stream === "stdout") console.log(line);
+  else console.error(line);
+}
+process.exitCode = outcome.exitCode;

package/scripts/test-pack.mjs

@@ -42,6 +42,16 @@ import {
   buildAdapterRepoMapReport,
   renderAdapterRepoMapReport,
 } from "./lib/adapter-repo-map.mjs";
+import {
+  buildRouteTraceReport,
+  renderRouteTraceReport,
+  routeTraceCliResult,
+} from "./lib/route-trace.mjs";
+import {
+  buildEnvAuditReport,
+  envAuditCliResult,
+  renderEnvAuditReport,
+} from "./lib/env-audit.mjs";
 import {
   adapterUpgradeCliResult,
   checkAdapterUpgrade,
@@ -256,6 +266,8 @@ test("local CLI maps approved commands to existing safe scripts", () => {
   assert.ok(cliText.includes("scripts/validate-pack.mjs"));
   assert.ok(cliText.includes("scripts/validate-project-adapters.mjs"));
   assert.ok(cliText.includes("scripts/render-adapter-repo-map.mjs"));
+  assert.ok(cliText.includes("scripts/render-route-trace.mjs"));
+  assert.ok(cliText.includes("scripts/render-env-audit.mjs"));
   assert.ok(cliText.includes("scripts/validate-adapters.mjs"));
   assert.ok(!cliText.includes(".env"));
 
@@ -277,6 +289,14 @@ test("local CLI maps approved commands to existing safe scripts", () => {
       ["repo-map", path.join(fixtureRoot, "project-adapter-installation", "valid-exact-pin")],
       /# Adapter-Aware Repo Map/,
     ],
+    [
+      ["route-trace", path.join(fixtureRoot, "route-trace", "static-project")],
+      /# Route Trace Report/,
+    ],
+    [
+      ["env-audit", path.join(fixtureRoot, "env-audit", "static-project")],
+      /# Env Audit Report/,
+    ],
   ];
 
   for (const [args, expected] of commands) {
@@ -301,7 +321,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.8");
+  assert.equal(packageJson.version, "0.2.10");
   assert.equal(
     packageJson.description,
     "Evidence-first, read-only coding-agent skills and project adapter tooling.",
@@ -313,6 +333,8 @@ test("npm package metadata is public-ready and dependency-free", () => {
     "coding-agent",
     "agent-skills",
     "repo-map",
+    "route-trace",
+    "env-audit",
     "project-adapters",
     "code-validation",
     "cli",
@@ -363,6 +385,142 @@ test("npm package metadata is public-ready and dependency-free", () => {
   assert.match(read("docs/release/npm-package.md"), /npm install -g coding-agent-skills/);
 });
 
+test("route-trace renderer identifies static route files and inferred patterns", () => {
+  const result = buildRouteTraceReport(
+    path.join(root, "tests", "fixtures", "route-trace", "static-project"),
+    { coreRoot: root },
+  );
+  assert.equal(result.ok, true);
+  assert.equal(result.status, "complete");
+  assert.equal(result.adapter.present, false);
+  assert.ok(
+    result.verifiedRouteFiles.some(
+      (record) => record.route === "/api/users" && record.file === "app/api/users/route.ts",
+    ),
+  );
+  assert.ok(
+    result.verifiedRouteFiles.some(
+      (record) => record.route === "/blog/[slug]" && record.file === "app/blog/[slug]/page.tsx",
+    ),
+  );
+  assert.ok(
+    result.verifiedRouteFiles.some(
+      (record) => record.route === "/api/hello" && record.file === "pages/api/hello.ts",
+    ),
+  );
+  assert.ok(
+    result.inferredRoutePatterns.some(
+      (record) => record.route === "/dashboard" && record.kind === "react-router-route-declaration",
+    ),
+  );
+  assert.ok(
+    result.inferredRoutePatterns.some(
+      (record) => record.route === "/health" && record.method === "GET",
+    ),
+  );
+  assert.ok(result.notVerified.includes("runtime-generated routes"));
+  assert.ok(renderRouteTraceReport(result).includes("No target project build"));
+});
+
+test("route-trace renderer respects adapter-declared scope", () => {
+  const result = buildRouteTraceReport(
+    path.join(root, "tests", "fixtures", "route-trace", "adapter-project"),
+    { coreRoot: root },
+  );
+  assert.equal(result.ok, true);
+  assert.equal(result.status, "complete");
+  assert.equal(result.adapter.present, true);
+  assert.equal(result.adapter.enabled, true);
+  assert.deepEqual(result.adapter.scopePaths, ["app", "pages", "src"]);
+  assert.ok(
+    result.verifiedRouteFiles.some(
+      (record) => record.route === "/api/items" && record.file === "app/api/items/route.ts",
+    ),
+  );
+  assert.ok(
+    result.inferredRoutePatterns.some((record) => record.route === "/adapter-health"),
+  );
+
+  const cli = routeTraceCliResult(
+    path.join(root, "tests", "fixtures", "route-trace", "adapter-project"),
+    { coreRoot: root },
+  );
+  assert.equal(cli.exitCode, 0);
+  assert.match(cli.lines.join("\n"), /route-trace used adapter-declared safe read paths only/);
+});
+
+test("route-trace does not broaden a repo-map-only project adapter", () => {
+  const result = buildRouteTraceReport(
+    path.join(root, "tests", "fixtures", "project-adapter-installation", "valid-exact-pin"),
+    { coreRoot: root },
+  );
+  assert.equal(result.ok, true);
+  assert.equal(result.status, "partial");
+  assert.equal(result.adapter.present, true);
+  assert.equal(result.adapter.enabled, false);
+  assert.deepEqual(result.scannedFiles, []);
+  assert.match(renderRouteTraceReport(result), /route-trace is not enabled/);
+});
+
+test("env-audit identifies variable names without reading .env values", () => {
+  const temporary = fs.mkdtempSync(path.join(os.tmpdir(), "env-audit-fixture-"));
+  fs.cpSync(path.join(root, "tests", "fixtures", "env-audit", "static-project"), temporary, {
+    recursive: true,
+  });
+  fs.writeFileSync(path.join(temporary, ".env"), "SHOULD_NOT_BE_READ=synthetic-fixture-value\n");
+
+  const result = buildEnvAuditReport(
+    temporary,
+    { coreRoot: root },
+  );
+
+  assert.equal(result.status, "complete");
+  assert.ok(result.filesScanned.includes(".env.example"));
+  assert.ok(!result.filesScanned.includes(".env"));
+  assert.ok(result.skipped.some((item) => item.path === ".env"));
+  const names = result.variables.map((variable) => variable.name);
+  assert.ok(names.includes("DATABASE_URL"));
+  assert.ok(names.includes("NEXT_PUBLIC_APP_URL"));
+  assert.ok(names.includes("PORT"));
+  assert.ok(names.includes("SERVICE_TOKEN"));
+  assert.ok(names.includes("DENO_REGION"));
+  const rendered = renderEnvAuditReport(result);
+  assert.match(rendered, /DATABASE_URL/);
+  assert.doesNotMatch(rendered, /synthetic-fixture-value/);
+});
+
+test("env-audit respects adapter-declared scope", () => {
+  const result = buildEnvAuditReport(
+    path.join(root, "tests", "fixtures", "env-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/config.ts"]);
+  assert.ok(result.variables.some((variable) => variable.name === "ADAPTER_ONLY_VALUE"));
+  assert.ok(result.warnings.includes("env-audit used adapter-declared safe read paths only"));
+  const cli = envAuditCliResult(
+    path.join(root, "tests", "fixtures", "env-audit", "adapter-project"),
+    { coreRoot: root },
+  );
+  assert.equal(cli.exitCode, 0);
+  assert.match(cli.lines.join("\n"), /Env-audit enabled: yes/);
+});
+
+test("env-audit does not broaden a repo-map-only project adapter", () => {
+  const result = buildEnvAuditReport(
+    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.variables.length, 0);
+  assert.match(renderEnvAuditReport(result), /env-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

@@ -95,11 +95,15 @@ const requiredRootFiles = [
   "scripts/verify-evidence-bundle.mjs",
   "scripts/render-evidence-archive-report.mjs",
   "scripts/render-adapter-repo-map.mjs",
+  "scripts/render-route-trace.mjs",
+  "scripts/render-env-audit.mjs",
   "scripts/check-adapter-upgrade.mjs",
   "scripts/check-adapter-upgrade-chain.mjs",
   "scripts/validate-adapters.mjs",
   "scripts/validate-project-adapters.mjs",
   "scripts/lib/adapter-repo-map.mjs",
+  "scripts/lib/route-trace.mjs",
+  "scripts/lib/env-audit.mjs",
   "scripts/lib/adapter-upgrade.mjs",
   "scripts/lib/adapter-upgrade-chain.mjs",
   "scripts/lib/adapter-discovery.mjs",
@@ -673,8 +677,8 @@ if (packageJson) {
   if (packageJson.name !== "coding-agent-skills") {
     failures.push("package.json has unexpected package name");
   }
-  if (packageJson.version !== "0.2.8") {
-    failures.push("package.json version must be 0.2.8 for public package validation");
+  if (packageJson.version !== "0.2.10") {
+    failures.push("package.json version must be 0.2.10 for public package validation");
   }
   if (packageJson.type !== "module") failures.push("package.json must preserve ESM mode");
   if (packageJson.private !== false) {
@@ -692,6 +696,8 @@ if (packageJson) {
       "coding-agent",
       "agent-skills",
       "repo-map",
+      "route-trace",
+      "env-audit",
       "project-adapters",
       "code-validation",
       "cli",

package/skills/env-audit/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: env-audit
+description: Identify environment variable names and configuration requirements from static files without reading .env files or printing values. Use when Codex must map required, optional, sample, or inferred environment names before implementation, deployment planning, or handoff; do not use for secret validation, credential testing, API calls, runtime checks, builds, tests, deployments, migrations, or secret-file reads.
+---
+
+# Env Audit
+
+Identify environment variable names from bounded static evidence and emit a value-free report. Remain audit-only and fail closed when evidence would require secret files, runtime state, or credential validation.
+
+This skill must not change project files, Git state, dependencies, runtime state, services,
+databases, remotes, or deployment state.
+
+## Purpose And Use
+
+Use this skill to map statically visible environment variable names, sample declarations, and configuration references before changing code, documenting setup, or preparing handoff. It can classify names as sample, required, optional, or inferred, but it must not claim that any value exists or works.
+
+Do not use this skill for secret auditing, credential validation, live service checks, runtime truth claims, deployment readiness, migrations, builds, tests, or package installation.
+
+## Inputs
+
+Require a project root or starting path. Optionally accept a project adapter, intended config area, maximum static scan depth, or named framework/config family to prioritize.
+
+Do not assume `.env` files may be read, variable values are safe, documented names are complete, sample files are current, runtime-injected variables are visible, or an adapter covers every configuration surface.
+
+## 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 `env-audit`, stop static file reading and report the adapter-limited skip.
+4. Build the scan scope from adapter safe read paths when available; otherwise use a bounded generic static scan.
+5. Exclude `.env`, `.env.*` except `.env.example`, secret-bearing paths, generated paths, dependency paths, and oversized files before reading.
+6. Extract environment variable names from safe static patterns such as `process.env.NAME`, `import.meta.env.NAME`, `Deno.env.get("NAME")`, `env("NAME")`, docs, and `.env.example` declarations.
+7. Never print values, line contents, tokens, credentials, or raw secret-like matches.
+8. Label every finding as sample, required, optional, inferred, skipped, or not verified.
+9. Report skipped files, unverified runtime/secret-store areas, branch state warnings, and safety refusals.
+10. Emit the shared evidence pack or env-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, variable names, classifications, file references, sample files inspected, skipped items, not-verified areas, warnings, and changed-state declaration through the shared evidence-pack contract.
+
+Recover from missing adapters, unreadable files, ambiguous variable names, or secret-bearing paths by narrowing scope and reporting uncertainty. Never recover by reading `.env`, printing values, validating credentials, contacting APIs, installing dependencies, running builds/tests, broadening adapter scope, or mutating files.
+
+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 credential validation.
+
+## Approval Boundary
+
+Explicit approval may permit one named non-secret static file read outside normal config paths. Approval does not permit `.env` or secret-file reads, value printing, credential validation, API calls, builds, tests, package installation, runtime checks, deployments, migrations, Git mutation, or project writes.
+
+## Completion
+
+Claim `complete` only when the declared static scan scope was inspected, variable names are reported without values, skipped and not-verified areas are recorded with consequences, adapter limitations are explicit, and no project, Git, dependency, runtime, service, or remote state changed.
+
+Report `partial`, `failed`, or `blocked` when adapter scope prevents env scanning, requested evidence requires secret files or runtime state, the project root cannot be established, or safety exclusions prevent a requested conclusion. Never claim credential presence or validity from static findings.
+
+These conditions are both the acceptance criteria and definition of done.

package/skills/env-audit/adapter-interface.md

@@ -0,0 +1,12 @@
+Adapters may enable `env-audit` by declaring the skill ID with unchanged `audit-only`
+mode and compatible version `0.2.3` or `0.2.x`.
+
+Useful extension fields:
+
+- `safeReadPaths`: source, docs, sample, and config paths that may contain env names.
+- `ignoredPaths`: generated, dependency, runtime-output, and secret-bearing paths to skip.
+- `documentationPrecedence`: docs that may explain required or optional env names.
+- `requiredEvidence`: evidence the report must include before completion.
+
+Adapters must not add `.env`, `.env.*` except `.env.example`, credentials, secret stores,
+runtime checks, API calls, builds, tests, deployments, migrations, or project writes.

package/skills/env-audit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Env Audit"
+  short_description: "Map env variable names without reading values"
+  default_prompt: "Audit the statically visible environment variable names in this repository without changing project state. Do not read .env files or print values."

package/skills/env-audit/checklist.md

@@ -0,0 +1,7 @@
+- Confirm project root, branch state, and adapter state.
+- Validate adapter before consuming any adapter-declared paths.
+- Refuse `.env`, `.env.*` except `.env.example`, secret-bearing paths, and generated outputs.
+- Scan only bounded static source, docs, sample, and config files.
+- Record variable names, classifications, and file references without values.
+- Record skipped files and runtime/secret-store areas that were not verified.
+- Confirm no files, dependencies, runtime state, services, remotes, or databases changed.

package/skills/env-audit/evidence-template.md

@@ -0,0 +1,17 @@
+## Env Audit Evidence
+
+- Repository root:
+- Branch state:
+- Adapter state:
+- Scan scope:
+- Ignored paths:
+- Static files scanned:
+- Sample files inspected:
+- Variable names found:
+- Required names:
+- Optional names:
+- Inferred names:
+- Skipped items:
+- Not verified:
+- Safety refusals:
+- Changed state: none

package/skills/env-audit/examples.md

@@ -0,0 +1,28 @@
+## Safe
+
+```bash
+coding-agent-skills env-audit /workspace/app
+```
+
+Produces a value-free list of names such as `DATABASE_URL`, `NEXT_PUBLIC_API_URL`, and
+`PORT`, with file references and classifications.
+
+```bash
+node scripts/render-env-audit.mjs tests/fixtures/env-audit/static-project
+```
+
+Runs the synthetic fixture scanner without reading `.env` files or contacting services.
+
+## Unsafe
+
+```bash
+cat .env
+```
+
+Secret-file reads are forbidden.
+
+```bash
+npm run dev
+```
+
+Runtime checks are outside this skill.

package/skills/env-audit/failure-modes.md

@@ -0,0 +1,5 @@
+- **Adapter not enabled:** report `partial` and do not broaden target-project scanning.
+- **Secret-bearing path requested:** skip the file and record the safety exclusion.
+- **Dynamic variable names:** report as not verified instead of guessing.
+- **Large or unreadable files:** skip with consequence and continue bounded scanning.
+- **Credential validation requested:** refuse and explain that only names are in scope.

package/skills/route-trace/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: route-trace
+description: Trace statically visible application route surfaces without executing project code or changing state. Use when Codex must identify Next.js, API, React Router, Express/Fastify/Hono, or route-config surfaces from files before editing, reviewing, or planning route work; do not use for runtime URL probing, server execution, builds, tests, deployment checks, migrations, or runtime truth claims.
+---
+
+# Route Trace
+
+Identify route surfaces from static project files and emit an evidence-backed report. Remain audit-only and fail closed when route evidence would require execution or secret-bearing configuration.
+
+This skill must not change project files, Git state, dependencies, runtime state, services,
+databases, remotes, or deployment state.
+
+## Purpose And Use
+
+Use this skill to locate and classify statically visible routes before changing application code, reviewing API surfaces, or planning route-level work. It can identify verified route files and inferred route declarations, but it must not claim that a route works at runtime.
+
+Do not use this skill for live endpoint checks, server startup, browser tests, build verification, deployment readiness, migrations, database inspection, or secret auditing.
+
+## Inputs
+
+Require a project root or starting path. Optionally accept a project adapter, intended route area, maximum static scan depth, or named route framework to prioritize.
+
+Do not assume every route is statically discoverable, every route file is reachable in production, framework conventions are current, an adapter covers all route surfaces, or documentation route lists are authoritative.
+
+## 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 `route-trace`, stop static file reading and report the adapter-limited skip.
+4. Build the scan scope from adapter safe read paths when available; otherwise use a bounded generic static scan.
+5. Apply ignored paths and secret-file exclusions before reading any file.
+6. Identify verified route files from static conventions such as Next.js `app/` and `pages/` route files.
+7. Identify inferred route patterns from visible declarations such as React Router paths, Express/Fastify/Hono registrations, and route config objects.
+8. Label every finding as verified, inferred, skipped, not verified, or adapter-limited.
+9. Report skipped files, unverified runtime-dependent areas, branch state warnings, and safety refusals.
+10. Emit the shared evidence pack or route-trace 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, verified route files, inferred route patterns, skipped items, not-verified route classes, warnings, and changed-state declaration through the shared evidence-pack contract.
+
+Recover from missing adapters, unsupported frameworks, unreadable files, or ambiguous route declarations by narrowing scope and reporting uncertainty. Never recover by installing dependencies, running app code, starting servers, hitting URLs, broadening adapter scope, reading `.env`, or mutating files.
+
+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 verification.
+
+## Approval Boundary
+
+Explicit approval may permit one named non-secret static file read outside normal route paths. Approval does not permit package installation, builds, tests, runtime checks, server startup, URL probing, database inspection, migrations, deployments, Git mutation, or secret-file reads.
+
+## Completion
+
+Claim `complete` only when the declared static scan scope was inspected, route findings are labeled by evidence type, skipped and not-verified areas are recorded with consequences, adapter limitations are explicit, and no project, Git, dependency, runtime, service, or remote state changed.
+
+Report `partial`, `failed`, or `blocked` when adapter scope prevents route scanning, route evidence requires execution, the project root cannot be established, or safety exclusions prevent a requested conclusion. Never claim runtime availability or route correctness from static findings alone.
+
+These conditions are both the acceptance criteria and definition of done.

package/skills/route-trace/adapter-interface.md

@@ -0,0 +1,20 @@
+# Route Trace Adapter Interface
+
+Project adapters may enable `route-trace` only as an audit-only static inspection skill.
+
+Adapters may provide:
+
+- `safeReadPaths` for route-bearing source and route config files.
+- `ignoredPaths` for generated output, dependency folders, and non-route surfaces.
+- `documentationPrecedence` for route documentation that should be reviewed separately.
+- `requiredEvidence` such as route files inspected, adapter scope, skipped paths, and not-verified runtime classes.
+- `expectedPackageManagers` as metadata only.
+
+Adapters must not:
+
+- Add commands for `route-trace`.
+- Permit builds, tests, package installs, server startup, URL probing, deployment, migration, database inspection, or secret reads.
+- Remove inherited restrictions.
+- Change `route-trace` from `audit-only` to action-capable.
+- Expand scanning outside the declared project root without named approval.
+- Suppress skipped checks, warnings, uncertainty, or completion requirements.

package/skills/route-trace/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Route Trace"
+  short_description: "Trace static route surfaces without changing the project"
+  default_prompt: "Trace the statically visible route surfaces in this repository without modifying project, runtime, dependency, or external state."

package/skills/route-trace/checklist.md

@@ -0,0 +1,11 @@
+# Route Trace Checklist
+
+- Confirm project root and declared scope.
+- Validate any project adapter before consuming adapter metadata.
+- If the adapter is present but does not enable `route-trace`, stop and report the adapter-limited skip.
+- Build a bounded static scan scope from adapter safe paths or generic repository-local defaults.
+- Exclude `.env`, secret-bearing files, generated output, dependencies, and ignored paths.
+- Identify verified route files separately from inferred route declarations.
+- Record skipped paths and not-verified runtime-dependent route classes.
+- State that no server, build, test, runtime check, deployment, migration, package install, or secret read was performed.
+- Emit an evidence pack or route-trace report before claiming completion.

package/skills/route-trace/evidence-template.md

@@ -0,0 +1,18 @@
+# Route Trace Evidence Template
+
+Use the shared evidence-pack contract and include:
+
+- Skill: `route-trace`
+- Repository root, branch, HEAD, and working-tree state
+- User intent and declared route scope
+- Project adapter ID or `null`
+- Static scan scope and ignored paths
+- Verified route files with file paths and route patterns
+- Inferred route declarations with evidence file paths
+- Skipped paths with reasons and consequences
+- Not-verified runtime-dependent route classes
+- Safety refusals
+- Changed state: `false`
+- Recommended next action
+
+Completion requires evidence for both findings and boundaries. A static route trace is not runtime truth.

package/skills/route-trace/examples.md

@@ -0,0 +1,32 @@
+# Route Trace Examples
+
+## Safe
+
+- Inspect a repository for statically visible Next.js `app/` and `pages/` routes.
+- Trace route declarations in React Router config without running the app.
+- Identify Express, Fastify, or Hono-style route registrations from visible source files.
+- Report that a project adapter prevents route scanning because `route-trace` is not enabled.
+
+## Unsafe
+
+- Start a dev server to see which URLs respond.
+- Run browser tests or fetch live endpoints.
+- Read `.env` to determine route prefixes.
+- Run migrations, seed databases, deploy, or inspect production infrastructure.
+- Claim that a static route finding proves runtime availability.
+
+## Example Output Shape
+
+```text
+# Route Trace Report
+Status: complete
+
+## Verified Route Files
+- /api/users (next-app-api-route-file) in app/api/users/route.ts
+
+## Inferred Route Patterns
+- GET /health (express-style-route-registration) in server/routes.ts
+
+## Not Verified
+- runtime-generated routes
+```

package/skills/route-trace/failure-modes.md

@@ -0,0 +1,9 @@
+# Route Trace Failure Modes
+
+- **No project root**: stop with `failed`; do not search outside the declared scope.
+- **Malformed adapter**: stop with adapter validation failure; do not fall back to broader scanning.
+- **Adapter present but not enabled**: report `partial` with adapter-limited scope and no target-file reads.
+- **Unreadable or large files**: skip and record the consequence.
+- **Secret-bearing path**: skip; do not request contents unless the user gives a named-file approval and the file is non-secret.
+- **Runtime-dependent routing**: mark as not verified instead of running the app.
+- **Ambiguous route declaration**: label as inferred or unresolved; do not upgrade it to verified.

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

@@ -0,0 +1,56 @@
+{
+  "adapterId": "env-audit-fixture",
+  "adapterVersion": "1.0.0",
+  "project": {
+    "id": "env-audit-fixture",
+    "detection": {
+      "rootMarkers": [
+        {"kind": "file", "path": "package.json"},
+        {"kind": "file", "path": "README.md"}
+      ],
+      "maximumDepth": 1,
+      "scope": "declared-project-root",
+      "requireApprovalOutsideScope": true
+    }
+  },
+  "supportedSkills": [
+    {
+      "id": "env-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", "env names", "skipped secret paths"],
+    "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/env-audit/adapter-project/.coding-agent/skills.json

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

package/tests/fixtures/env-audit/adapter-project/README.md

@@ -0,0 +1,3 @@
+# Env Audit Adapter Fixture
+
+This fixture narrows env scanning to `src`.

package/tests/fixtures/env-audit/adapter-project/package.json

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