skill-family-engineering-kit 0.1.0

package/src/skeleton.mjs

@@ -0,0 +1,886 @@
+import { CONTRACTS_VERSION } from "skill-family-contracts";
+import { digestBytes } from "skill-family-harness-node";
+import { invalidParamsError, kitError, KIT_ERROR_KINDS } from "./errors.mjs";
+import {
+  generateIdentityRecord,
+  generateLicenseContent,
+  generateNoticeContent,
+  loadLicensingProfile,
+} from "./licensing.mjs";
+import { MIGRATION_MANIFEST_PATH } from "./migration.mjs";
+
+/**
+ * The planned skeleton of one Skill Family project.
+ *
+ * describeSkeletonFiles is the single source of truth for both scaffold
+ * (which writes the files) and adopt-plan (which previews exactly the same
+ * bytes). The two commands cannot diverge because they consume the same
+ * pure function; the plan is the action and the action is the plan.
+ *
+ * The function is deterministic: equal inputs produce equal bytes, so
+ * adoption plans stay comparable across runs (no timestamps are embedded).
+ *
+ * The skeleton is a COMPLETE, immediately developable Skill Family
+ * workspace (§4.2), not just a few manifests: workspace tooling with exact
+ * pinned versions, docs and MkDocs config, docs CI with a hard-disabled
+ * Pages gate, file classification with an explicit lockfile tracking
+ * decision, minimal Git workflow rules (rules only — the kit never executes
+ * Git writes), contract documents, and check entrypoints. The public
+ * skeleton and Profile differences are layered: everything Profile-specific
+ * flows from the licensing profile data, never from this module.
+ */
+
+export const KIT_TOOL_NAME = "skill-family-engineering-kit";
+export const KIT_VERSION = "0.0.0";
+
+/** Kit-owned document paths inside a target workspace. */
+export const PROJECT_MANIFEST_PATH = "skill-family.project-manifest.json";
+export const MANAGED_LOCK_PATH = "skill-family.managed-file-lock.json";
+export const PROJECTION_MANIFEST_PATH = "skill-family.projection.json";
+export const IDENTITY_RECORD_PATH = "skill-family.identity-record.json";
+export const RELEASE_INTEGRATION_PATH = "skill-family.release-integration.json";
+export const FILE_REGISTRY_PATH = ".foundation/file-registry.json";
+
+/**
+ * Exact tool versions of the generated workspace. These are engineering
+ * facts of the skeleton itself (not per-profile policy): Node major locked
+ * to 22, pnpm and projen pinned to exact versions.
+ */
+export const SKELETON_NODE_MAJOR = "22";
+export const SKELETON_PNPM_VERSION = "10.30.0";
+export const SKELETON_PROJEN_VERSION = "0.101.23";
+
+const PROJEN_MARKER = '~~ Generated by projen. To modify, edit .projenrc.js and run "npx projen".';
+
+const KEBAB_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+/** Validates the kebab-case identifiers used by the skeleton. */
+export function assertKebabId(value, label) {
+  if (typeof value !== "string" || !KEBAB_PATTERN.test(value)) {
+    throw invalidParamsError(
+      `${label} must be a kebab-case identifier (^[a-z][a-z0-9]*(-[a-z0-9]+)*$)`,
+      { value: String(value) },
+    );
+  }
+  return value;
+}
+
+function assertProjectName(value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw invalidParamsError("project name must be a non-empty string", {
+      value: String(value),
+    });
+  }
+  return value;
+}
+
+/**
+ * Normalizes scaffold/adopt-plan inputs. Defaults: projectId falls back to
+ * the target directory basename when it is a valid kebab id, projectName
+ * falls back to projectId, profileId defaults to "generic". A null
+ * licensingProfile is resolved at load time to the first variant declared
+ * in the licensing registry (the default is a data fact, never a
+ * hardcoded profile name).
+ */
+export function normalizeSkeletonInputs({ projectId, projectName, profileId, licensingProfile, licensingVariant, rootBasename }) {
+  let resolvedId = projectId;
+  if (resolvedId === undefined || resolvedId === null) {
+    resolvedId = rootBasename;
+  }
+  assertKebabId(resolvedId, "project id");
+  const name = projectName === undefined || projectName === null ? resolvedId : projectName;
+  assertProjectName(name);
+  const profile = profileId === undefined || profileId === null ? "generic" : profileId;
+  assertKebabId(profile, "profile id");
+  const licensing = licensingProfile === undefined || licensingProfile === null ? null : licensingProfile;
+  if (licensing !== null) {
+    assertKebabId(licensing, "licensing profile");
+  }
+  if (licensingVariant !== undefined && licensingVariant !== null) {
+    assertKebabId(licensingVariant, "licensing variant");
+  }
+  return {
+    projectId: resolvedId,
+    projectName: name,
+    profileId: profile,
+    licensingProfile: licensing,
+    licensingVariant: licensingVariant ?? null,
+  };
+}
+
+function jsonString(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+/* ------------------------------------------------------------------ */
+/* Root workspace tooling (projen-managed in the generated project)    */
+/* ------------------------------------------------------------------ */
+
+function workspaceName(projectId) {
+  return `${projectId}-workspace`;
+}
+
+function renderRootPackageJson({ projectId, projectName, licensingProfile }) {
+  return jsonString({
+    name: workspaceName(projectId),
+    version: "0.0.0",
+    private: true,
+    description: `Skill Family workspace for project ${projectName}.`,
+    author: licensingProfile.identity.displayValue,
+    license: licensingProfile.licensing.spdx,
+    engines: { node: `>=${SKELETON_NODE_MAJOR} <${Number(SKELETON_NODE_MAJOR) + 1}` },
+    packageManager: `pnpm@${SKELETON_PNPM_VERSION}`,
+    scripts: {
+      // Direct execution of the projenrc: the projen CLI needs .projen/tasks.json
+      // to discover the default task, but a fresh skeleton has no .projen/ yet.
+      // `node .projenrc.js` works for the first synth and every later one.
+      synth: "node .projenrc.js",
+      check:
+        "node scripts/check-core.mjs && node scripts/check-docs.mjs && node scripts/security-negative.mjs && pnpm --recursive --if-present run check",
+      test: "pnpm --recursive --if-present run test",
+      "docs-build": "mkdocs build --strict",
+    },
+    devDependencies: {
+      projen: SKELETON_PROJEN_VERSION,
+    },
+    "//": PROJEN_MARKER,
+  });
+}
+
+function renderLeafPackageJson({ projectId, licensingProfile }) {
+  return jsonString({
+    name: projectId,
+    version: "0.0.0",
+    private: true,
+    description: `Skill Family project ${projectId}.`,
+    author: licensingProfile.identity.displayValue,
+    license: licensingProfile.licensing.spdx,
+    type: "module",
+    engines: { node: `>=${SKELETON_NODE_MAJOR} <${Number(SKELETON_NODE_MAJOR) + 1}` },
+    exports: "./src/index.mjs",
+    scripts: {
+      check: "node --test",
+      test: "node --test",
+    },
+    "//": PROJEN_MARKER,
+  });
+}
+
+// The four renderers below must reproduce, byte for byte, what the seeded
+// .projenrc.js synthesizes with projen 0.101.23 (verified empirically):
+// - IgnoreFile: `# marker` + patterns in insertion order, joined with "\n",
+//   trailing "\n"; the Project constructor seeds node_modules/ and
+//   !/.gitattributes, Tasks seeds the four !/.projen/*.json includes, every
+//   committed file seeds its own !/<path> include at construction time.
+// - GitAttributesFile: `# marker`, blank line, sorted attributes, no trailing newline.
+// - TextFile (.npmrc/.node-version): lines joined with "\n", no marker, no
+//   trailing newline.
+
+function renderPnpmWorkspaceYaml() {
+  return [`# ${PROJEN_MARKER}`, "", "packages:", "  - packages/*", ""].join("\n");
+}
+
+function renderNpmrc() {
+  return ["save-exact=true", "shared-workspace-lockfile=true", "strict-peer-dependencies=true"].join("\n");
+}
+
+function renderNodeVersion() {
+  return SKELETON_NODE_MAJOR;
+}
+
+function renderGitIgnore({ projectId }) {
+  // pnpm-lock.yaml is deliberately NOT ignored: a public workspace tracks
+  // its lockfile for reproducible installs.
+  // site/.qoder/.artifacts are root-only (`/site/`, `/.qoder/`,
+  // `/.artifacts/`), identical to the foundation root project: a nested
+  // packages/site/** (or any non-root occurrence) must stay tracked.
+  return [
+    `# ${PROJEN_MARKER}`,
+    "!/.gitattributes",
+    "!/.projen/tasks.json",
+    "!/.projen/deps.json",
+    "!/.projen/tree.json",
+    "!/.projen/files.json",
+    "node_modules/",
+    "/site/",
+    ".cache/",
+    "/.qoder/",
+    "*.log",
+    ".DS_Store",
+    ".env",
+    ".env.*",
+    "!.env.example",
+    "/.artifacts/",
+    "!/package.json",
+    "!/pnpm-workspace.yaml",
+    "!/.npmrc",
+    "!/.node-version",
+    `!/packages/${projectId}/package.json`,
+    "",
+  ].join("\n");
+}
+
+function renderGitAttributes() {
+  return [`# ${PROJEN_MARKER}`, "", "* text=auto eol=lf"].join("\n");
+}
+
+/* ------------------------------------------------------------------ */
+/* Kit-managed documents and entrypoints                               */
+/* ------------------------------------------------------------------ */
+
+function renderProjectManifest({ projectId, projectName, profileId, managedFiles }) {
+  return jsonString({
+    schemaVersion: 1,
+    kind: "skill-family.project-manifest",
+    project: {
+      id: workspaceName(projectId),
+      name: projectName,
+      description: `Skill Family project ${projectName}.`,
+    },
+    contracts: {
+      version: CONTRACTS_VERSION,
+      profile: profileId,
+    },
+    managedFiles,
+  });
+}
+
+function renderManagedLock(entries) {
+  return jsonString({
+    schemaVersion: 1,
+    kind: "skill-family.managed-file-lock",
+    lockVersion: 1,
+    entries,
+  });
+}
+
+function renderMigrationManifest() {
+  // Fresh skeleton: nothing has been migrated yet; the state machine starts
+  // at "planned" with an empty legacy list (migration manifest contract shape).
+  return jsonString({
+    schemaVersion: 1,
+    kind: "skill-family.migration-manifest",
+    legacyInfra: [],
+    exceptions: [],
+  });
+}
+
+function renderReleaseIntegration({ projectId }) {
+  // Integration boundary placeholder only: the foundation never replicates
+  // a release state machine (§4.2).
+  return jsonString({
+    schemaVersion: 1,
+    kind: "skill-family.release-integration",
+    project: projectId,
+    status: "placeholder",
+    boundary:
+      "release-skill integrates here when a project decides to publish; no release state machine is replicated in the skeleton",
+  });
+}
+
+function renderFileRegistry({ projectId, projenManaged, kitManaged, handwritten }) {
+  return jsonString({
+    schemaVersion: 1,
+    kind: "skill-family.file-registry",
+    workspace: workspaceName(projectId),
+    generatedBy: { tool: KIT_TOOL_NAME, version: KIT_VERSION },
+    classes: {
+      projenManaged: {
+        files: projenManaged,
+        note: "由 projen 生成：只改 .projenrc.js 后运行 pnpm synth。",
+      },
+      kitManaged: {
+        files: kitManaged,
+        note: "由 engineering kit 维护的契约与门禁入口；经 scaffold/重新锁定更新。",
+      },
+      handwritten: {
+        entries: handwritten,
+        note: "由人维护的源事实；任何工具永不覆盖。",
+      },
+      artifacts: {
+        patterns: ["node_modules/", "/site/", ".cache/", "/.qoder/", "*.log", ".DS_Store", ".env", ".env.*", "/.artifacts/"],
+        note: "可再生构建物/缓存/运行证据；经 .gitignore 忽略，绝不跟踪。",
+      },
+    },
+    lockfileDecision: {
+      path: "pnpm-lock.yaml",
+      tracked: true,
+      rationale: "公开 workspace 默认跟踪锁文件以保证可复现安装。",
+    },
+    rules: {
+      closedWorld: "每个拟跟踪文件恰好属于 projenManaged/kitManaged/handwritten 之一；每个忽略项属于 artifacts。",
+      gitPolicy: "工具只生成 Git 规则文本，绝不执行任何 Git 写操作。",
+    },
+  });
+}
+
+function renderDocsWorkflow() {
+  return [
+    "name: docs",
+    "on:",
+    "  push:",
+    "    branches: [main]",
+    "  pull_request:",
+    "jobs:",
+    "  docs-build:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    "      - uses: actions/checkout@v4",
+    "      - uses: actions/setup-python@v5",
+    "        with:",
+    "          python-version: '3.12'",
+    "      - name: Install MkDocs",
+    "        run: pip install mkdocs-material==9.6.14",
+    "      - name: Build docs",
+    "        run: mkdocs build --strict",
+    "",
+  ].join("\n");
+}
+
+function renderDocsDeployWorkflow() {
+  // Pages deployment stays HARD-DISABLED (`if: false`). The confirmation
+  // value travels through an environment variable, never through shell
+  // interpolation (FC-16 pattern).
+  return [
+    "name: docs-deploy",
+    "on:",
+    "  workflow_dispatch:",
+    "    inputs:",
+    "      confirm:",
+    "        description: 'Type the confirmation value to enable Pages deployment'",
+    "        required: true",
+    "jobs:",
+    "  deploy-pages:",
+    "    if: false",
+    "    runs-on: ubuntu-latest",
+    "    env:",
+    "      PAGES_CONFIRM: ${{ inputs.confirm }}",
+    "    steps:",
+    "      - name: Refuse until explicitly enabled",
+    "        run: |",
+    '          if [ "$PAGES_CONFIRM" != "enable-pages" ]; then',
+    "            echo 'Pages deployment is disabled; refusing.'",
+    "            exit 1",
+    "          fi",
+    "          echo 'Pages deployment is still gated by if:false and must be reviewed before enabling.'",
+    "",
+  ].join("\n");
+}
+
+function renderCheckCoreScript() {
+  return [
+    "#!/usr/bin/env node",
+    "// core check: verifies the managed lock binds the real bytes and the",
+    "// file registry stays a closed world. Dependency-free by design.",
+    'import { createHash } from "node:crypto";',
+    'import { readFileSync, existsSync } from "node:fs";',
+    "",
+    "const lock = JSON.parse(readFileSync(\"skill-family.managed-file-lock.json\", \"utf8\"));",
+    "const failures = [];",
+    "for (const entry of lock.entries) {",
+    "  if (!existsSync(entry.path)) {",
+    "    failures.push(`managed file missing: ${entry.path}`);",
+    "    continue;",
+    "  }",
+    "  const actual = createHash(\"sha256\").update(readFileSync(entry.path)).digest(\"hex\");",
+    "  if (actual !== entry.hash.value) failures.push(`managed file drifted: ${entry.path}`);",
+    "}",
+    "const registry = JSON.parse(readFileSync(\".foundation/file-registry.json\", \"utf8\"));",
+    "const seen = new Map();",
+    "for (const [className, files] of [",
+    '  ["projenManaged", registry.classes.projenManaged.files],',
+    '  ["kitManaged", registry.classes.kitManaged.files],',
+    '  ["handwritten", registry.classes.handwritten.entries],',
+    "]) {",
+    "  for (const file of files) {",
+    '    if (seen.has(file)) failures.push(`file classified twice: ${file} (${seen.get(file)} and ${className})`);',
+    "    seen.set(file, className);",
+    "  }",
+    "}",
+    "if (failures.length > 0) {",
+    '  for (const failure of failures) console.error(`[check-core] ${failure}`);',
+    "  process.exit(2);",
+    "}",
+    'console.log(`[check-core] OK (${lock.entries.length} locked files, closed-world registry)`);',
+    "",
+  ].join("\n");
+}
+
+function renderCheckDocsScript() {
+  return [
+    "#!/usr/bin/env node",
+    "// docs check: README exists and every mkdocs nav page exists on disk.",
+    "// Dependency-free by design.",
+    'import { readFileSync, existsSync } from "node:fs";',
+    "",
+    "const failures = [];",
+    'if (!existsSync("README.md") || readFileSync("README.md", "utf8").trim() === "") {',
+    '  failures.push("README.md is missing or empty");',
+    "}",
+    'const mkdocs = readFileSync("mkdocs.yml", "utf8");',
+    'for (const match of mkdocs.matchAll(/\\bdocs\\/[A-Za-z0-9._\\/-]+\\.md\\b/g)) {',
+    "  if (!existsSync(match[0])) failures.push(`nav page missing: ${match[0]}`);",
+    "}",
+    "if (failures.length > 0) {",
+    '  for (const failure of failures) console.error(`[check-docs] ${failure}`);',
+    "  process.exit(2);",
+    "}",
+    'console.log("[check-docs] OK");',
+    "",
+  ].join("\n");
+}
+
+function renderSecurityNegativeScript() {
+  return [
+    "#!/usr/bin/env node",
+    "// security negative cases: every hostile path MUST be rejected by the",
+    "// containment classifier below; if any passes, this script exits 2.",
+    "",
+    "function classify(relPath) {",
+    '  if (typeof relPath !== "string" || relPath.length === 0) return "reject";',
+    '  if (relPath.includes("\\\\") || relPath.includes("..")) return "reject";',
+    '  if (relPath.startsWith("/") || /^[A-Za-z]:/.test(relPath)) return "reject";',
+    '  if (relPath.startsWith("file:") || relPath.startsWith("http")) return "reject";',
+    '  return "accept";',
+    "}",
+    "",
+    "const negatives = [",
+    '  "../outside.txt",',
+    '  "/etc/passwd",',
+    '  "C:\\\\Windows\\\\system32",',
+    '  "\\\\\\\\server\\\\share",',
+    '  "a/../../b",',
+    '  "file:///etc/passwd",',
+    '  "",',
+    "];",
+    "const failures = negatives.filter((candidate) => classify(candidate) !== \"reject\");",
+    "if (failures.length > 0) {",
+    "  console.error(`[security-negative] hostile path accepted: ${failures.join(\", \")}`);",
+    "  process.exit(2);",
+    "}",
+    'console.log(`[security-negative] OK (${negatives.length} hostile paths rejected)`);',
+    "",
+  ].join("\n");
+}
+
+/* ------------------------------------------------------------------ */
+/* Handwritten seeds                                                   */
+/* ------------------------------------------------------------------ */
+
+function renderReadme({ projectId, projectName, licensingProfile }) {
+  return [
+    `# ${projectName}`,
+    "",
+    `Skill Family project \`${projectId}\` (workspace \`${workspaceName(projectId)}\`).`,
+    "",
+    `Licensed under ${licensingProfile.licensing.spdx} by ${licensingProfile.identity.displayValue}.`,
+    "",
+    "- 开发：`pnpm install && pnpm synth`",
+    "- 验证：`pnpm check`",
+    "- 文档：`pnpm run docs-build`",
+    "- Git lifecycle guide: [docs/git-lifecycle.md](docs/git-lifecycle.md)",
+    "",
+    "This README is handwritten source material: the engineering kit never overwrites it.",
+    "",
+  ].join("\n");
+}
+
+function renderAgents({ projectId }) {
+  // MCR-020: this file carries ONLY the Git safety baseline and a link to
+  // the single complete guide (docs/git-lifecycle.md). No automatic Git
+  // actions, no duplicated process.
+  return [
+    "# Project Agent Rules",
+    "",
+    `Engineering rules for ${workspaceName(projectId)}. Maintain this file by hand;`,
+    "the engineering kit treats it as handwritten source material.",
+    "",
+    "## Managed files",
+    "",
+    "- projen-managed files: only edit `.projenrc.js`, then run `pnpm synth`.",
+    "- kit-managed files are declared in `skill-family.managed-file-lock.json`.",
+    "- File classification lives in `.foundation/file-registry.json` (closed world).",
+    "- Run `pnpm check` before handing work over.",
+    "",
+    "## Git safety baseline (the full process lives in docs/git-lifecycle.md)",
+    "",
+    "Without an explicit human authorization for the current task, no tool or",
+    "automation in this workspace may stage, commit, push, tag, publish, create",
+    "or delete remotes, open pull requests, or delete remote branches. A green",
+    "`pnpm check` only makes a change eligible to commit — eligible never means",
+    "authorized.",
+    "",
+    "The single complete Git lifecycle guide of this workspace is",
+    "`docs/git-lifecycle.md` (branch model, safe commit points, eligibility,",
+    "failure recovery, branch exit). Link to that guide; never duplicate the",
+    "full process here or in README/help/quickstart.",
+    "",
+  ].join("\n");
+}
+
+function renderProjenrc({ projectId, projectName, licensingProfile }) {
+  // Handwritten seed: the generated project's single projen entry. It must
+  // reproduce every projen-managed byte of the skeleton, so `pnpm synth`
+  // inside the generated workspace is idempotent.
+  // The seed must never contain the PROJEN_MARKER literal ("~~ Generated by
+  // projen"): projen's legacy cleanup (first synth without .projen/files.json)
+  // deletes any file containing that literal, which would remove .projenrc.js
+  // itself. The `marker: true` option below injects the identical marker key
+  // at synth time instead.
+  const rootPkg = JSON.parse(renderRootPackageJson({ projectId, projectName, licensingProfile }));
+  const leafPkg = JSON.parse(renderLeafPackageJson({ projectId, licensingProfile }));
+  delete rootPkg["//"];
+  delete leafPkg["//"];
+  return [
+    `const { JsonFile, Project, TextFile, YamlFile } = require("projen");`,
+    "",
+    `const WORKSPACE_NAME = ${JSON.stringify(workspaceName(projectId))};`,
+    "",
+    "class WorkspaceProject extends Project {",
+    "  constructor() {",
+    "    super({ name: WORKSPACE_NAME, commitGenerated: true, projectTree: true });",
+    '    this.defaultTask?.execArgs(["node", ".projenrc.js"]);',
+    '    this.addGitIgnore("node_modules/");',
+    '    this.addGitIgnore("/site/");',
+    '    this.addGitIgnore(".cache/");',
+    '    this.addGitIgnore("/.qoder/");',
+    '    this.addGitIgnore("*.log");',
+    '    this.addGitIgnore(".DS_Store");',
+    '    this.addGitIgnore(".env");',
+    '    this.addGitIgnore(".env.*");',
+    '    this.addGitIgnore("!.env.example");',
+    '    this.addGitIgnore("/.artifacts/");',
+    `    new JsonFile(this, "package.json", { obj: ${JSON.stringify(rootPkg)}, marker: true, readonly: true });`,
+    `    new YamlFile(this, "pnpm-workspace.yaml", { obj: { packages: ["packages/*"] }, marker: true, readonly: true });`,
+    `    new TextFile(this, ".npmrc", { lines: ["save-exact=true", "shared-workspace-lockfile=true", "strict-peer-dependencies=true"], marker: true, readonly: true });`,
+    `    new TextFile(this, ".node-version", { lines: [${JSON.stringify(SKELETON_NODE_MAJOR)}], marker: true, readonly: true });`,
+    `    new JsonFile(this, "packages/${projectId}/package.json", { obj: ${JSON.stringify(leafPkg)}, marker: true, readonly: true });`,
+    "  }",
+    "}",
+    "",
+    "new WorkspaceProject().synth();",
+    "",
+  ].join("\n");
+}
+
+function renderMkdocsYml({ projectName }) {
+  return [
+    `site_name: ${projectName}`,
+    "theme:",
+    "  name: material",
+    "nav:",
+    "  - Home: index.md",
+    "  - Help: help.md",
+    "  - Setup: setup.md",
+    "  - Quickstart: quickstart.md",
+    "  - Git lifecycle: git-lifecycle.md",
+    "  - Architecture: architecture.md",
+    "",
+  ].join("\n");
+}
+
+function renderDocPage(title, projectName, body) {
+  return [`# ${title}`, "", ...body.map((line) => line.replaceAll("{{PROJECT}}", projectName)), ""].join("\n");
+}
+
+function renderGitLifecycle() {
+  // MCR-020: the generated docs/git-lifecycle.md is the SINGLE complete Git
+  // lifecycle guide of the scaffolded workspace. AGENTS.md keeps only the
+  // safety baseline and a link here; README/help/quickstart link, never
+  // duplicate. Eligible (checks green) never means authorized.
+  // RCR-010: the four Git write-authorization categories are independent —
+  // each needs its own explicit per-task authorization and none of them can
+  // be derived from another (commit !=> push/tag/release; push !=>
+  // tag/release/remote-branch deletion).
+  return [
+    "# Git lifecycle",
+    "",
+    "The single complete Git lifecycle guide of this workspace. AGENTS.md",
+    "keeps only the safety baseline and a link here; README/help/quickstart",
+    "link to this guide and never duplicate the process.",
+    "",
+    "## Authorization boundary",
+    "",
+    "Tools in this workspace never execute Git writes. Without an explicit",
+    "human authorization for the current task, nothing may stage, commit,",
+    "push, tag, publish, create or delete remotes, open pull requests, or",
+    "delete remote branches.",
+    "",
+    "## Authorizations are independent and never imply each other",
+    "",
+    "Git write authorizations fall into four separate categories. Each",
+    "category requires its own explicit authorization for the current task;",
+    "the categories are independent and one never implies another:",
+    "",
+    "1. stage;",
+    "2. commit;",
+    "3. push, opening a pull request, deleting a remote branch;",
+    "4. tag, release/publish.",
+    "",
+    "One authorization never derives another: one commit authorization does",
+    "not automatically authorize push, tag, or release; one push",
+    "authorization does not automatically authorize tag, release, or",
+    "deleting a remote branch.",
+    "",
+    "## Eligible vs authorized",
+    "",
+    "A change reaches eligible (ready to be committed) when `pnpm check`",
+    "exits 0 on the current tree. Eligible never means authorized:",
+    "committing an eligible change still requires the explicit per-task",
+    "authorization above.",
+    "",
+    "## Branch model",
+    "",
+    "- One long-lived `main` branch plus short-lived task branches",
+    "  (`task/<id>-<slug>`).",
+    "- Never push `main` directly and never revert `main` by force-push.",
+    "",
+    "## Safe commit point",
+    "",
+    "Commit only an eligible tree — never commit a broken state to `main`.",
+    "",
+    "## Failure recovery",
+    "",
+    "On a red build, fix forward on the task branch; if the branch is",
+    "unsalvageable, delete it and restart from `main` (each as an explicitly",
+    "authorized action).",
+    "",
+    "## Branch exit",
+    "",
+    "After a reviewed merge, the task branch may be deleted locally and",
+    "remotely — only as explicitly authorized actions, never automated.",
+    "",
+  ].join("\n");
+}
+
+function renderIndexModule({ projectId }) {
+  return [
+    `// Entry module of ${projectId}. Handwritten source material: the`,
+    "// engineering kit never overwrites files under src/.",
+    "",
+    "export const PROJECT_ID = " + JSON.stringify(projectId) + ";",
+    "",
+  ].join("\n");
+}
+
+function renderLeafTest({ projectId }) {
+  return [
+    `import test from "node:test";`,
+    'import assert from "node:assert/strict";',
+    'import { PROJECT_ID } from "../src/index.mjs";',
+    "",
+    'test("project id is stable", () => {',
+    `  assert.equal(PROJECT_ID, ${JSON.stringify(projectId)});`,
+    "});",
+    "",
+  ].join("\n");
+}
+
+/* ------------------------------------------------------------------ */
+/* Skeleton assembly                                                   */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Computes the skeleton files for one project.
+ * Returns { files, managedFiles, lockEntries, licensing } where files is the
+ * ordered array of { path, fileClass: "managed"|"handwritten", content } and
+ * every managed content hash is already bound in the lock entries.
+ */
+export async function describeSkeletonFiles(inputs) {
+  // Same-source guarantee: every caller — scaffold, adopt-plan,
+  // conformance verifiers — goes through the same intake normalization, so
+  // identical options always yield identical bytes.
+  const normalized = normalizeSkeletonInputs({
+    ...inputs,
+    rootBasename: inputs.rootBasename ?? inputs.projectId,
+  });
+  const {
+    projectId,
+    projectName,
+    profileId,
+    licensingProfile,
+    licensingVariant,
+  } = normalized;
+  const { licensingProfileData, profilesRoot, identityProjections } = inputs;
+
+  // Load licensing profile if not provided
+  let profileData = licensingProfileData;
+  if (!profileData && profilesRoot) {
+    profileData = await loadLicensingProfile({
+      profilesRoot,
+      profileId: licensingProfile,
+      variant: licensingVariant ?? undefined,
+    });
+  }
+
+  if (!profileData) {
+    throw kitError(
+      KIT_ERROR_KINDS.INVALID_MANIFEST,
+      "licensing profile data is required (provide licensingProfileData or profilesRoot)",
+      { licensingProfile },
+    );
+  }
+
+  const leafDir = `packages/${projectId}`;
+  const generator = { tool: KIT_TOOL_NAME, version: KIT_VERSION };
+
+  const licenseContent = generateLicenseContent(profileData);
+  const noticeContent = generateNoticeContent(profileData, { projectName });
+  const identityRecord = generateIdentityRecord(profileData, {
+    projectId,
+    projectName,
+    projections: identityProjections,
+  });
+  const identityRecordContent = jsonString(identityRecord);
+
+  const handwritten = [
+    "README.md",
+    "AGENTS.md",
+    "LICENSE",
+    ".projenrc.js",
+    "mkdocs.yml",
+    "docs/**",
+    `${leafDir}/src/**`,
+    `${leafDir}/test/**`,
+    MIGRATION_MANIFEST_PATH,
+  ];
+  if (noticeContent) handwritten.push("NOTICE");
+
+  const projenManaged = [
+    "package.json",
+    "pnpm-workspace.yaml",
+    ".npmrc",
+    ".node-version",
+    ".gitignore",
+    `${leafDir}/package.json`,
+  ];
+  const kitManaged = [
+    ".gitattributes",
+    ".github/workflows/docs.yml",
+    ".github/workflows/docs-deploy.yml",
+    "scripts/check-core.mjs",
+    "scripts/check-docs.mjs",
+    "scripts/security-negative.mjs",
+    FILE_REGISTRY_PATH,
+    PROJECT_MANIFEST_PATH,
+    IDENTITY_RECORD_PATH,
+    RELEASE_INTEGRATION_PATH,
+    MANAGED_LOCK_PATH,
+  ];
+
+  const managedFiles = [...projenManaged, ...kitManaged];
+  const files = [
+    { path: "README.md", fileClass: "handwritten", content: renderReadme({ projectId, projectName, licensingProfile: profileData }) },
+    { path: "AGENTS.md", fileClass: "handwritten", content: renderAgents({ projectId }) },
+    { path: "LICENSE", fileClass: "handwritten", content: licenseContent },
+    { path: ".gitignore", fileClass: "managed", content: renderGitIgnore({ projectId }) },
+    { path: ".gitattributes", fileClass: "managed", content: renderGitAttributes() },
+    { path: ".npmrc", fileClass: "managed", content: renderNpmrc() },
+    { path: ".node-version", fileClass: "managed", content: renderNodeVersion() },
+    { path: "package.json", fileClass: "managed", content: renderRootPackageJson({ projectId, projectName, licensingProfile: profileData }) },
+    { path: "pnpm-workspace.yaml", fileClass: "managed", content: renderPnpmWorkspaceYaml() },
+    { path: ".projenrc.js", fileClass: "handwritten", content: renderProjenrc({ projectId, projectName, licensingProfile: profileData }) },
+    { path: "mkdocs.yml", fileClass: "handwritten", content: renderMkdocsYml({ projectName }) },
+    {
+      path: "docs/index.md",
+      fileClass: "handwritten",
+      content: renderDocPage("Home", projectName, ["{{PROJECT}} 的工程主页。骨架由 engineering kit 生成，本页为手写源事实。"]),
+    },
+    {
+      path: "docs/help.md",
+      fileClass: "handwritten",
+      content: renderDocPage("Help", projectName, [
+        "遇到问题时先运行 `pnpm check`；门禁输出会给出稳定错误码与类别。",
+        "完整 Git lifecycle 指南：[git-lifecycle.md](git-lifecycle.md)。",
+      ]),
+    },
+    {
+      path: "docs/setup.md",
+      fileClass: "handwritten",
+      content: renderDocPage(
+        "Setup",
+        projectName,
+        [
+          `需要 Node ${SKELETON_NODE_MAJOR}（major 锁定）与 pnpm ${SKELETON_PNPM_VERSION}（packageManager 字段精确锁定）。`,
+          "执行 `pnpm install`，然后 `pnpm synth` 生成受管文件。",
+        ],
+      ),
+    },
+    {
+      path: "docs/quickstart.md",
+      fileClass: "handwritten",
+      content: renderDocPage(
+        "Quickstart",
+        projectName,
+        [
+          "`pnpm install && pnpm synth && pnpm check` 全绿即完成最小验证。",
+          "任何 Git 写操作前先阅读完整指南：[git-lifecycle.md](git-lifecycle.md)。",
+        ],
+      ),
+    },
+    {
+      path: "docs/architecture.md",
+      fileClass: "handwritten",
+      content: renderDocPage(
+        "Architecture",
+        projectName,
+        [
+          "本 workspace 分为手写源事实、projen 受管工具文件与 kit 受管契约文件三层。",
+          "文件分类的唯一登记是 `.foundation/file-registry.json`（闭世界）。",
+        ],
+      ),
+    },
+    {
+      path: "docs/git-lifecycle.md",
+      fileClass: "handwritten",
+      content: renderGitLifecycle(),
+    },
+    { path: ".github/workflows/docs.yml", fileClass: "managed", content: renderDocsWorkflow() },
+    { path: ".github/workflows/docs-deploy.yml", fileClass: "managed", content: renderDocsDeployWorkflow() },
+    { path: "scripts/check-core.mjs", fileClass: "managed", content: renderCheckCoreScript() },
+    { path: "scripts/check-docs.mjs", fileClass: "managed", content: renderCheckDocsScript() },
+    { path: "scripts/security-negative.mjs", fileClass: "managed", content: renderSecurityNegativeScript() },
+    { path: `${leafDir}/package.json`, fileClass: "managed", content: renderLeafPackageJson({ projectId, licensingProfile: profileData }) },
+    { path: `${leafDir}/src/index.mjs`, fileClass: "handwritten", content: renderIndexModule({ projectId }) },
+    { path: `${leafDir}/test/index.test.mjs`, fileClass: "handwritten", content: renderLeafTest({ projectId }) },
+    {
+      path: FILE_REGISTRY_PATH,
+      fileClass: "managed",
+      content: renderFileRegistry({ projectId, projenManaged, kitManaged, handwritten }),
+    },
+    {
+      path: PROJECT_MANIFEST_PATH,
+      fileClass: "managed",
+      content: renderProjectManifest({ projectId, projectName, profileId, managedFiles }),
+    },
+    { path: IDENTITY_RECORD_PATH, fileClass: "managed", content: identityRecordContent },
+    // The migration manifest is seeded by the skeleton but becomes
+    // target-held data: the lock never binds it and adoption never
+    // overwrites it — its validity is judged by the migration contract.
+    { path: MIGRATION_MANIFEST_PATH, fileClass: "handwritten", content: renderMigrationManifest() },
+    { path: RELEASE_INTEGRATION_PATH, fileClass: "managed", content: renderReleaseIntegration({ projectId }) },
+  ];
+  if (noticeContent) {
+    files.push({ path: "NOTICE", fileClass: "handwritten", content: noticeContent });
+  }
+
+  // The lock binds every managed file except itself (a document cannot
+  // contain its own content hash); the manifest still declares the lock
+  // path as managed.
+  const lockEntries = files
+    .filter((file) => file.fileClass === "managed" && file.path !== MANAGED_LOCK_PATH)
+    .map((file) => ({
+      path: file.path,
+      hash: { algorithm: "sha256", value: digestBytes(Buffer.from(file.content, "utf8")) },
+      generator,
+      policy: "managed",
+    }));
+  files.push({ path: MANAGED_LOCK_PATH, fileClass: "managed", content: renderManagedLock(lockEntries) });
+
+  return {
+    files,
+    managedFiles,
+    lockEntries,
+    licensing: { profile: profileData.profile.id, variant: profileData.profile.variant },
+  };
+}