@adamchanadam/cer-workflow 0.3.17

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Chan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# CER Workflow
+
+Installable npm package for the CER Workflow Codex skills.
+
+Status:
+
+- Package version `0.3.17` matches the included CER Workflow Skill runtime VERSION files.
+- npm support is an installability layer for future users. It does not change CER runtime behavior.
+- Validator, package, and install checks do not by themselves prove manual UAT pass, token saving, or universal task quality.
+
+Packaged surfaces:
+
+- `skills/cer-workflow`: Traditional Chinese installable Skill package.
+- `skills/cer-workflow-en`: English installable Skill package.
+- `bin/cer-workflow.mjs`: small local helper for package inspection and explicit-target install tests.
+
+The package whitelist intentionally excludes internal maintenance material such as `dev/`, `CER_docs/`, handoff and log files, backups, temporary evidence, local workspace paths, and cross-project comparison evidence.
+
+## Install
+
+```sh
+npm install -g @adamchanadam/cer-workflow
+cer-workflow help
+```
+
+For one-off inspection without a global install:
+
+```sh
+npx @adamchanadam/cer-workflow inspect
+```
+
+## Local Checks
+
+```sh
+npm run package:inspect
+npm run pack:dry-run
+```
+
+After packing and installing the generated tarball into a temporary project, run:
+
+```sh
+npx cer-workflow inspect --strict-package
+```
+
+## Install Helper
+
+The helper does not auto-detect or silently write to any global Skill directory. A file-copy Skill install requires an explicit target and confirmation:
+
+```sh
+npx cer-workflow install --skill en --target <empty-skill-directory> --yes
+npx cer-workflow install --skill zh --target <empty-skill-directory> --yes
+```
+
+The target directory must be absent or empty. The helper does not overwrite, delete, migrate, or back up an existing Skill directory.
+
+## Release Boundary
+
+This package is a distribution wrapper for the included Skill packages. Public runtime behavior remains owned by the Skill files and their references.

package/bin/cer-workflow.mjs

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, "..");
+const packageJsonPath = path.join(packageRoot, "package.json");
+
+const skillFiles = [
+  "SKILL.md",
+  "VERSION",
+  "agents/openai.yaml",
+  "references/core-runtime.md",
+  "references/parallel-producers.md",
+  "references/roadmap.md",
+  "references/uat.md",
+  "scripts/validate_cer_skill.py",
+];
+
+const skills = {
+  zh: {
+    label: "Traditional Chinese",
+    source: "skills/cer-workflow",
+    expectedTargetName: "cer-workflow",
+  },
+  en: {
+    label: "English",
+    source: "skills/cer-workflow-en",
+    expectedTargetName: "cer-workflow-en",
+  },
+};
+
+function readPackageJson() {
+  return JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+}
+
+function usage() {
+  return `CER Workflow package helper
+
+Usage:
+  cer-workflow help
+  cer-workflow version
+  cer-workflow inspect [--strict-package]
+  cer-workflow install --skill zh|en --target <empty-skill-directory> --yes
+
+Notes:
+  - This helper installs only the packaged CER Workflow Skill files.
+  - install never auto-detects a global Skill path.
+  - install refuses non-empty targets and does not delete, overwrite, migrate, or back up files.
+`;
+}
+
+function parseFlags(args) {
+  const flags = new Map();
+  const positionals = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    const key = arg.slice(2);
+    if (key === "yes" || key === "strict-package") {
+      flags.set(key, true);
+      continue;
+    }
+    const value = args[i + 1];
+    if (!value || value.startsWith("--")) {
+      throw new Error(`Missing value for --${key}`);
+    }
+    flags.set(key, value);
+    i += 1;
+  }
+  return { flags, positionals };
+}
+
+function requiredPackageFiles() {
+  const files = ["README.md", "LICENSE", "bin/cer-workflow.mjs"];
+  for (const skill of Object.values(skills)) {
+    for (const file of skillFiles) {
+      files.push(path.posix.join(skill.source, file));
+    }
+  }
+  return files;
+}
+
+function inspectPackage(strictPackage) {
+  const pkg = readPackageJson();
+  const errors = [];
+  const warnings = [];
+  if (pkg.name !== "@adamchanadam/cer-workflow") {
+    errors.push("package name mismatch");
+  }
+  const zhVersion = fs.readFileSync(path.join(packageRoot, skills.zh.source, "VERSION"), "utf8").trim();
+  const enVersion = fs.readFileSync(path.join(packageRoot, skills.en.source, "VERSION"), "utf8").trim();
+  if (pkg.version !== zhVersion || pkg.version !== enVersion) {
+    errors.push("package version must match both packaged Skill VERSION files");
+  }
+  if (pkg.private === true) {
+    errors.push("package must not be private for the promoted npm candidate");
+  }
+  if (pkg.license !== "MIT") {
+    errors.push("package license must be MIT");
+  }
+  if (pkg.publishConfig?.access !== "public" || pkg.publishConfig?.tag !== "next") {
+    errors.push("publishConfig must keep access=public and tag=next before first publish");
+  }
+  if (pkg.bin?.["cer-workflow"] !== "bin/cer-workflow.mjs") {
+    errors.push("bin mapping is missing or changed");
+  }
+
+  const expectedFiles = requiredPackageFiles();
+  for (const file of expectedFiles) {
+    if (!fs.existsSync(path.join(packageRoot, file))) {
+      errors.push(`missing required package file: ${file}`);
+    }
+  }
+
+  const whitelist = Array.isArray(pkg.files) ? pkg.files : [];
+  const missingWhitelistEntries = expectedFiles.filter((file) => !whitelist.includes(file));
+  for (const file of missingWhitelistEntries) {
+    errors.push(`package files whitelist missing: ${file}`);
+  }
+
+  const forbiddenWhitelist = [
+    "dev",
+    "dev/",
+    "CER_docs",
+    "CER_docs/",
+    "backup",
+    "backup/",
+    "tmp",
+    "tmp/",
+    "START_NEXT_SESSION_PROMPT.txt",
+  ];
+  for (const entry of whitelist) {
+    if (forbiddenWhitelist.includes(entry)) {
+      errors.push(`forbidden whitelist entry: ${entry}`);
+    }
+  }
+
+  if (strictPackage) {
+    const forbiddenPackagedPaths = [
+      "dev",
+      "CER_docs",
+      "backup",
+      "tmp",
+      "Adam_Personal_Notes",
+      "travel-checklist",
+      "assets",
+      "START_NEXT_SESSION_PROMPT.txt",
+    ];
+    for (const entry of forbiddenPackagedPaths) {
+      if (fs.existsSync(path.join(packageRoot, entry))) {
+        errors.push(`internal path is present in strict packaged mode: ${entry}`);
+      }
+    }
+  } else {
+    warnings.push("strict package absence check skipped; use --strict-package after tarball install");
+  }
+
+  if (errors.length) {
+    console.error("CER package inspection failed:");
+    for (const error of errors) {
+      console.error(`- ${error}`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`CER package inspection OK: ${pkg.name}@${pkg.version}`);
+  console.log(`Public package candidate: ${pkg.private === true ? "no" : "yes"}`);
+  console.log(`Publish tag: ${pkg.publishConfig?.tag ?? "(unset)"}`);
+  console.log(`Required files checked: ${expectedFiles.length}`);
+  for (const warning of warnings) {
+    console.log(`Note: ${warning}`);
+  }
+}
+
+function expandHome(inputPath) {
+  if (inputPath === "~") {
+    return os.homedir();
+  }
+  if (inputPath.startsWith("~/") || inputPath.startsWith("~\\")) {
+    return path.join(os.homedir(), inputPath.slice(2));
+  }
+  return inputPath;
+}
+
+function assertSafeTarget(target, skill) {
+  const resolved = path.resolve(expandHome(target));
+  const parsed = path.parse(resolved);
+  const home = path.resolve(os.homedir());
+  const root = path.resolve(parsed.root);
+  const packageRootResolved = path.resolve(packageRoot);
+
+  if (resolved === root) {
+    throw new Error("Refusing to install into a filesystem root");
+  }
+  if (resolved === home) {
+    throw new Error("Refusing to install directly into the user home directory");
+  }
+  if (resolved === packageRootResolved || resolved.startsWith(`${packageRootResolved}${path.sep}`)) {
+    throw new Error("Refusing to install inside this package source root");
+  }
+  if (path.basename(resolved) !== skill.expectedTargetName) {
+    throw new Error(`Target directory name must be ${skill.expectedTargetName}`);
+  }
+  return resolved;
+}
+
+function listDirectoryIfExists(target) {
+  if (!fs.existsSync(target)) {
+    return [];
+  }
+  const stat = fs.statSync(target);
+  if (!stat.isDirectory()) {
+    throw new Error("Target exists but is not a directory");
+  }
+  return fs.readdirSync(target);
+}
+
+function copySkill(skill, target) {
+  const sourceRoot = path.join(packageRoot, skill.source);
+  for (const relative of skillFiles) {
+    const source = path.join(sourceRoot, relative);
+    const destination = path.join(target, relative);
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.copyFileSync(source, destination, fs.constants.COPYFILE_EXCL);
+  }
+}
+
+function installSkill(args) {
+  const { flags } = parseFlags(args);
+  const skillKey = flags.get("skill");
+  const targetInput = flags.get("target");
+  const confirmed = flags.get("yes") === true;
+
+  if (!skillKey || !skills[skillKey]) {
+    throw new Error("install requires --skill zh or --skill en");
+  }
+  if (!targetInput) {
+    throw new Error("install requires --target <empty-skill-directory>");
+  }
+  if (!confirmed) {
+    throw new Error("install requires --yes");
+  }
+
+  const skill = skills[skillKey];
+  const target = assertSafeTarget(targetInput, skill);
+  const existingEntries = listDirectoryIfExists(target);
+  if (existingEntries.length > 0) {
+    throw new Error("Target directory is not empty; this helper does not overwrite or delete files");
+  }
+
+  fs.mkdirSync(target, { recursive: true });
+  copySkill(skill, target);
+  console.log(`Installed ${skill.label} CER Workflow skill to ${target}`);
+  console.log(`Files copied: ${skillFiles.length}`);
+}
+
+function main() {
+  const [command = "help", ...args] = process.argv.slice(2);
+  if (command === "help" || command === "--help" || command === "-h") {
+    console.log(usage());
+    return;
+  }
+  if (command === "version" || command === "--version" || command === "-v") {
+    console.log(readPackageJson().version);
+    return;
+  }
+  if (command === "inspect") {
+    const { flags } = parseFlags(args);
+    inspectPackage(flags.get("strict-package") === true);
+    return;
+  }
+  if (command === "install") {
+    installSkill(args);
+    return;
+  }
+  throw new Error(`Unknown command: ${command}`);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@adamchanadam/cer-workflow",
+  "version": "0.3.17",
+  "description": "Installable npm package for the CER Workflow Codex skills.",
+  "type": "module",
+  "bin": {
+    "cer-workflow": "bin/cer-workflow.mjs"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "bin/cer-workflow.mjs",
+    "skills/cer-workflow/SKILL.md",
+    "skills/cer-workflow/VERSION",
+    "skills/cer-workflow/agents/openai.yaml",
+    "skills/cer-workflow/references/core-runtime.md",
+    "skills/cer-workflow/references/parallel-producers.md",
+    "skills/cer-workflow/references/roadmap.md",
+    "skills/cer-workflow/references/uat.md",
+    "skills/cer-workflow/scripts/validate_cer_skill.py",
+    "skills/cer-workflow-en/SKILL.md",
+    "skills/cer-workflow-en/VERSION",
+    "skills/cer-workflow-en/agents/openai.yaml",
+    "skills/cer-workflow-en/references/core-runtime.md",
+    "skills/cer-workflow-en/references/parallel-producers.md",
+    "skills/cer-workflow-en/references/roadmap.md",
+    "skills/cer-workflow-en/references/uat.md",
+    "skills/cer-workflow-en/scripts/validate_cer_skill.py"
+  ],
+  "scripts": {
+    "package:inspect": "node bin/cer-workflow.mjs inspect",
+    "pack:dry-run": "npm pack --dry-run --json"
+  },
+  "keywords": [
+    "codex",
+    "skill",
+    "cer-workflow",
+    "agent-workflow"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Adamchanadam/cer-workflow.git"
+  },
+  "homepage": "https://github.com/Adamchanadam/cer-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/Adamchanadam/cer-workflow/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  }
+}

package/skills/cer-workflow/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: cer-workflow
+description: "執行獨立 CER 工作法，或用本地 /CER-auto 選最低足夠的 ordinary／Goal／CER 工作法／blocked 路線。只在使用者明確帶 CER 的指令或同等語意時使用；適合長期、多批、易中斷、需要唯一 writer、fresh Reviewer、自足派工、持久化及按需平行候選分析的工作。單獨「開工／收工」不是 CER 觸發。本 Skill 不規定項目文件。"
+---
+
+# CER 工作法
+
+CER Core v1 只供 Codex 使用。Claude Code 需要另一個尚未提供的 Skill；不得聲稱本
+Skill 或本 repo 目前支援 Claude Code。
+
+公開 runtime 語言邊界由 [core-runtime.md](references/core-runtime.md) 擁有：未來行為先
+改英文 `cer-workflow-en` canonical；本入口只保留中文觸發／回覆相容，不另定 runtime。
+
+## 入口路由
+
+1. 處理本地 `/CER-auto` 時，在任何 CER 身份成立前，只讀取
+   [core-runtime.md](references/core-runtime.md) 的「執行強度閘門」及裁決所需的使用者
+   要求與目標專案真源；路徑已知時按該 owner 的單次有界讀取要求載入。選 ordinary execution 或 Goal 後停止載入其他 CER references；選 CER 工作法
+   時只在需要 CER 的停點完整讀取 `core-runtime.md` 及 [roadmap.md](references/roadmap.md)，按現行
+   CER 啟動。CER 啟動後才成立 C／E1；R 仍按既有 Reviewer owner 的風險條件建立。
+   blocked 則報缺口並停止。Remote `/CER-auto` 首版不支援。
+2. 接受 `/CER-start` 前，完整讀取 [core-runtime.md](references/core-runtime.md) 及
+   [roadmap.md](references/roadmap.md)。
+3. 處理 `/CER-close` 時，只讀取 `core-runtime.md` 的「角色」、「小熊卡 package 版本」及
+   「獨立持久化與收工」，以及 `roadmap.md` 的「固定生命週期卡」。
+4. 處理 `/CER-stop` 時，只讀取 `core-runtime.md` 的「角色」、「小熊卡 package 版本」及
+   「停用 CER」，以及 `roadmap.md` 的「固定生命週期卡」；其他停點只讀相關段落。
+5. 只有角色座標或終態證據不完整、互相矛盾，或目標專案另有要求時才擴大讀取；不得只因指令是 stop／close 而完整重讀全部 references。
+6. CER 啟動後，目標 `AGENTS.md` 明確路由 Kit full closeout 或 governance bridge 時，只讀取 `core-runtime.md` 的「自足派工」相應規則，不另行設計 Kit 程序。
+7. 只有安裝驗收或 fresh UAT 才完整讀取 [uat.md](references/uat.md)。
+8. C 評估或使用平行候選生產者前，完整讀取
+   [parallel-producers.md](references/parallel-producers.md)；該檔是此能力的唯一完整 owner。
+
+## 操作指令
+
+slash command 是文字別名；平台不支援時，直接貼上同一句仍有效。
+
+| 指令 | 自然語言 | 效果 |
+|---|---|---|
+| `/CER-auto <任務、限制、優先序>` | `CER 自適應：...` | 本地 task 先選 ordinary execution、Goal、CER 工作法或 blocked；路線裁決前不成立 C；選到 CER 工作法才進完整 C／E／R，R 按風險決定。Remote 首版不支援。 |
+| `/CER-start <任務、限制、優先序>` | `CER 啟動：...` | 啟動 CER；本地或明確 Remote 接收 task 可成為唯一 C。單獨 `開工` 不啟動 CER。 |
+| `/CER-stop` | `停止 CER，改用單 thread 繼續。` | 按 runtime 收斂 active writer 後停用 CER。 |
+| `/CER-close` | `CER 收工。`／`CER 關閉。` | 按 runtime 收尾並證明 writer closed。單獨 `收工` 不觸發 CER close。 |
+| `/CER-status` | `顯示 CER 狀態。` | 只報 C 已知狀態、座標、停點及阻礙；不輪詢。 |
+| `/CER-help` | `顯示 CER 指令。` | 顯示本表與 `/CER-auto` 任務寫法。 |
+
+`/CER-auto` 任務寫法：用 `目標＋限制／不可做＋成功驗收＋權威來源／授權邊界`。需要例子時，按使用者情境生成，不固定行業：`/CER-auto 幫我比較/整理/修補 <你的資料或問題>；不要 <不可做的事>；成功條件是 <可驗收成果>；如要作正式決策、付款、發布或外部承諾，先停下改用 CER 工作法。`
+
+## 入口邊界
+
+- 完整唯一 C 啟動閘門由 `core-runtime.md` 擁有：candidate `C_READY` 與發送方讀回仍不足夠；
+  接收者實際收到 `C_ACCEPTED` 後才成為 active Controller（C）。
+- 正式 E／R 必須在同一 Codex project 側欄可見並由官方 `create_thread` 建立，不得用 inline sub-agent、fork 或 delegate 降級代替。每輪 `CER-start` 建立全新 E1，同一輪後續批次持續復用該同一 E1；每個 R 都必須是 fresh 新 task。完整拓撲、唯一 writer、Reviewer、批次、direct-push、result disposition、正式採用裁決、persistence 及 close 規則只在 `core-runtime.md` 定義。
+- 顯示標籤只作辨識：`🚀 C:01｜...`、`E1:01｜...`、`R1:01｜...`、`R2:01｜...`、
+  `E2:01｜...`。`00` 只可標示無法可靠回推的 legacy cycle；新 cycle 必須用 `01` 以上，
+  不顯示問號 cycle label。cycle 編號只供側欄辨識，完整 threadId 仍是權威；收尾改名失敗只報
+  `title sync warning`。卡片文字及 `VERSION` 讀法由 `roadmap.md`／`core-runtime.md` 擁有。
+- 真源攝取門檻只由 `core-runtime.md` 的 Controller preflight 擁有；`/CER-auto` 的路線選擇、重判及安全切換只由其「執行強度閘門」擁有；長任務防失焦檢查點只由其成果錨定與進展閘擁有。入口不重寫 profile、Reviewer、YAGNI 或停止規則。
+
+## 版本與藍圖邊界
+
+`v1` 是工作流世代，不是 package 版本；package 版本只來自本 Skill 同層的 `VERSION`。
+根目錄 `01_CER工作法_人類概覽.md` 與 `02_CER工作法_AI執行協議.md` 是來源專案的內部需求與驗收藍圖；Skill references 是實際操作規程。兩者對齊但互不擁有，不在入口複製 runtime。

package/skills/cer-workflow/VERSION

@@ -0,0 +1 @@
+0.3.17

package/skills/cer-workflow/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "CER 工作法"
+  short_description: "以正式角色閉環安全執行長期多批工作，並在合適時自動加速分析"
+  default_prompt: "使用 $cer-workflow 以唯一 writer 執行這項工作；按風險建立 fresh Reviewer，必要時在內部自動加速，無需額外設定。"
+policy:
+  allow_implicit_invocation: false