coding-agent-skills 0.2.8

package/scripts/lib/upgrade-evidence.mjs

@@ -0,0 +1,276 @@
+import { randomUUID } from "node:crypto";
+
+import { PILOT_VERSION } from "./pack-rules.mjs";
+
+export const UPGRADE_EVIDENCE_CONTRACT_VERSION = "1.0.0";
+
+const SUMMARY_BY_CODE = {
+  "adapter-schema-drift": "The adapter schema changed outside the supported contract.",
+  "adapter-set-drift": "The installed adapter set changed across revisions.",
+  "adapter-version-downgrade": "An adapter version moved backward.",
+  "adapter-version-drift": "An adapter version is incompatible or inconsistent.",
+  "after-project-invalid": "The proposed project revision did not validate.",
+  "before-project-invalid": "The source project revision did not validate.",
+  "chain-target-stale": "The final chain revision does not target the running core.",
+  "completion-override": "The revision attempted to redefine completion.",
+  "failure-suppression": "The revision attempted to suppress failures.",
+  "incompatible-core-chain": "Core versions do not form an adjacent compatible chain.",
+  "mode-escalation": "An audit-only skill was escalated.",
+  "path-traversal": "A revision or output path escaped its allowed boundary.",
+  "required-evidence-removal": "Required evidence was removed.",
+  "restriction-weakening": "Inherited restrictions were weakened.",
+  "scope-expansion": "Scope expanded without the required approval boundary.",
+  "secret-exposure": "Secret-like content was detected and withheld.",
+  "skill-compatibility-drift": "Skill compatibility changed incompatibly.",
+  "stale-compatible-range": "The compatible range does not represent the target core.",
+  "stale-exact-pin": "The exact core pin is stale.",
+  "unknown-skill-compatibility": "An unknown skill compatibility declaration was found.",
+  "unsupported-future-core": "A revision targets a core newer than the validator.",
+  "unsupported-old-core": "A revision is older than the supported upgrade source.",
+};
+
+function summaryForCode(code) {
+  return SUMMARY_BY_CODE[code] ?? "The validator reported an incompatible upgrade condition.";
+}
+
+function unique(values) {
+  return [...new Set(values)].sort();
+}
+
+function adapters(context) {
+  return context?.adapters ?? [];
+}
+
+function adapterIds(before, after) {
+  return unique([
+    ...adapters(before).map((adapter) => adapter.id),
+    ...adapters(after).map((adapter) => adapter.id),
+  ]);
+}
+
+function versions(context) {
+  return adapters(context).map((adapter) => ({
+    adapterId: adapter.id,
+    version: adapter.version,
+  }));
+}
+
+function skillIds(context) {
+  return unique(adapters(context).flatMap((adapter) => adapter.skillIds));
+}
+
+function compatibility(context) {
+  return adapters(context)
+    .flatMap((adapter) =>
+      adapter.skillCompatibility.map((skill) => ({
+        adapterId: adapter.id,
+        skillId: skill.id,
+        versions: [...skill.compatibleVersions],
+        mode: skill.declaredMode,
+      })),
+    )
+    .sort(
+      (left, right) =>
+        left.adapterId.localeCompare(right.adapterId) ||
+        left.skillId.localeCompare(right.skillId),
+    );
+}
+
+function approvals(before, after) {
+  return unique(
+    [...adapters(before), ...adapters(after)].flatMap(
+      (adapter) => adapter.approvalRequirements,
+    ),
+  );
+}
+
+function staleClassification(codes) {
+  if (codes.includes("stale-exact-pin")) return "stale-exact-pin";
+  if (codes.includes("stale-compatible-range")) return "stale-compatible-range";
+  if (codes.includes("chain-target-stale")) return "chain-target-stale";
+  return "none";
+}
+
+function pinResult(codes, before, after) {
+  if (!before?.versionPin || !after?.versionPin) return "unknown";
+  if (staleClassification(codes) !== "none") return "stale";
+  if (
+    codes.some((code) =>
+      [
+        "before-invalid-core-version",
+        "after-invalid-core-version",
+        "unsupported-old-core",
+        "unsupported-future-core",
+        "incompatible-core-chain",
+      ].includes(code),
+    )
+  ) {
+    return "invalid";
+  }
+  return "accepted";
+}
+
+function resultStatus(codes) {
+  return codes.length === 0 ? "pass" : "fail";
+}
+
+function restrictionCodes(codes) {
+  return codes.filter((code) =>
+    [
+      "restriction-weakening",
+      "mode-escalation",
+      "failure-suppression",
+      "completion-override",
+      "required-evidence-removal",
+      "secret-exposure",
+      "scope-expansion",
+    ].includes(code),
+  );
+}
+
+function evidenceBase(result, options) {
+  const before = result.context?.before ?? {
+    rootSummary: {
+      reference: "before",
+      declarationStatus: "unavailable",
+      validationStatus: "fail",
+    },
+    coreVersion: null,
+    versionPin: null,
+    adapterSchemaVersion: null,
+    adapters: [],
+  };
+  const after = result.context?.after ?? {
+    rootSummary: {
+      reference: "after",
+      declarationStatus: "unavailable",
+      validationStatus: "fail",
+    },
+    coreVersion: null,
+    versionPin: null,
+    adapterSchemaVersion: null,
+    adapters: [],
+  };
+  const codes = unique(result.codes ?? []);
+  const restrictions = restrictionCodes(codes);
+  const approvalRequirements = approvals(before, after);
+  const finalStatus = result.ok
+    ? approvalRequirements.length > 0
+      ? "warn"
+      : "pass"
+    : "fail";
+  const blockingFailures = codes.map((code) => ({
+    code,
+    summary: summaryForCode(code),
+  }));
+
+  return {
+    contractVersion: UPGRADE_EVIDENCE_CONTRACT_VERSION,
+    validator: {
+      name: options.validatorName,
+      version: PILOT_VERSION,
+    },
+    invocation: {
+      id: options.invocationId ?? `upgrade-${randomUUID()}`,
+      timestamp: options.timestamp ?? new Date().toISOString(),
+    },
+    beforeProject: before.rootSummary,
+    afterProject: after.rootSummary,
+    coreVersions: {
+      before: before.coreVersion,
+      after: after.coreVersion,
+    },
+    adapterIds: adapterIds(before, after),
+    adapterVersions: {
+      before: versions(before),
+      after: versions(after),
+    },
+    adapterSchemaVersions: {
+      before: before.adapterSchemaVersion,
+      after: after.adapterSchemaVersion,
+    },
+    supportedSkillIds: {
+      before: skillIds(before),
+      after: skillIds(after),
+    },
+    skillCompatibility: {
+      before: compatibility(before),
+      after: compatibility(after),
+    },
+    pinStatus: {
+      before: before.versionPin,
+      after: after.versionPin,
+      result: pinResult(codes, before, after),
+      staleClassification: staleClassification(codes),
+    },
+    compatibilityResult: {
+      result: resultStatus(codes),
+      codes,
+    },
+    restrictionInheritanceResult: {
+      result: resultStatus(restrictions),
+      codes: restrictions,
+    },
+    approvalRequirements,
+    detectedRisks: blockingFailures,
+    blockingFailures,
+    warnings: approvalRequirements.map((operation) => ({
+      code: "approval-required",
+      summary: `Named approval remains required for ${operation}.`,
+    })),
+    safeSummary: result.ok
+      ? approvalRequirements.length > 0
+        ? "The read-only compatibility check passed with named approvals still required."
+        : "The read-only compatibility check passed without applying changes."
+      : `The read-only compatibility check rejected ${codes.length} condition(s).`,
+    finalStatus,
+    confidence: {
+      level: result.context ? "high" : "low",
+      reason: result.context
+        ? "Both sanitized revision summaries and compatibility results were available."
+        : "One or more revision summaries were unavailable.",
+    },
+    changedState: {
+      changed: false,
+      summary:
+        "No project, adapter, Git, runtime, service, database, or remote state was changed.",
+    },
+    recommendedNextAction: result.ok
+      ? "Request human approval before adopting this upgrade in a real project."
+      : "Resolve every blocking failure and rerun the read-only validation.",
+  };
+}
+
+export function buildAdapterUpgradeEvidence(result, options = {}) {
+  const evidence = evidenceBase(result, {
+    ...options,
+    validatorName: "check-adapter-upgrade",
+  });
+  if (options.chainId) evidence.chainId = options.chainId;
+  if (Number.isInteger(options.chainStepIndex)) {
+    evidence.chainStepIndex = options.chainStepIndex;
+  }
+  return evidence;
+}
+
+export function buildAdapterChainEvidence(result, options = {}) {
+  const evidence = evidenceBase(result, {
+    ...options,
+    validatorName: "check-adapter-upgrade-chain",
+  });
+  evidence.chainId = options.chainId ?? `chain-${randomUUID()}`;
+  evidence.chainSummary = {
+    revisionCount: result.revisionCount,
+    transitionCount: result.transitionCount,
+    passedTransitions: result.passedTransitions,
+    failedTransitions: result.failedTransitions,
+    steps: result.transitions.map((transition) => ({
+      stepIndex: transition.stepIndex,
+      beforeRevision: `revision-${transition.stepIndex}`,
+      afterRevision: `revision-${transition.stepIndex + 1}`,
+      status: transition.ok ? "pass" : "fail",
+      codes: [...transition.codes],
+    })),
+  };
+  return evidence;
+}

package/scripts/render-adapter-repo-map.mjs

@@ -0,0 +1,8 @@
+import { adapterRepoMapCliResult } from "./lib/adapter-repo-map.mjs";
+
+const outcome = adapterRepoMapCliResult(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-evidence-archive-report.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { evidenceArchiveCliResult } from "./lib/evidence-bundle.mjs";
+
+const args = process.argv.slice(2);
+const bundleFile = args[0];
+const json = args.includes("--json");
+
+try {
+  const result = evidenceArchiveCliResult(bundleFile, { json });
+  for (const line of result.lines) {
+    if (result.stream === "stderr") console.error(line);
+    else console.log(line);
+  }
+  process.exit(result.exitCode);
+} catch {
+  console.error("evidence archive report rendering failed safely");
+  process.exit(2);
+}

package/scripts/run-next

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+const SUPPORTED_FLAGS = [
+  "harness-hardening",
+  "docs-hardening",
+  "test-hardening",
+  "adapter-harness",
+  "evidence-harness",
+  "release-preflight",
+  "commit",
+  "tag",
+  "push",
+];
+const BLOCKED_MILESTONE_PATTERNS = [
+  [/\b(?:add|create|implement)\b.*\bnew skills?\b/i, "new skills"],
+  [/\breal project adapters?\b/i, "real project adapters"],
+  [/\bmodify\b.*\breal project repositor/i, "real project repositories"],
+  [/\bdeploy(?:ment|s)?\b/i, "deployment"],
+  [/\bmigrations?\b/i, "migration"],
+  [/\b(?:service|process) mutation\b/i, "service or process mutation"],
+  [/\b(?:read|print|expose)\b.*\b(?:secret|credential|token)s?\b/i, "secret access"],
+  [/\bweaken\b.*\b(?:safety|restriction|policy|evidence)\b/i, "safety weakening"],
+];
+
+function failClosed(message) {
+  console.error(`run-next refused: ${message}`);
+  process.exit(1);
+}
+
+function usage() {
+  return [
+    "usage: ./scripts/run-next --allow <permission>",
+    `supported permissions: ${SUPPORTED_FLAGS.join(", ")}`,
+  ].join("\n");
+}
+
+function parseArgs(argv) {
+  const allowed = new Set();
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === "--help" || value === "-h") {
+      console.log(usage());
+      process.exit(0);
+    }
+    if (value !== "--allow") failClosed(`unknown argument ${value}`);
+    const permission = argv[index + 1];
+    if (!permission) failClosed("missing permission after --allow");
+    if (!SUPPORTED_FLAGS.includes(permission)) {
+      failClosed(`unknown permission ${permission}`);
+    }
+    allowed.add(permission);
+    index += 1;
+  }
+  if (allowed.size === 0) failClosed("at least one --allow flag is required");
+  return allowed;
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    cwd: options.cwd,
+    encoding: "utf8",
+    stdio: options.capture ? "pipe" : "inherit",
+  });
+  if (result.error) failClosed(`${command} could not start`);
+  if (result.status !== 0) {
+    if (options.capture && result.stderr) process.stderr.write(result.stderr);
+    failClosed(`${command} ${args.join(" ")} failed`);
+  }
+  return options.capture ? result.stdout.trim() : "";
+}
+
+function readRequired(root, relativePath) {
+  const file = path.join(root, relativePath);
+  if (!fs.existsSync(file)) failClosed(`missing ${relativePath}`);
+  return fs.readFileSync(file, "utf8");
+}
+
+function latestTag(tags) {
+  const versions = tags
+    .split(/\r?\n/)
+    .map((tagName) => /^v(\d+)\.(\d+)\.(\d+)$/.exec(tagName))
+    .filter(Boolean)
+    .map((match) => ({
+      tag: match[0],
+      parts: match.slice(1).map(Number),
+    }))
+    .sort((left, right) => {
+      for (let index = 0; index < 3; index += 1) {
+        if (left.parts[index] !== right.parts[index]) {
+          return left.parts[index] - right.parts[index];
+        }
+      }
+      return 0;
+    });
+  return versions.at(-1)?.tag ?? "unknown";
+}
+
+function recommendedMilestone(ledger) {
+  const match = /^## Current Recommended Milestone\s+([\s\S]*?)(?:\n## |\s*$)/m.exec(
+    ledger,
+  );
+  const value = match?.[1]?.trim();
+  if (!value) failClosed("work-ledger.md does not declare a recommended milestone");
+  return value.replace(/\s+/g, " ");
+}
+
+function requiredPermissionFor(milestone) {
+  if (/evidence|replay|regression/i.test(milestone)) return "evidence-harness";
+  if (/adapter/i.test(milestone)) return "adapter-harness";
+  if (/test/i.test(milestone)) return "test-hardening";
+  if (/doc/i.test(milestone)) return "docs-hardening";
+  return "harness-hardening";
+}
+
+function blockedMilestoneReason(milestone) {
+  for (const [pattern, reason] of BLOCKED_MILESTONE_PATTERNS) {
+    if (pattern.test(milestone)) return reason;
+  }
+  return null;
+}
+
+function appendRunEvidence(root, entry) {
+  const runLog = path.join(root, "runs", "skill-runs.md");
+  const ledger = path.join(root, "work-ledger.md");
+  fs.appendFileSync(runLog, entry.runLog);
+  fs.appendFileSync(ledger, entry.ledger);
+}
+
+const allowed = parseArgs(process.argv.slice(2));
+const initialRoot = run("git", ["rev-parse", "--show-toplevel"], {
+  cwd: process.cwd(),
+  capture: true,
+});
+const root = path.resolve(initialRoot);
+process.chdir(root);
+
+const status = run("git", ["status", "--short", "--branch"], {
+  cwd: root,
+  capture: true,
+});
+const dirty = status
+  .split(/\r?\n/)
+  .slice(1)
+  .some((line) => line.trim());
+if (dirty) failClosed("working tree must be clean before run-next writes evidence");
+
+const tags = run("git", ["tag", "--list"], { cwd: root, capture: true });
+const latest = latestTag(tags);
+const roadmap = readRequired(root, "ROADMAP.md");
+const changelog = readRequired(root, "CHANGELOG.md");
+const ledger = readRequired(root, "work-ledger.md");
+if (!roadmap.includes("Roadmap")) failClosed("ROADMAP.md could not be recognized");
+if (!changelog.includes("Changelog")) failClosed("CHANGELOG.md could not be recognized");
+
+const milestone = recommendedMilestone(ledger);
+const blockedReason = blockedMilestoneReason(milestone);
+if (blockedReason) {
+  failClosed(`ledger milestone is out of scope: ${blockedReason}`);
+}
+const requiredPermission = requiredPermissionFor(milestone);
+if (!allowed.has(requiredPermission)) {
+  failClosed(`next action requires --allow ${requiredPermission}`);
+}
+
+const validationCommands = [
+  ["node", ["scripts/validate-pack.mjs", "."]],
+  ["node", ["scripts/test-pack.mjs"]],
+  ["node", ["scripts/validate-maintainer-loop.mjs", "."]],
+  ["node", ["--test"]],
+];
+for (const [command, args] of validationCommands) run(command, args, { cwd: root });
+
+const timestamp = new Date().toISOString();
+const runId = `run-${timestamp.replace(/[-:.TZ]/g, "").slice(0, 14)}`;
+const permissions = [...allowed].sort().join(", ");
+const commandUsed = `./scripts/run-next ${[...allowed]
+  .sort()
+  .map((permission) => `--allow ${permission}`)
+  .join(" ")}`;
+const validationList = validationCommands
+  .map(([command, args]) => `  - \`${command} ${args.join(" ")}\``)
+  .join("\n");
+
+appendRunEvidence(root, {
+  runLog: `
+
+## ${runId}
+
+- Run ID: \`${runId}\`
+- Timestamp: \`${timestamp}\`
+- Command used: \`${commandUsed}\`
+- Permissions granted: \`${permissions}\`
+- Files changed: \`runs/skill-runs.md\`, \`work-ledger.md\`
+- Validation commands:
+${validationList}
+- Validation result: pass
+- Commit/tag/push status: not performed by runner
+- Next state: selected \`${milestone}\`; human approval required before implementation
+`,
+  ledger: `
+
+### ${timestamp}
+
+- Latest tag observed: \`${latest}\`
+- Selected milestone: ${milestone}
+- Required permission: \`${requiredPermission}\`
+- Validation result: pass
+- Stop boundary: implementation requires human approval
+`,
+});
+
+console.log("run-next complete");
+console.log(`latest tag: ${latest}`);
+console.log(`selected milestone: ${milestone}`);
+console.log(`required permission: ${requiredPermission}`);
+console.log("validation result: pass");
+console.log("next state: human approval required before implementation");