skill-family-engineering-kit 0.1.2 → 0.1.3

package/src/core-check.mjs

@@ -0,0 +1,223 @@
+import { lstat } from "node:fs/promises";
+import path from "node:path";
+import { KIT_ERROR_KINDS } from "./errors.mjs";
+import { CHECK_CLASSES, runChecks } from "./check.mjs";
+import {
+  IDENTITY_RECORD_PATH,
+  MANAGED_LOCK_PATH,
+  PROJECT_MANIFEST_PATH,
+} from "./skeleton.mjs";
+import {
+  listTargetEntries,
+  loadTargetFacts,
+  matchAnyGitignorePattern,
+  matchAnyGlob,
+  resolveTargetRoot,
+} from "./workspace.mjs";
+
+/**
+ * runCoreCheck — the single shared production entry of the closed-world
+ * project check (C2).
+ *
+ * The generated `scripts/check-core.mjs` entrypoints of scaffolded projects
+ * ONLY import this function: safe file-tree enumeration, lstat/symlink/FIFO
+ * and special-entry rejection, file-registry classification (managed /
+ * handwritten / artifact closed world), declaration path containment, the
+ * seven check classes, and the stable finding/exit mapping all live here and
+ * nowhere else. No generated string may re-derive a recursive walk, an lstat
+ * classification, a glob match, or a local closed-world algorithm.
+ *
+ * Stages (all read-only; never opens a file before it is lstat-classified):
+ *   1. declaration containment — escaping managed declarations (absolute
+ *      paths, `..` segments) are reported lexically and never touch the fs;
+ *   2. managed preflight — lstat only: missing / symlink / non-regular
+ *      managed paths fail closed before anything could read them;
+ *   3. tree enumeration — every symlink and special entry fails closed;
+ *      every regular file must belong to the registered closed world
+ *      (managed, handwritten, artifact, or a tracked tool lock);
+ *   4. the seven check classes through runChecks — skipped whenever an
+ *      unsafe path (symlink/special at a managed or class-read path) would
+ *      be opened by them: FIFOs must never be read (they block), symlinks
+ *      must never be followed.
+ *
+ * Exit mapping: 0 clean; 2 when any finding carries a security kind
+ * (CORE_CHECK_SECURITY_KINDS, including the harness containment kinds that
+ * can surface through escaping lock entries); 1 otherwise.
+ */
+
+/** Finding kinds that always map to the security exit code 2. */
+export const CORE_CHECK_SECURITY_KINDS = Object.freeze([
+  // Kit kinds of this entry.
+  KIT_ERROR_KINDS.SYMLINK_AT_MANAGED_PATH,
+  KIT_ERROR_KINDS.NOT_A_REGULAR_FILE,
+  KIT_ERROR_KINDS.SYMLINK_ENTRY,
+  KIT_ERROR_KINDS.SPECIAL_ENTRY,
+  KIT_ERROR_KINDS.UNCONTAINED_DECLARATION,
+  // Stable harness containment kinds that surface through drift findings when
+  // a lock entry tries to escape the target (reported, never followed).
+  "absolute-path",
+  "windows-drive-path",
+  "windows-path",
+  "unc-path",
+  "path-traversal",
+  "symlink-escape",
+  "realpath-escape",
+  "invalid-path",
+]);
+
+const CORE_CLASS = "core";
+
+/**
+ * Paths the seven check classes open by name. They take part in the unsafe
+ * read-set even when they are not declared managed (README.md is handwritten
+ * in the skeleton), so a symlink/FIFO there can never hang or escape a read.
+ */
+const CLASS_READ_PATHS = Object.freeze([
+  "README.md",
+  "package.json",
+  PROJECT_MANIFEST_PATH,
+  MANAGED_LOCK_PATH,
+  IDENTITY_RECORD_PATH,
+  "identity-record.json",
+]);
+
+/** Lexical containment of a managed declaration; never touches the fs. */
+export function isContainedDeclaration(rel) {
+  if (typeof rel !== "string" || rel.length === 0) return false;
+  if (rel.startsWith("/")) return false;
+  if (rel.split("/").includes("..")) return false;
+  return true;
+}
+
+/**
+ * Runs the unified closed-world check over one target.
+ * Options: { root, allowGitSpawn, profilesRoot }.
+ * Returns { kind, ok, exitCode, findings, classes, unsafeReadPaths }.
+ * Never writes anywhere.
+ */
+export async function runCoreCheck({ root, allowGitSpawn = true, profilesRoot } = {}) {
+  const rootAbs = await resolveTargetRoot(root ?? ".");
+  const facts = await loadTargetFacts(rootAbs);
+  const findings = [];
+  const push = (kind, message, extra) =>
+    findings.push({ class: CORE_CLASS, kind, code: "SFC2004", message, ...(extra ?? {}) });
+
+  // ---- Stage 1: declaration containment (purely lexical) -----------------
+  const declarations = [...facts.managedSet].sort();
+  const containedDeclarations = [];
+  for (const rel of declarations) {
+    if (isContainedDeclaration(rel)) {
+      containedDeclarations.push(rel);
+    } else {
+      push(
+        KIT_ERROR_KINDS.UNCONTAINED_DECLARATION,
+        `managed declaration escapes the target root (absolute path or '..' segment): ${rel}`,
+        { path: rel },
+      );
+    }
+  }
+
+  // ---- Stage 2: managed preflight (lstat only, never open/read) ----------
+  const unsafeReadPaths = new Set();
+  for (const rel of containedDeclarations) {
+    let st;
+    try {
+      st = await lstat(path.join(rootAbs, rel));
+    } catch {
+      push(
+        KIT_ERROR_KINDS.MANAGED_FILE_MISSING,
+        `managed file declared in the registry/manifest/lock does not exist: ${rel}`,
+        { path: rel },
+      );
+      continue;
+    }
+    if (st.isSymbolicLink()) {
+      push(KIT_ERROR_KINDS.SYMLINK_AT_MANAGED_PATH, `managed path is a symbolic link: ${rel}`, { path: rel });
+      unsafeReadPaths.add(rel);
+    } else if (!st.isFile()) {
+      push(
+        KIT_ERROR_KINDS.NOT_A_REGULAR_FILE,
+        `managed path is not a regular file (FIFO/socket/device/directory): ${rel}`,
+        { path: rel },
+      );
+      unsafeReadPaths.add(rel);
+    }
+  }
+
+  // ---- Stage 3: safe tree enumeration + closed-world classification ------
+  const entries = await listTargetEntries(rootAbs);
+  for (const entry of entries) {
+    if (entry.kind === "directory" || entry.kind === "directory-opaque") continue;
+    if (entry.kind === "symlink") {
+      // Symlinks are never classified by content patterns: unregistered ones
+      // fail closed; managed ones were already reported by the preflight.
+      if (!facts.managedSet.has(entry.path)) {
+        push(
+          KIT_ERROR_KINDS.SYMLINK_ENTRY,
+          `symbolic link is outside the registered closed world (managed/handwritten/artifact): ${entry.path}`,
+          { path: entry.path },
+        );
+      }
+      if (facts.managedSet.has(entry.path) || CLASS_READ_PATHS.includes(entry.path)) {
+        unsafeReadPaths.add(entry.path);
+      }
+      continue;
+    }
+    if (entry.kind === "special") {
+      if (!facts.managedSet.has(entry.path)) {
+        push(
+          KIT_ERROR_KINDS.SPECIAL_ENTRY,
+          `special entry (FIFO/socket/device) is outside the registered closed world: ${entry.path}`,
+          { path: entry.path },
+        );
+      }
+      if (facts.managedSet.has(entry.path) || CLASS_READ_PATHS.includes(entry.path)) {
+        unsafeReadPaths.add(entry.path);
+      }
+      continue;
+    }
+    // Regular files must belong to exactly one registered class. Managed
+    // bytes are verified by the drift class, never re-derived here.
+    if (facts.managedSet.has(entry.path)) continue;
+    if (matchAnyGlob(facts.handwrittenPatterns, entry.path)) continue;
+    if (matchAnyGitignorePattern(facts.artifactPatterns, entry.path)) continue;
+    if (facts.trackedToolLocks.includes(entry.path)) continue;
+    push(
+      KIT_ERROR_KINDS.UNREGISTERED_FILE,
+      `regular file is not registered in the closed world (managed/handwritten/artifact): ${entry.path}`,
+      { path: entry.path },
+    );
+  }
+
+  // ---- Stage 4: the seven check classes through the shared entry ---------
+  let classReport = null;
+  if (unsafeReadPaths.size === 0) {
+    classReport = await runChecks({ root: rootAbs, allowGitSpawn, profilesRoot });
+    findings.push(...classReport.findings);
+  }
+
+  let exitCode = 0;
+  if (findings.length > 0) {
+    const securityKinds = new Set(CORE_CHECK_SECURITY_KINDS);
+    exitCode = findings.some((f) => securityKinds.has(f.kind)) ? 2 : 1;
+  }
+  if (classReport && classReport.mechanism) exitCode = 2;
+
+  return {
+    kind: "skill-family.core-check-report",
+    schemaVersion: 1,
+    target: { root: ".", entryCount: entries.length },
+    ok: findings.length === 0,
+    exitCode,
+    findings,
+    classes:
+      classReport?.classes ??
+      CHECK_CLASSES.map((name) => ({ name, selected: false, completed: false, findings: 0 })),
+    classChecksSkipped:
+      unsafeReadPaths.size > 0
+        ? { reason: "unsafe read-set (symlink/special at a managed or class-read path)", paths: [...unsafeReadPaths].sort() }
+        : null,
+    policy:
+      "core check is diagnosis only: it enumerates with lstat, never opens an unclassified entry, never follows symlinks, and never writes",
+  };
+}

package/src/errors.mjs

@@ -48,9 +48,12 @@ export const KIT_ERROR_KINDS = Object.freeze({
   // check / shared
   CONTRACTS_MISSING: "contracts-missing",
   CONTRACT_PARSE_FAILED: "contract-parse-failed",
+  DOCUMENT_INCOMPLETE: "document-incomplete",
+  CHECK_CLASS_FAILED: "check-class-failed",
   MANAGED_FILE_MISSING: "managed-file-missing",
   MANAGED_FILE_DRIFT: "managed-file-drift",
   SYMLINK_AT_MANAGED_PATH: "symlink-at-managed-path",
+  NOT_A_REGULAR_FILE: "not-a-regular-file",
   CLOSURE_INPUT_MISSING: "closure-input-missing",
   CONTRACTS_VERSION_MISMATCH: "contracts-version-mismatch",
   README_MISSING: "readme-missing",
@@ -59,6 +62,11 @@ export const KIT_ERROR_KINDS = Object.freeze({
   GIT_NO_COMMITS: "git-no-commits",
   GIT_DIRTY: "git-dirty",
   MUTATION_MODE_REQUESTED: "mutation-mode-requested",
+  // core check: the single shared closed-world entry (C2)
+  UNREGISTERED_FILE: "unregistered-file",
+  SYMLINK_ENTRY: "symlink-entry",
+  SPECIAL_ENTRY: "special-entry",
+  UNCONTAINED_DECLARATION: "uncontained-declaration",
 });
 
 /** Error carrying one frozen SFC code plus a stable kit kind in details. */

package/src/index.mjs

@@ -1,6 +1,7 @@
 import { ContractsError } from "skill-family-contracts";
 import { buildHandoffDraft, HANDOFF_FIELDS, planAdoption } from "./adopt-plan.mjs";
-import { CHECK_CLASSES, runChecks } from "./check.mjs";
+import { CHECK_CLASSES, DOCUMENT_STATES, runChecks } from "./check.mjs";
+import { CORE_CHECK_SECURITY_KINDS, isContainedDeclaration, runCoreCheck } from "./core-check.mjs";
 import {
   invalidParamsError,
   KitError,
@@ -150,10 +151,13 @@ export async function runCommand(command, options = {}) {
     }
     case "check": {
       const output = await runChecks(options);
-      return {
-        exitCode: output.ok ? KIT_EXIT_CODES.ok : KIT_EXIT_CODES.findings,
-        output,
-      };
+      // 0 clean; 2 mechanism (a selected class could not complete); 1 findings.
+      const exitCode = output.mechanism
+        ? KIT_EXIT_CODES.rejected
+        : output.ok
+          ? KIT_EXIT_CODES.ok
+          : KIT_EXIT_CODES.findings;
+      return { exitCode, output };
     }
     default: {
       // TOP_LEVEL_COMMANDS is frozen with exactly the cases above; this
@@ -181,6 +185,10 @@ export {
   loadProjectionManifest,
   runChecks,
   CHECK_CLASSES,
+  DOCUMENT_STATES,
+  runCoreCheck,
+  CORE_CHECK_SECURITY_KINDS,
+  isContainedDeclaration,
   probeGitState,
   probeGitFacts,
   GIT_READ_ONLY_ALLOWLIST,

package/src/skeleton.mjs

@@ -379,88 +379,28 @@ function renderDocsDeployWorkflow() {
 }
 
 function renderCheckCoreScript() {
+  // Thin generated shim. ALL mechanics — safe tree enumeration, entry-type
+  // rejection (symlink / FIFO / special entries), file-registry closed-world
+  // classification, path containment, the seven check classes, and the
+  // stable finding/exit mapping — live in the kit's single shared production
+  // entry (runCoreCheck). This file must never grow a local tree scan,
+  // entry-type classifier, glob matcher, or closed-world algorithm of its own.
   return [
     "#!/usr/bin/env node",
-    "// core check: delegates to the Foundation's production check entry and",
-    "// verifies the file registry closed-world classification.",
-    "// No local algorithm duplication — the generated project consumes the",
-    "// shared check closure from skill-family-engineering-kit.",
-    'import { lstat } from "node:fs/promises";',
-    'import { readFileSync } from "node:fs";',
-    'import { readdir } from "node:fs/promises";',
-    'import path from "node:path";',
-    'import { runChecks, matchAnyGlob } from "skill-family-engineering-kit";',
-    "",
-    "const root = process.cwd();",
-    "const failures = [];",
-    "",
-    "// Load file registry for closed-world classification",
-    'const registry = JSON.parse(readFileSync(path.join(root, ".foundation/file-registry.json"), "utf8"));',
-    'const lock = JSON.parse(readFileSync(path.join(root, "skill-family.managed-file-lock.json"), "utf8"));',
-    "",
-    "// Build managed file set from file registry (projenManaged + kitManaged)",
-    "const managedSet = new Set([",
-    "  ...registry.classes.projenManaged.files,",
-    "  ...registry.classes.kitManaged.files,",
-    "]);",
-    "",
-    "// Build handwritten patterns from registry",
-    "const handwrittenPatterns = registry.classes.handwritten.entries.filter((e) => typeof e === \"string\");",
-    "",
-    "// Artifact patterns from registry",
-    "const artifactPatterns = registry.classes.artifacts.patterns.filter((e) => typeof e === \"string\");",
-    "",
-    "// Pre-flight: verify managed files are regular files (catches symlinks, FIFOs, etc.)",
-    "// This prevents runChecks from hanging on FIFOs and provides clear error messages.",
-    "for (const relPath of managedSet) {",
-    "  let st;",
-    "  try {",
-    "    st = await lstat(path.resolve(root, relPath));",
-    "  } catch {",
-    '    failures.push(`managed file missing: ${relPath}`);',
-    "    continue;",
-    "  }",
-    "  if (st.isSymbolicLink()) {",
-    '    failures.push(`managed file is a symlink: ${relPath}`);',
-    "  } else if (!st.isFile()) {",
-    '    failures.push(`managed file is not a regular file: ${relPath}`);',
-    "  }",
-    "}",
-    "",
-    "// Closed-world file classification: every tracked file must be classified",
-    "const OPAQUE = new Set([\".git\", \"node_modules\"]);",
-    "async function walk(dir, base) {",
-    "  const dirents = await readdir(dir, { withFileTypes: true });",
-    "  for (const dirent of dirents) {",
-    "    const rel = base ? `${base}/${dirent.name}` : dirent.name;",
-    "    if (dirent.isDirectory() && !dirent.isSymbolicLink()) {",
-    "      if (!OPAQUE.has(dirent.name)) await walk(path.join(dir, dirent.name), rel);",
-    "      continue;",
-    "    }",
-    "    if (!dirent.isFile()) continue;",
-    "    const isManaged = managedSet.has(rel);",
-    "    const isHandwritten = matchAnyGlob(handwrittenPatterns, rel);",
-    "    const isArtifact = matchAnyGlob(artifactPatterns, rel);",
-    "    if (!isManaged && !isHandwritten && !isArtifact) {",
-    '      failures.push(`unregistered file: ${rel}`);',
-    "    }",
-    "  }",
-    "}",
-    "await walk(root, \"\");",
-    "",
-    "// Run the shared production checks (schema, drift, closure, version, docs, git, identity)",
-    "if (failures.length === 0) {",
-    "  const report = await runChecks({ root, allowGitSpawn: true });",
-    "  for (const f of report.findings) {",
-    '    failures.push(`${f.class}: ${f.message}`);',
-    "  }",
-    "}",
-    "",
-    "if (failures.length > 0) {",
-    '  for (const f of failures) console.error(`[check-core] ${f}`);',
-    "  process.exit(failures.some((f) => f.includes(\"symlink\") || f.includes(\"not a regular\") || f.includes(\"traversal\") || f.includes(\"escape\")) ? 2 : 1);",
+    "// core check: generated shim. It only imports the Foundation's single",
+    "// shared production check entry (runCoreCheck), passes the target root,",
+    "// prints the structured findings, and maps the stable exit code.",
+    "// No local algorithm duplication: safe tree enumeration, symlink/FIFO/",
+    "// special-entry rejection, closed-world classification, path containment,",
+    "// and the seven check classes all live in skill-family-engineering-kit.",
+    'import { runCoreCheck } from "skill-family-engineering-kit";',
+    "",
+    "const report = await runCoreCheck({ root: process.cwd(), allowGitSpawn: true });",
+    "for (const f of report.findings) {",
+    '  console.error(`[check-core] ${f.class}: ${f.kind}: ${f.message}`);',
     "}",
-    'console.log(`[check-core] OK`);',
+    "if (!report.ok) process.exit(report.exitCode);",
+    'console.log("[check-core] OK");',
     "",
   ].join("\n");
 }

package/src/workspace.mjs

@@ -101,7 +101,11 @@ export async function listTargetEntries(root) {
       }
       if (dirent.isFile()) {
         entries.push({ path: rel, kind: "file" });
+        continue;
       }
+      // Anything else (FIFO, socket, device, …) is a special entry: it is
+      // recorded so classification can fail closed on it; it is never opened.
+      entries.push({ path: rel, kind: "special" });
     }
   }
   await walk(root, "");
@@ -169,6 +173,61 @@ export function matchAnyGlob(patterns, relPath) {
   return Array.isArray(patterns) && patterns.some((pattern) => matchGlob(pattern, relPath));
 }
 
+function gitignoreSegmentRegExp(segment) {
+  let expression = "";
+  for (const char of segment) {
+    if (char === "*") expression += "[^/]*";
+    else expression += char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${expression}$`);
+}
+
+/**
+ * Gitignore-style lexical match for file-registry artifact patterns. The
+ * registry's artifacts class is mechanically identical to the .gitignore
+ * patterns (check-structure enforces the equality), so the closed-world
+ * classification interprets them with gitignore semantics:
+ *   - a leading "/" anchors the pattern at the target root;
+ *   - a "/" in the middle (after the trailing one is stripped) also anchors;
+ *   - a trailing "/" marks a directory pattern: it matches everything under
+ *     a directory with that name, never a regular file of that name;
+ *   - "*" is a per-segment wildcard (never crosses "/");
+ *   - unanchored patterns match at any depth.
+ * Purely lexical; never touches the filesystem.
+ */
+export function matchGitignoreStylePattern(pattern, relPath) {
+  if (typeof pattern !== "string" || typeof relPath !== "string") return false;
+  let trimmed = pattern.trim();
+  if (trimmed === "" || trimmed.startsWith("#")) return false;
+  let rootAnchored = trimmed.startsWith("/");
+  if (rootAnchored) trimmed = trimmed.slice(1);
+  const directoryOnly = trimmed.endsWith("/");
+  if (directoryOnly) trimmed = trimmed.slice(0, -1);
+  if (trimmed.includes("/")) rootAnchored = true;
+  const patternSegments = trimmed.split("/").filter((segment) => segment !== "");
+  if (patternSegments.length === 0) return false;
+  const pathSegments = relPath.split("/").filter((segment) => segment !== "");
+  const matchesAt = (start) => {
+    if (start + patternSegments.length > pathSegments.length) return false;
+    for (let i = 0; i < patternSegments.length; i += 1) {
+      if (!gitignoreSegmentRegExp(patternSegments[i]).test(pathSegments[start + i])) return false;
+    }
+    const end = start + patternSegments.length;
+    // A directory pattern matches everything strictly under the directory;
+    // a file pattern matches exactly the named entry.
+    return directoryOnly ? end < pathSegments.length : end === pathSegments.length;
+  };
+  if (rootAnchored) return matchesAt(0);
+  for (let start = 0; start < pathSegments.length; start += 1) {
+    if (matchesAt(start)) return true;
+  }
+  return false;
+}
+
+export function matchAnyGitignorePattern(patterns, relPath) {
+  return Array.isArray(patterns) && patterns.some((pattern) => matchGitignoreStylePattern(pattern, relPath));
+}
+
 /** Normalizes a relative path to forward slashes without touching the fs. */
 export function normalizeRelPath(relPath) {
   return String(relPath).replaceAll("\\", "/").replace(/\/+/g, "/").replace(/^\.\//, "");
@@ -189,6 +248,8 @@ export async function loadTargetFacts(root) {
     managedLock: null,
     managedSet: new Set(),
     handwrittenPatterns: [...DEFAULT_HANDWRITTEN_PATTERNS],
+    artifactPatterns: [],
+    trackedToolLocks: [],
     hasOwnRegistry: false,
   };
 
@@ -196,16 +257,37 @@ export async function loadTargetFacts(root) {
   if (registry.ok && registry.value && typeof registry.value === "object") {
     facts.fileRegistry = registry.value;
     facts.hasOwnRegistry = true;
+    // Foundation-shape registry: one flat managed list.
     const managed = registry.value?.classes?.managed;
     if (Array.isArray(managed)) {
       for (const entry of managed) {
         if (typeof entry === "string") facts.managedSet.add(normalizeRelPath(entry));
       }
     }
+    // Generated-skeleton registry: the managed set is declared as two classes
+    // (projen-managed + kit-managed). Both shapes feed the same closed world.
+    for (const classKey of ["projenManaged", "kitManaged"]) {
+      const files = registry.value?.classes?.[classKey]?.files;
+      if (Array.isArray(files)) {
+        for (const entry of files) {
+          if (typeof entry === "string") facts.managedSet.add(normalizeRelPath(entry));
+        }
+      }
+    }
     const patterns = registry.value?.classes?.handwritten?.entries;
     if (Array.isArray(patterns) && patterns.length > 0) {
       facts.handwrittenPatterns = patterns.filter((entry) => typeof entry === "string");
     }
+    const artifactPatterns = registry.value?.classes?.artifacts?.patterns;
+    if (Array.isArray(artifactPatterns)) {
+      facts.artifactPatterns = artifactPatterns.filter((entry) => typeof entry === "string");
+    }
+    const toolLocks = registry.value?.classes?.trackedToolLocks?.entries;
+    if (Array.isArray(toolLocks)) {
+      facts.trackedToolLocks = toolLocks
+        .filter((entry) => typeof entry === "string")
+        .map((entry) => normalizeRelPath(entry));
+    }
   }
 
   const manifest = await readOptionalJson(root, "skill-family.project-manifest.json");