coding-agent-skills 0.2.12 → 0.2.13

package/scripts/test-pack.mjs

@@ -62,6 +62,11 @@ import {
   buildApiContractAuditReport,
   renderApiContractAuditReport,
 } from "./lib/api-contract-audit.mjs";
+import {
+  buildMigrationReviewReport,
+  migrationReviewCliResult,
+  renderMigrationReviewReport,
+} from "./lib/migration-review.mjs";
 import {
   adapterUpgradeCliResult,
   checkAdapterUpgrade,
@@ -280,6 +285,7 @@ test("local CLI maps approved commands to existing safe scripts", () => {
   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/render-migration-review.mjs"));
   assert.ok(cliText.includes("scripts/validate-adapters.mjs"));
   assert.ok(!cliText.includes(".env"));
 
@@ -317,6 +323,10 @@ test("local CLI maps approved commands to existing safe scripts", () => {
       ["api-contract-audit", path.join(fixtureRoot, "api-contract-audit", "static-project")],
       /# API Contract Audit Report/,
     ],
+    [
+      ["migration-review", path.join(fixtureRoot, "migration-review", "static-project")],
+      /# Migration Review Report/,
+    ],
   ];
 
   for (const [args, expected] of commands) {
@@ -341,7 +351,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.12");
+  assert.equal(packageJson.version, "0.2.13");
   assert.equal(
     packageJson.description,
     "Evidence-first, read-only coding-agent skills and project adapter tooling.",
@@ -357,6 +367,7 @@ test("npm package metadata is public-ready and dependency-free", () => {
     "env-audit",
     "secret-audit",
     "api-contract-audit",
+    "migration-review",
     "project-adapters",
     "code-validation",
     "cli",
@@ -650,6 +661,53 @@ test("api-contract-audit does not broaden a repo-map-only project adapter", () =
   assert.match(renderApiContractAuditReport(result), /api-contract-audit is not enabled/);
 });
 
+test("migration-review maps static migration surfaces without database access", () => {
+  const result = buildMigrationReviewReport(
+    path.join(root, "tests", "fixtures", "migration-review", "static-project"),
+    { coreRoot: root },
+  );
+
+  assert.equal(result.status, "complete");
+  assert.ok(result.migrationFiles.some((record) => record.path === "prisma/migrations/20260703010101_init/migration.sql"));
+  assert.ok(result.schemaFiles.some((record) => record.path === "prisma/schema.prisma"));
+  assert.ok(result.configFiles.some((record) => record.path === "drizzle.config.ts"));
+  assert.ok(result.packageScriptKeys.some((record) => record.key === "db:migrate"));
+  assert.ok(result.riskIndicators.some((record) => record.type === "drop-column"));
+  assert.match(renderMigrationReviewReport(result), /No database connection/);
+});
+
+test("migration-review respects adapter-declared scope", () => {
+  const result = buildMigrationReviewReport(
+    path.join(root, "tests", "fixtures", "migration-review", "adapter-project"),
+    { coreRoot: root },
+  );
+
+  assert.equal(result.status, "complete");
+  assert.equal(result.adapter.enabled, true);
+  assert.deepEqual(result.scopePaths, ["db"]);
+  assert.deepEqual(result.filesScanned, ["db/migrations/001_create_accounts.sql"]);
+  assert.ok(result.migrationFiles.some((record) => record.path === "db/migrations/001_create_accounts.sql"));
+  assert.ok(result.warnings.includes("migration-review used adapter-declared safe read paths only"));
+  const cli = migrationReviewCliResult(
+    path.join(root, "tests", "fixtures", "migration-review", "adapter-project"),
+    { coreRoot: root },
+  );
+  assert.equal(cli.exitCode, 0);
+  assert.match(cli.lines.join("\n"), /Migration-review enabled: yes/);
+});
+
+test("migration-review does not broaden a repo-map-only project adapter", () => {
+  const result = buildMigrationReviewReport(
+    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.migrationFiles.length, 0);
+  assert.match(renderMigrationReviewReport(result), /migration-review 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

@@ -99,6 +99,7 @@ const requiredRootFiles = [
   "scripts/render-env-audit.mjs",
   "scripts/render-secret-audit.mjs",
   "scripts/render-api-contract-audit.mjs",
+  "scripts/render-migration-review.mjs",
   "scripts/check-adapter-upgrade.mjs",
   "scripts/check-adapter-upgrade-chain.mjs",
   "scripts/validate-adapters.mjs",
@@ -108,6 +109,7 @@ const requiredRootFiles = [
   "scripts/lib/env-audit.mjs",
   "scripts/lib/secret-audit.mjs",
   "scripts/lib/api-contract-audit.mjs",
+  "scripts/lib/migration-review.mjs",
   "scripts/lib/adapter-upgrade.mjs",
   "scripts/lib/adapter-upgrade-chain.mjs",
   "scripts/lib/adapter-discovery.mjs",
@@ -681,8 +683,8 @@ if (packageJson) {
   if (packageJson.name !== "coding-agent-skills") {
     failures.push("package.json has unexpected package name");
   }
-  if (packageJson.version !== "0.2.12") {
-    failures.push("package.json version must be 0.2.12 for public package validation");
+  if (packageJson.version !== "0.2.13") {
+    failures.push("package.json version must be 0.2.13 for public package validation");
   }
   if (packageJson.type !== "module") failures.push("package.json must preserve ESM mode");
   if (packageJson.private !== false) {
@@ -704,6 +706,7 @@ if (packageJson) {
       "env-audit",
       "secret-audit",
       "api-contract-audit",
+      "migration-review",
       "project-adapters",
       "code-validation",
       "cli",

package/skills/migration-review/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: migration-review
+description: Review statically visible database migration and schema evidence without connecting to databases, applying migrations, generating ORM clients, or modifying projects. Use when Codex must map migration files, schema/config files, migration-related package script keys, and static risk indicators before database work or handoff; do not use for runtime database inspection, migration execution, deploys, builds, tests, package installs, or secret-file reads.
+---
+
+# Migration Review
+
+Map statically visible migration evidence and report what is and is not verified. Remain
+audit-only and avoid turning migration discovery into database or deployment work.
+
+This skill must not change project files, Git state, dependencies, runtime state, services,
+databases, remotes, generated ORM clients, or deployment state.
+
+## Purpose And Use
+
+Use this skill before database work, migration handoff, or schema review when the agent needs
+to understand visible migration files, schema declarations, migration config, and static
+risk indicators.
+
+Do not use it to prove database state, apply or roll back migrations, inspect deployed
+databases, generate ORM clients, build, test, deploy, run package scripts, or read secrets.
+
+## Inputs
+
+Require a project root or starting path. Optionally accept a project adapter, intended scan
+area, documentation precedence, migration directory hints, or known ORM/database boundaries.
+
+Do not assume a missing migration directory means no database exists, migration filenames
+reflect applied state, schema files match production, package script keys are safe to run, 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 `migration-review`, 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 migration files and migration directories.
+7. Identify schema and migration config files.
+8. Identify package script keys that mention migration tools without printing command values.
+9. Identify static risk indicators such as drop-column, truncate, rename, or raw data update
+   patterns without judging runtime safety.
+10. Emit the shared evidence pack or migration review 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, migration
+files, schema files, config files, package script keys, risk indicators, skipped items,
+not-verified areas, warnings, and changed-state declaration through the shared evidence-pack
+contract.
+
+Recover from missing migration directories, ambiguous ORM layouts, unreadable files, or
+adapter limits by reporting uncertainty. Never recover by connecting to a database, applying
+migrations, generating ORM clients, installing dependencies, building, testing, deploying,
+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 database 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, database connections, migration
+execution, ORM generation, package installation, builds, tests, runtime checks, deployments,
+Git mutation, or project writes.
+
+## Completion
+
+Claim `complete` only when the declared static scan scope was inspected, visible migration
+surfaces are reported, skipped and not-verified areas are explicit, adapter limitations are
+clear, and no project, Git, dependency, runtime, service, database, remote, generated-code, or
+deployment state changed.
+
+Report `partial`, `failed`, or `blocked` when adapter scope prevents scanning, requested
+evidence requires database/runtime 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/migration-review/adapter-interface.md

@@ -0,0 +1,16 @@
+Adapters may enable `migration-review` only as an audit-only static inspection skill.
+
+Allowed adapter extensions:
+
+- `safeReadPaths` for migration, schema, config, and relevant package files.
+- `ignoredPaths` for generated, dependency, build, coverage, and output directories.
+- `documentationPrecedence` for migration runbooks or schema docs.
+- `requiredEvidence` for migration files, schemas, config, risk indicators, and not-verified areas.
+
+Adapters must not:
+
+- Add commands for `migration-review`.
+- Require database connections, migration execution, ORM generation, or package scripts.
+- Include `.env`, credential, service-key, or secret-bearing paths.
+- Change `migration-review` from `audit-only` to action-capable.
+- Expand scope outside the declared project root without named approval.

package/skills/migration-review/agents/openai.yaml

@@ -0,0 +1,3 @@
+display_name: Migration Review
+short_description: Review static migration and schema evidence without database access.
+default_prompt: Review this repository's migration and schema evidence as an audit-only pass without modifying files, applying migrations, connecting to databases, generating ORM clients, or reading secrets.

package/skills/migration-review/checklist.md

@@ -0,0 +1,8 @@
+- 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 `migration-review`.
+- Exclude `.env`, secret-bearing, dependency, generated, output, and oversized files.
+- Report migration files, schema files, config files, package script keys, and risk indicators.
+- Do not print package script command values.
+- Record not-verified database state, rollback, generated-client, and production gaps.
+- Declare that no database connection, migration execution, ORM generation, build, test, deploy, package install, secret read, or write occurred.

package/skills/migration-review/evidence-template.md

@@ -0,0 +1,12 @@
+Evidence fields:
+
+- Project root and Git branch state.
+- Adapter presence, enabled state, and scope paths.
+- Ignored paths and skipped static files.
+- Migration files and reasons.
+- Schema files and reasons.
+- Migration config files and reasons.
+- Package script keys, without command values.
+- Static risk indicators by file and type.
+- Not-verified database, rollback, generated-client, and production areas.
+- Refused behavior and changed-state declaration.

package/skills/migration-review/examples.md

@@ -0,0 +1,20 @@
+Safe examples:
+
+```bash
+coding-agent-skills migration-review /workspace/app
+```
+
+```bash
+node scripts/render-migration-review.mjs tests/fixtures/migration-review/static-project
+```
+
+Expected result: a report listing static migration files, schema/config files, package
+script keys, risk indicators, skipped paths, not-verified database behavior, and refused
+actions.
+
+## Unsafe Examples
+
+- Apply database migrations.
+- Connect to a local or remote database to inspect applied state.
+- Generate ORM clients or migration files.
+- Read `.env`, credentials, service keys, or private runtime config.

package/skills/migration-review/failure-modes.md

@@ -0,0 +1,5 @@
+- Missing migration directories: report uncertainty instead of assuming no database exists.
+- Adapter present without `migration-review`: return `partial` and read no target files.
+- Secret-bearing paths: skip and record the exclusion without printing values.
+- Destructive-looking SQL: report the static indicator without judging production safety.
+- Requested database state or rollback proof: stop at the approval boundary because this skill is static only.

package/tests/fixtures/migration-review/adapter-project/.coding-agent/adapters/migration-review-fixture/adapter.json

@@ -0,0 +1,56 @@
+{
+  "adapterId": "migration-review-fixture",
+  "adapterVersion": "1.0.0",
+  "project": {
+    "id": "fixture-migration-review",
+    "detection": {
+      "rootMarkers": [
+        {"kind": "file", "path": "package.json"},
+        {"kind": "file", "path": "README.md"}
+      ],
+      "maximumDepth": 1,
+      "scope": "declared-project-root",
+      "requireApprovalOutsideScope": true
+    }
+  },
+  "supportedSkills": [
+    {
+      "id": "migration-review",
+      "compatibleVersions": ["0.2.3", "0.2.x"],
+      "declaredMode": "audit-only"
+    }
+  ],
+  "extensions": {
+    "safeReadPaths": ["db"],
+    "ignoredPaths": ["ignored", "node_modules", "dist", "build"],
+    "documentationPrecedence": ["README.md"],
+    "commandAliases": [],
+    "safeStatusCommands": [],
+    "requiredEvidence": ["project root", "adapter scope", "migration files", "not-verified database 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/migration-review/adapter-project/.coding-agent/skills.json

@@ -0,0 +1,23 @@
+{
+  "declarationVersion": "1.0.0",
+  "projectId": "fixture-migration-review",
+  "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": ["migration-review"],
+  "adapters": [
+    {
+      "id": "migration-review-fixture",
+      "version": "1.0.0",
+      "skillIds": ["migration-review"]
+    }
+  ],
+  "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/migration-review/adapter-project/README.md

@@ -0,0 +1,3 @@
+# Adapter Migration Fixture
+
+Synthetic adapter-scoped migration fixture.

package/tests/fixtures/migration-review/adapter-project/db/migrations/001_create_accounts.sql

@@ -0,0 +1,3 @@
+CREATE TABLE accounts (
+  id text PRIMARY KEY
+);

package/tests/fixtures/migration-review/adapter-project/ignored/migrations/999_ignore.sql

@@ -0,0 +1 @@
+DROP TABLE ignored_table;

package/tests/fixtures/migration-review/adapter-project/package.json

@@ -0,0 +1,3 @@
+{
+  "name": "fixture-migration-review-adapter"
+}

package/tests/fixtures/migration-review/static-project/README.md

@@ -0,0 +1,3 @@
+# Migration Review Fixture
+
+Synthetic static migration fixture.

package/tests/fixtures/migration-review/static-project/drizzle.config.ts

@@ -0,0 +1,4 @@
+export default {
+  schema: "./src/db/schema.ts",
+  out: "./drizzle",
+};

package/tests/fixtures/migration-review/static-project/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "fixture-migration-review-static",
+  "scripts": {
+    "db:migrate": "prisma migrate deploy",
+    "db:generate": "prisma generate"
+  }
+}

package/tests/fixtures/migration-review/static-project/prisma/migrations/20260703010101_init/migration.sql

@@ -0,0 +1,6 @@
+CREATE TABLE "User" (
+  "id" text PRIMARY KEY,
+  "email" text NOT NULL
+);
+
+ALTER TABLE "User" DROP COLUMN "legacyName";

package/tests/fixtures/migration-review/static-project/prisma/schema.prisma

@@ -0,0 +1,4 @@
+model User {
+  id    String @id
+  email String @unique
+}

package/tests/fixtures/triggers/cases.json

@@ -67,6 +67,18 @@
       "expectedSkill": "api-contract-audit",
       "notSkills": ["build-verify", "llm-drift-control"]
     },
+    {
+      "id": "migration-review-static",
+      "prompt": "Review database migrations and schema files without connecting to the database.",
+      "expectedSkill": "migration-review",
+      "notSkills": ["runtime-truth", "build-verify"]
+    },
+    {
+      "id": "migration-review-rollback",
+      "prompt": "Map Prisma migrations and rollback review concerns from static files before handoff.",
+      "expectedSkill": "migration-review",
+      "notSkills": ["deployment-preflight", "runtime-truth"]
+    },
     {
       "id": "build-after-implementation",
       "prompt": "The implementation is finished. Run the existing typecheck, tests, and build.",
@@ -119,7 +131,7 @@
       "id": "negative-deploy",
       "prompt": "Deploy this application to production.",
       "expectedSkill": null,
-      "notSkills": ["repo-map", "route-trace", "env-audit", "secret-audit", "api-contract-audit", "build-verify", "git-preflight", "runtime-truth", "llm-drift-control"]
+      "notSkills": ["repo-map", "route-trace", "env-audit", "secret-audit", "api-contract-audit", "migration-review", "build-verify", "git-preflight", "runtime-truth", "llm-drift-control"]
     },
     {
       "id": "negative-install",

package/tests/trigger/README.md

@@ -10,6 +10,8 @@
   environment variable mapping or runtime truth.
 - Static API contract mapping must trigger `api-contract-audit`, not runtime truth or
   build verification.
+- Static migration/schema review must trigger `migration-review`, not runtime truth,
+  deployment, or migration execution.
 - 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,13 +4,13 @@
 
 - Repository: `coding-agent-skills`
 - Branch: `main`
-- Pilot skills: `repo-map`, `route-trace`, `env-audit`, `secret-audit`, `api-contract-audit`, `build-verify`, `git-preflight`, `runtime-truth`, `llm-drift-control`
+- Pilot skills: `repo-map`, `route-trace`, `env-audit`, `secret-audit`, `api-contract-audit`, `migration-review`, `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.12` exposes the dependency-free
+- Public npm package release `v0.2.13` 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
@@ -18,19 +18,21 @@
 - `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.
+- `migration-review` is implemented as an audit-only static migration and schema evidence
+  review 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.12`
+`v0.2.13`
 
 ## Current Recommended Milestone
 
-The `api-contract-audit` public npm release is in progress under builder-mode approval.
+The `migration-review` 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`.
+`github-handoff-skill`.
 
 ## Allowed Next Actions
 
@@ -102,6 +104,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.12`
+- Implemented milestone: `migration-review` audit-only static migration and schema evidence review 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 `github-handoff-skill`
+  after `v0.2.13` publication completes.
+
+
 ### 2026-07-03T12:00:00Z
 
 - Latest tag observed: `v0.2.11`