coding-agent-skills 0.2.13 → 0.2.14

package/scripts/lib/github-handoff.mjs

@@ -0,0 +1,446 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  ADAPTER_MANIFEST_FILENAME,
+  readSafeJsonFile,
+} from "./adapter-discovery.mjs";
+import { PILOT_VERSION } from "./pack-rules.mjs";
+import {
+  readProjectAdapterDeclaration,
+  validateProjectAdapters,
+} from "./project-adapter-installation.mjs";
+
+const DEFAULT_CORE_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "..",
+);
+
+const SKILL_ID = "github-handoff";
+
+const REFUSED_BEHAVIOR = [
+  "no commits",
+  "no pushes",
+  "no tags",
+  "no branch changes",
+  "no pull request creation",
+  "no GitHub API mutations",
+  "no token reads",
+  "no secret-file reads",
+  "no project writes",
+];
+
+const NOT_VERIFIED = [
+  "remote repository permissions",
+  "GitHub pull request state",
+  "GitHub issue state",
+  "GitHub Actions or CI status",
+  "whether local commits have been pushed",
+  "reviewer assignment or approval state",
+  "release publication state",
+];
+
+function inside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function toPosix(relativePath) {
+  return relativePath.split(path.sep).join("/");
+}
+
+function safeRelativePath(candidate) {
+  return (
+    typeof candidate === "string" &&
+    candidate.length > 0 &&
+    !candidate.startsWith("/") &&
+    !candidate.split(/[\\/]+/).includes("..")
+  );
+}
+
+function secretBearingPath(relativePath) {
+  const normalized = toPosix(relativePath);
+  const basename = path.posix.basename(normalized);
+  return (
+    basename === ".env" ||
+    basename.startsWith(".env.") ||
+    basename === ".npmrc" ||
+    /\.(?:pem|key|p12|pfx)$/i.test(basename) ||
+    /(?:^|\/)(?:secrets?|credentials?|private-key|service-role|tokens?)(?:\/|$)/i.test(normalized)
+  );
+}
+
+function runGit(projectRoot, args) {
+  const result = spawnSync("git", args, {
+    cwd: projectRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  return {
+    ok: result.status === 0,
+    stdout: result.stdout.trim(),
+  };
+}
+
+function parseStatusEntry(line) {
+  const code = line.slice(0, 2);
+  const rawPath = line.slice(3).trim();
+  const paths = rawPath.split(" -> ");
+  const redacted = paths.some(secretBearingPath);
+  return {
+    code,
+    path: redacted ? "[REDACTED:secret-bearing-path]" : rawPath,
+    redacted,
+    category: categorizeStatus(code),
+  };
+}
+
+function categorizeStatus(code) {
+  if (code.includes("U") || code === "AA" || code === "DD") return "conflicted";
+  if (code === "??") return "untracked";
+  if (code.includes("A")) return "added";
+  if (code.includes("D")) return "deleted";
+  if (code.includes("R")) return "renamed";
+  if (code.includes("C")) return "copied";
+  if (code.includes("M")) return "modified";
+  return "other";
+}
+
+function summarizeChanges(entries) {
+  const summary = {
+    total: entries.length,
+    added: 0,
+    copied: 0,
+    deleted: 0,
+    modified: 0,
+    renamed: 0,
+    untracked: 0,
+    conflicted: 0,
+    other: 0,
+    redacted: 0,
+  };
+  for (const entry of entries) {
+    summary[entry.category] += 1;
+    if (entry.redacted) summary.redacted += 1;
+  }
+  return summary;
+}
+
+function gitSummary(projectRoot) {
+  const summary = {
+    isGitRepo: false,
+    root: null,
+    branchState: null,
+    branch: null,
+    head: null,
+    headShort: null,
+    headSubject: null,
+    tagsAtHead: [],
+    remoteNames: [],
+    changedFiles: [],
+    changeSummary: summarizeChanges([]),
+    warnings: [],
+  };
+
+  const revParse = runGit(projectRoot, ["rev-parse", "--show-toplevel"]);
+  if (!revParse.ok) {
+    summary.warnings.push("git repository not detected");
+    return summary;
+  }
+  summary.isGitRepo = true;
+  summary.root = revParse.stdout;
+
+  const status = runGit(projectRoot, ["status", "--short", "--branch"]);
+  if (!status.ok) {
+    summary.warnings.push("git status unavailable");
+  } else {
+    const lines = status.stdout.split(/\r?\n/).filter(Boolean);
+    summary.branchState = lines[0] ?? null;
+    summary.changedFiles = lines.slice(1).map(parseStatusEntry);
+    summary.changeSummary = summarizeChanges(summary.changedFiles);
+    if (summary.changedFiles.length) summary.warnings.push("working tree has local changes");
+    if (summary.changeSummary.redacted) {
+      summary.warnings.push("one or more changed paths were redacted because they look secret-bearing");
+    }
+    if (/\[(?:ahead|behind|gone|diverged)[^\]]*\]/i.test(summary.branchState ?? "")) {
+      summary.warnings.push("branch state indicates remote divergence; revalidate before handoff");
+    }
+  }
+
+  const branch = runGit(projectRoot, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  if (branch.ok) summary.branch = branch.stdout;
+
+  const head = runGit(projectRoot, ["rev-parse", "HEAD"]);
+  if (head.ok) {
+    summary.head = head.stdout;
+    summary.headShort = head.stdout.slice(0, 12);
+  }
+
+  const subject = runGit(projectRoot, ["log", "-1", "--format=%s"]);
+  if (subject.ok) summary.headSubject = subject.stdout;
+
+  const tags = runGit(projectRoot, ["tag", "--points-at", "HEAD"]);
+  if (tags.ok) summary.tagsAtHead = tags.stdout ? tags.stdout.split(/\r?\n/).filter(Boolean).sort() : [];
+
+  const remotes = runGit(projectRoot, ["remote"]);
+  if (remotes.ok) summary.remoteNames = remotes.stdout ? remotes.stdout.split(/\r?\n/).filter(Boolean).sort() : [];
+
+  return summary;
+}
+
+function adapterContext(projectRootInput, coreRoot) {
+  const loaded = readProjectAdapterDeclaration(projectRootInput);
+  if (!loaded.ok) {
+    if (loaded.codes.length === 1 && loaded.codes[0] === "missing-project-declaration") {
+      return {
+        ok: true,
+        present: false,
+        enabled: false,
+        projectRoot: path.resolve(projectRootInput),
+        mode: "none",
+        codes: [],
+      };
+    }
+    return { ok: false, present: false, enabled: false, status: "failed", codes: loaded.codes };
+  }
+
+  const validation = validateProjectAdapters(loaded.projectRoot, { coreRoot });
+  if (!validation.ok) {
+    return {
+      ok: false,
+      present: true,
+      enabled: false,
+      status: "failed",
+      codes: validation.codes,
+      validation,
+    };
+  }
+
+  if (!validation.acceptedSkills.includes(SKILL_ID)) {
+    return {
+      ok: true,
+      present: true,
+      enabled: false,
+      projectRoot: loaded.projectRoot,
+      mode: "adapter-present-github-handoff-not-enabled",
+      declarationPath: loaded.declarationPath,
+      declaration: loaded.declaration,
+      validation,
+      codes: [`${SKILL_ID}-not-enabled-by-adapter`],
+    };
+  }
+
+  const adapters = [];
+  const errors = [];
+  const container = path.resolve(loaded.projectRoot, loaded.declaration.adapterRoot);
+  if (!inside(loaded.projectRoot, container) || !fs.existsSync(container)) {
+    errors.push("adapter-root-not-found");
+  } else {
+    for (const declaration of loaded.declaration.adapters ?? []) {
+      if (!(declaration.skillIds ?? []).includes(SKILL_ID)) continue;
+      const manifestPath = path.join(container, declaration.id, ADAPTER_MANIFEST_FILENAME);
+      const record = readSafeJsonFile(manifestPath);
+      if (!record.value) {
+        errors.push(...record.codes);
+        continue;
+      }
+      adapters.push({
+        declaration,
+        manifestPath: path.relative(loaded.projectRoot, manifestPath),
+        manifest: record.value,
+      });
+    }
+  }
+  if (errors.length) {
+    return { ok: false, present: true, enabled: false, status: "failed", codes: errors, validation };
+  }
+  return {
+    ok: true,
+    present: true,
+    enabled: true,
+    projectRoot: loaded.projectRoot,
+    mode: "adapter-enabled",
+    declarationPath: loaded.declarationPath,
+    declaration: loaded.declaration,
+    validation,
+    adapters,
+    codes: [],
+  };
+}
+
+function adapterEvidence(context) {
+  const ignoredPaths = new Set([".git", "node_modules", "dist", "build", "coverage", "validation-output"]);
+  const requiredEvidence = new Set(["branch state", "HEAD", "working-tree state", "changed-file summary"]);
+  for (const adapter of context.adapters ?? []) {
+    for (const candidate of adapter.manifest.extensions?.ignoredPaths ?? []) {
+      if (safeRelativePath(candidate)) ignoredPaths.add(candidate);
+    }
+    for (const candidate of adapter.manifest.extensions?.requiredEvidence ?? []) {
+      if (typeof candidate === "string" && candidate.trim()) requiredEvidence.add(candidate);
+    }
+  }
+  return {
+    ignoredPaths: [...ignoredPaths].sort(),
+    requiredEvidence: [...requiredEvidence].sort(),
+  };
+}
+
+export function buildGithubHandoffReport(projectRootInput, options = {}) {
+  const coreRoot = options.coreRoot ?? DEFAULT_CORE_ROOT;
+  const context = adapterContext(projectRootInput, coreRoot);
+  const projectRoot = context.projectRoot ?? path.resolve(projectRootInput ?? ".");
+  const git = gitSummary(projectRoot);
+  const base = {
+    coreVersion: PILOT_VERSION,
+    projectRoot,
+    adapter: context,
+    git,
+    ignoredPaths: [".git", "node_modules", "dist", "build", "coverage", "validation-output"],
+    requiredEvidence: ["branch state", "HEAD", "working-tree state", "changed-file summary"],
+    changedFiles: [],
+    changeSummary: summarizeChanges([]),
+    skipped: [],
+    warnings: [...git.warnings],
+    notVerified: NOT_VERIFIED,
+    refusedBehavior: REFUSED_BEHAVIOR,
+  };
+
+  if (!context.ok) {
+    return {
+      ...base,
+      status: "failed",
+      warnings: [...(context.codes ?? []), ...git.warnings],
+    };
+  }
+
+  if (!git.isGitRepo) {
+    return {
+      ...base,
+      status: "failed",
+      skipped: [{ path: ".", reason: "project root is not a Git repository" }],
+    };
+  }
+
+  if (context.present && !context.enabled) {
+    return {
+      ...base,
+      status: "partial",
+      skipped: [{ path: ".", reason: "project adapter is present but does not enable github-handoff" }],
+      warnings: [
+        "github-handoff is not enabled by the project adapter; changed-file details were not listed",
+        ...git.warnings,
+      ],
+    };
+  }
+
+  const evidence = context.enabled ? adapterEvidence(context) : {
+    ignoredPaths: base.ignoredPaths,
+    requiredEvidence: base.requiredEvidence,
+  };
+
+  return {
+    ...base,
+    status: "complete",
+    ignoredPaths: evidence.ignoredPaths,
+    requiredEvidence: evidence.requiredEvidence,
+    changedFiles: git.changedFiles,
+    changeSummary: git.changeSummary,
+    warnings: [
+      ...git.warnings,
+      ...(context.enabled ? ["github-handoff used adapter-declared handoff evidence metadata"] : []),
+      "remote URLs were not printed to avoid credential exposure",
+    ],
+  };
+}
+
+function listOrNone(items) {
+  return items.length ? items.join(", ") : "none";
+}
+
+function renderChangeSummary(summary) {
+  return [
+    `- Total changed entries: ${summary.total}`,
+    `- Added: ${summary.added}`,
+    `- Modified: ${summary.modified}`,
+    `- Deleted: ${summary.deleted}`,
+    `- Renamed: ${summary.renamed}`,
+    `- Copied: ${summary.copied}`,
+    `- Untracked: ${summary.untracked}`,
+    `- Conflicted: ${summary.conflicted}`,
+    `- Redacted paths: ${summary.redacted}`,
+  ];
+}
+
+export function renderGithubHandoffReport(report) {
+  const lines = [
+    "# GitHub Handoff Report",
+    "",
+    `Status: ${report.status}`,
+    `Core version: ${report.coreVersion}`,
+    `Project root: ${report.projectRoot}`,
+    "",
+    "## Git State",
+    `- Git root: ${report.git.root ?? "not detected"}`,
+    `- Branch state: ${report.git.branchState ?? "not detected"}`,
+    `- Current branch: ${report.git.branch ?? "not detected"}`,
+    `- HEAD: ${report.git.headShort ?? "not detected"}`,
+    `- HEAD subject: ${report.git.headSubject ?? "not detected"}`,
+    `- Tags at HEAD: ${listOrNone(report.git.tagsAtHead)}`,
+    `- Remote names: ${listOrNone(report.git.remoteNames)}`,
+    "",
+    "## Adapter Scope",
+    `- Adapter present: ${report.adapter.present ? "yes" : "no"}`,
+    `- Github-handoff enabled: ${report.adapter.enabled ? "yes" : "no"}`,
+    `- Mode: ${report.adapter.mode ?? "unknown"}`,
+    "",
+    "## Required Evidence",
+    ...report.requiredEvidence.map((item) => `- ${item}`),
+    "",
+    "## Ignored Paths",
+    ...report.ignoredPaths.map((item) => `- ${item}`),
+    "",
+    "## Change Summary",
+    ...renderChangeSummary(report.changeSummary),
+    "",
+    "## Changed Files",
+  ];
+
+  if (report.changedFiles.length) {
+    for (const entry of report.changedFiles) {
+      lines.push(`- ${entry.code} ${entry.path}`);
+    }
+  } else {
+    lines.push("- none listed");
+  }
+
+  lines.push(
+    "",
+    "## Skipped",
+    ...(report.skipped.length ? report.skipped.map((item) => `- ${item.path}: ${item.reason}`) : ["- none"]),
+    "",
+    "## Not Verified",
+    ...report.notVerified.map((item) => `- ${item}`),
+    "",
+    "## Warnings",
+    ...(report.warnings.length ? report.warnings.map((item) => `- ${item}`) : ["- none"]),
+    "",
+    "## Refused Behavior",
+    ...report.refusedBehavior.map((item) => `- ${item}`),
+    "",
+    "No commit, push, tag, branch change, pull request creation, GitHub API mutation, token read, secret-file read, or project write was performed.",
+  );
+
+  return `${lines.join("\n")}\n`;
+}
+
+export function githubHandoffCliResult(projectRootInput, options = {}) {
+  const report = buildGithubHandoffReport(projectRootInput, options);
+  return {
+    exitCode: report.status === "failed" ? 1 : 0,
+    report,
+    lines: renderGithubHandoffReport(report).trimEnd().split("\n"),
+  };
+}

package/scripts/lib/pack-rules.mjs

@@ -5,6 +5,7 @@ export const PILOT_SKILLS = [
   "secret-audit",
   "api-contract-audit",
   "migration-review",
+  "github-handoff",
   "build-verify",
   "git-preflight",
   "runtime-truth",
@@ -21,6 +22,7 @@ export const AUDIT_ONLY_SKILLS = [
   "secret-audit",
   "api-contract-audit",
   "migration-review",
+  "github-handoff",
   "git-preflight",
   "runtime-truth",
   "llm-drift-control",
@@ -407,6 +409,13 @@ export function classifyTrigger(prompt) {
   ) {
     return "migration-review";
   }
+  if (
+    /\b(?:github handoff|handoff report|handoff evidence|pull request handoff|pr handoff|changed files summary|git handoff|release handoff)\b/.test(
+      text,
+    )
+  ) {
+    return "github-handoff";
+  }
   if (
     /\b(?:unfamiliar repository|canonical repository root|canonical repo|map the current packages|map this repository|identify its entry points|nested directory)\b/.test(
       text,
@@ -548,7 +557,7 @@ function classifySegment(segment, options = {}) {
   }
   if (
     executable === "node" &&
-    !/^node\s+(?:--check\b|--test\b|scripts\/(?:validate-pack|validate-maintainer-loop|validate-adapters|validate-project-adapters|check-adapter-upgrade|check-adapter-upgrade-chain|verify-evidence-bundle|render-evidence-archive-report|render-adapter-repo-map|render-route-trace|render-env-audit|render-secret-audit|render-api-contract-audit|render-migration-review|test-pack)\.mjs\b)/.test(
+    !/^node\s+(?:--check\b|--test\b|scripts\/(?:validate-pack|validate-maintainer-loop|validate-adapters|validate-project-adapters|check-adapter-upgrade|check-adapter-upgrade-chain|verify-evidence-bundle|render-evidence-archive-report|render-adapter-repo-map|render-route-trace|render-env-audit|render-secret-audit|render-api-contract-audit|render-migration-review|render-github-handoff|test-pack)\.mjs\b)/.test(
       segment,
     )
   ) {
@@ -558,7 +567,7 @@ function classifySegment(segment, options = {}) {
     ["coding-agent-skills", "bin/coding-agent-skills", "./bin/coding-agent-skills"].includes(
       executable,
     ) &&
-    !/^(?:\.\/)?(?:bin\/)?coding-agent-skills\s+(?:validate-pack|validate-project\s+\S+|repo-map\s+\S+|route-trace\s+\S+|env-audit\s+\S+|secret-audit\s+\S+|api-contract-audit\s+\S+|migration-review\s+\S+|validate-adapters\s+\S+|help|--help|-h)\s*$/.test(
+    !/^(?:\.\/)?(?:bin\/)?coding-agent-skills\s+(?:validate-pack|validate-project\s+\S+|repo-map\s+\S+|route-trace\s+\S+|env-audit\s+\S+|secret-audit\s+\S+|api-contract-audit\s+\S+|migration-review\s+\S+|github-handoff\s+\S+|validate-adapters\s+\S+|help|--help|-h)\s*$/.test(
       segment,
     )
   ) {

package/scripts/render-github-handoff.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { githubHandoffCliResult } from "./lib/github-handoff.mjs";
+
+const projectRoot = process.argv[2];
+const result = githubHandoffCliResult(projectRoot);
+process.stdout.write(`${result.lines.join("\n")}\n`);
+process.exitCode = result.exitCode;

package/scripts/test-pack.mjs

@@ -67,6 +67,11 @@ import {
   migrationReviewCliResult,
   renderMigrationReviewReport,
 } from "./lib/migration-review.mjs";
+import {
+  buildGithubHandoffReport,
+  githubHandoffCliResult,
+  renderGithubHandoffReport,
+} from "./lib/github-handoff.mjs";
 import {
   adapterUpgradeCliResult,
   checkAdapterUpgrade,
@@ -133,6 +138,27 @@ function readJson(relativePath) {
   return JSON.parse(read(relativePath));
 }
 
+function runGitFixtureCommand(cwd, args) {
+  const result = spawnSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    stdio: "pipe",
+  });
+  assert.equal(result.status, 0, `git ${args.join(" ")}\n${result.stderr}`);
+  return result.stdout.trim();
+}
+
+function createGitFixture(sourceRelativePath) {
+  const temporary = fs.mkdtempSync(path.join(os.tmpdir(), "github-handoff-fixture-"));
+  fs.cpSync(path.join(root, sourceRelativePath), temporary, { recursive: true });
+  runGitFixtureCommand(temporary, ["init", "-b", "main"]);
+  runGitFixtureCommand(temporary, ["config", "user.name", "Fixture User"]);
+  runGitFixtureCommand(temporary, ["config", "user.email", "fixture@example.invalid"]);
+  runGitFixtureCommand(temporary, ["add", "."]);
+  runGitFixtureCommand(temporary, ["commit", "-m", "initial fixture commit"]);
+  return temporary;
+}
+
 function walk(directory, output = []) {
   for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
     if ([".git", "node_modules", "validation-output"].includes(entry.name)) continue;
@@ -286,10 +312,16 @@ test("local CLI maps approved commands to existing safe scripts", () => {
   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/render-github-handoff.mjs"));
   assert.ok(cliText.includes("scripts/validate-adapters.mjs"));
   assert.ok(!cliText.includes(".env"));
 
   const fixtureRoot = path.join(root, "tests", "fixtures");
+  const githubHandoffFixture = createGitFixture(
+    path.join("tests", "fixtures", "github-handoff", "static-project"),
+  );
+  fs.appendFileSync(path.join(githubHandoffFixture, "README.md"), "\nLocal handoff change.\n");
+
   const commands = [
     [["validate-pack"], /pilot pack valid/],
     [
@@ -327,6 +359,10 @@ test("local CLI maps approved commands to existing safe scripts", () => {
       ["migration-review", path.join(fixtureRoot, "migration-review", "static-project")],
       /# Migration Review Report/,
     ],
+    [
+      ["github-handoff", githubHandoffFixture],
+      /# GitHub Handoff Report/,
+    ],
   ];
 
   for (const [args, expected] of commands) {
@@ -351,7 +387,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.13");
+  assert.equal(packageJson.version, "0.2.14");
   assert.equal(
     packageJson.description,
     "Evidence-first, read-only coding-agent skills and project adapter tooling.",
@@ -368,6 +404,7 @@ test("npm package metadata is public-ready and dependency-free", () => {
     "secret-audit",
     "api-contract-audit",
     "migration-review",
+    "github-handoff",
     "project-adapters",
     "code-validation",
     "cli",
@@ -708,6 +745,57 @@ test("migration-review does not broaden a repo-map-only project adapter", () =>
   assert.match(renderMigrationReviewReport(result), /migration-review is not enabled/);
 });
 
+test("github-handoff summarizes local git state without mutating remotes", () => {
+  const fixture = createGitFixture(path.join("tests", "fixtures", "github-handoff", "static-project"));
+  runGitFixtureCommand(fixture, ["tag", "v0.0.0"]);
+  fs.appendFileSync(path.join(fixture, "README.md"), "\nChanged for handoff.\n");
+  fs.writeFileSync(path.join(fixture, "src", "new-file.js"), "export const handoff = true;\n");
+
+  const result = buildGithubHandoffReport(fixture, { coreRoot: root });
+
+  assert.equal(result.status, "complete");
+  assert.equal(result.git.branch, "main");
+  assert.ok(result.git.head);
+  assert.ok(result.git.tagsAtHead.includes("v0.0.0"));
+  assert.equal(result.changeSummary.total, 2);
+  assert.equal(result.changeSummary.modified, 1);
+  assert.equal(result.changeSummary.untracked, 1);
+  assert.ok(result.changedFiles.some((record) => record.path === "README.md"));
+  assert.ok(result.changedFiles.some((record) => record.path === "src/new-file.js"));
+  assert.match(renderGithubHandoffReport(result), /No commit, push, tag/);
+});
+
+test("github-handoff respects adapter-declared handoff metadata", () => {
+  const fixture = createGitFixture(path.join("tests", "fixtures", "github-handoff", "adapter-project"));
+  fs.appendFileSync(path.join(fixture, "src", "index.js"), "\nexport const changed = true;\n");
+
+  const result = buildGithubHandoffReport(fixture, { coreRoot: root });
+
+  assert.equal(result.status, "complete");
+  assert.equal(result.adapter.enabled, true);
+  assert.ok(result.requiredEvidence.includes("handoff summary"));
+  assert.ok(result.ignoredPaths.includes("tmp"));
+  assert.equal(result.changeSummary.modified, 1);
+  assert.ok(result.warnings.includes("github-handoff used adapter-declared handoff evidence metadata"));
+  const cli = githubHandoffCliResult(fixture, { coreRoot: root });
+  assert.equal(cli.exitCode, 0);
+  assert.match(cli.lines.join("\n"), /Github-handoff enabled: yes/);
+});
+
+test("github-handoff does not broaden a repo-map-only project adapter", () => {
+  const fixture = createGitFixture(
+    path.join("tests", "fixtures", "project-adapter-installation", "valid-exact-pin"),
+  );
+  fs.appendFileSync(path.join(fixture, "README.md"), "\nShould not be listed.\n");
+
+  const result = buildGithubHandoffReport(fixture, { coreRoot: root });
+
+  assert.equal(result.status, "partial");
+  assert.equal(result.changedFiles.length, 0);
+  assert.equal(result.changeSummary.total, 0);
+  assert.match(renderGithubHandoffReport(result), /github-handoff 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

@@ -100,6 +100,7 @@ const requiredRootFiles = [
   "scripts/render-secret-audit.mjs",
   "scripts/render-api-contract-audit.mjs",
   "scripts/render-migration-review.mjs",
+  "scripts/render-github-handoff.mjs",
   "scripts/check-adapter-upgrade.mjs",
   "scripts/check-adapter-upgrade-chain.mjs",
   "scripts/validate-adapters.mjs",
@@ -110,6 +111,7 @@ const requiredRootFiles = [
   "scripts/lib/secret-audit.mjs",
   "scripts/lib/api-contract-audit.mjs",
   "scripts/lib/migration-review.mjs",
+  "scripts/lib/github-handoff.mjs",
   "scripts/lib/adapter-upgrade.mjs",
   "scripts/lib/adapter-upgrade-chain.mjs",
   "scripts/lib/adapter-discovery.mjs",
@@ -683,8 +685,8 @@ if (packageJson) {
   if (packageJson.name !== "coding-agent-skills") {
     failures.push("package.json has unexpected package name");
   }
-  if (packageJson.version !== "0.2.13") {
-    failures.push("package.json version must be 0.2.13 for public package validation");
+  if (packageJson.version !== "0.2.14") {
+    failures.push("package.json version must be 0.2.14 for public package validation");
   }
   if (packageJson.type !== "module") failures.push("package.json must preserve ESM mode");
   if (packageJson.private !== false) {
@@ -707,6 +709,7 @@ if (packageJson) {
       "secret-audit",
       "api-contract-audit",
       "migration-review",
+      "github-handoff",
       "project-adapters",
       "code-validation",
       "cli",