cowork-flow 0.0.48 → 0.0.49

package/README.md

@@ -46,6 +46,12 @@ cowork-flow sync ./my-project --dry-run
 # 同步已初始化项目
 cowork-flow sync ./my-project
 
+# 维护者：预览本仓库 source checkout live runtime / Skill replica 刷新
+npm run source:refresh:dry-run
+
+# 维护者：刷新 ignored root .cowork-flow、.agents/skills、.claude/skills
+npm run source:refresh
+
 # 预览 CLI 更新（不安装）
 cowork-flow update --dry-run
 
@@ -104,6 +110,7 @@ Skills 维护在 `template/skills/` 唯一源码，`init` / `sync` 时按目录
 |---|---|
 | `init <path>` | 初始化项目模板 |
 | `sync <path> [--dry-run]` | 同步已初始化项目的模板和技能 |
+| `source-refresh [path] [--dry-run]` | 维护者刷新 source checkout 的 ignored live runtime 与 Host Skill replica |
 | `install-zcode-plugin` | 安装 ZCode 插件到全局缓存 |
 | `update [--dry-run]` | 升级 CLI 本身 |
 
@@ -126,6 +133,13 @@ Skills 维护在 `template/skills/` 唯一源码，`init` / `sync` 时按目录
 - **Dry-run readiness**：`sync --dry-run` 只构建计划并输出 `readiness=<json>`，不写文件或事务状态；字段包含 `wouldCopy`、`wouldSkipProtected`、`wouldRemoveObsolete`、`hostAssetRefresh`、`pendingRecovery`、`warnings`
 - `--force` 整文件覆盖保护文件
 
+### source-refresh 行为
+
+- **用途**：仅面向 cowork-flow 源码 checkout 维护者；以 `template/.cowork-flow/` 和 `template/skills/` 为唯一 tracked 分发源，刷新 ignored 的根 `.cowork-flow/`、`.agents/skills/`、`.claude/skills/` 受管副本
+- **保护边界**：不覆盖 `.cowork-flow/tasks/`、`.cowork-flow/plans/`、`.cowork-flow/.runtime/`、`.cowork-flow/.developer`、`.cowork-flow/config.yaml` 和自定义 Skill
+- **事务语义**：复用 Asset Plan / plan applier，失败时回滚；`.cowork-flow/.version` 保持 version-last，并复制 template 版本文件的原始内容
+- **常用命令**：`npm run source:refresh:dry-run` 只预览；`npm run source:refresh` 应用后再运行 `./.cowork-flow/run doctor --all --json`
+
 ### update 行为
 
 - 默认查询 npm latest，发现新版本时执行 `npm install -g cowork-flow@latest`
@@ -251,6 +265,7 @@ npm run test:fast          # 快速 Node 测试，等价于 npm test
 npm run test:integration   # init/sync 关键集成路径
 npm run test:node:full     # 完整 Node 测试
 npm run test:template      # 核心模板集成测试
+npm run test:windows:core  # Windows core 发布信心门禁（Node/Python/init/sync/pack/模板）
 npm run test:template:full # 完整模板 Python discovery
 npm run test:all           # 发布前全量测试与打包检查
 npm run release:check     # 发布信心门禁；当前等价于 test:all
@@ -271,7 +286,7 @@ npm run release -- minor # minor
 
 - 发布说明维护在 `CHANGELOG.md`；发布前更新当前版本段落，并保留 `release:check` 和 `git diff --check` 证据。
 
-CI 需要 `NPM_TOKEN` secret。
+CI 的 PR 同时运行 Ubuntu core 与 Windows core；发布工作流要求 Ubuntu 与 Windows full verification 均成功后才执行 publish。测试 job 不接触 `NPM_TOKEN`，仅 publish job 使用该 secret。
 
 Windows 上发布前使用 `run.cmd` 入口验证；POSIX shell 专属 release 用例在没有 shell 的 Windows 环境会明确跳过，不得记录为通过。`release:check` 会保留这些 skip 报告，不把 skip 伪装成 pass。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-flow",
-  "version": "0.0.48",
+  "version": "0.0.49",
   "description": "CLI for installing and maintaining cowork-flow collaboration templates.",
   "type": "module",
   "bin": {
@@ -18,15 +18,18 @@
   ],
   "scripts": {
     "test": "npm run test:fast",
-    "test:fast": "node --test test/asset-plan.test.js test/cli.test.js test/host-assets.test.js test/opencode-plugin.test.js test/template-runner.test.js test/update.test.js test/zcode-plugin.test.js",
+    "test:fast": "node --test test/asset-plan.test.js test/cli.test.js test/host-assets.test.js test/opencode-plugin.test.js test/package.test.js test/template-runner.test.js test/update.test.js test/zcode-plugin.test.js",
     "test:integration": "node --test --test-name-pattern=\"^(init copies the template into a new target directory|sync updates safe template files and preserves protected files)$\" test/init.test.js test/sync.test.js",
     "test:node:full": "node --test",
     "test:template": "node scripts/run-template-tests.js --suite core",
     "test:template:full": "node scripts/run-template-tests.js --suite full",
     "pack:check": "node scripts/pack-check.js",
+    "source:refresh:dry-run": "node bin/cowork-flow.js source-refresh --dry-run",
+    "source:refresh": "node bin/cowork-flow.js source-refresh",
     "test:all": "npm run test:node:full && npm run test:template:full && npm run pack:check",
     "release:check": "npm run test:all",
-    "release": "sh scripts/release.sh"
+    "release": "sh scripts/release.sh",
+    "test:windows:core": "npm run test:fast && npm run test:integration && npm run pack:check && npm run test:template"
   },
   "engines": {
     "node": ">=20"

package/src/cli.js

@@ -4,6 +4,7 @@ import { createInterface } from 'node:readline/promises';
 
 import { runInit } from './commands/init.js';
 import { runInstallZCodePlugin } from './commands/install-zcode-plugin.js';
+import { runSourceRefresh } from './commands/source-refresh.js';
 import { runSync } from './commands/sync.js';
 import { runUpdate } from './commands/update.js';
 import { readPackageInfo } from './lib/package-info.js';
@@ -15,6 +16,7 @@ Usage:
   cowork-flow install-zcode-plugin [--dry-run] [--force] [--prune-old]
   cowork-flow update
   cowork-flow sync [target] [--dry-run] [--force]
+  cowork-flow source-refresh [target] [--dry-run]
   cowork-flow --version
   cowork-flow --help
 `;
@@ -173,6 +175,10 @@ export async function main(argv = process.argv.slice(2), options = {}) {
       return await runSync(args, { io });
     }
 
+    if (command === 'source-refresh') {
+      return await runSourceRefresh(args, { io });
+    }
+
     if (command === 'update') {
       return await runUpdate(args, { io });
     }

package/src/commands/source-refresh.js

@@ -0,0 +1,40 @@
+import { resolve } from 'node:path';
+
+import {
+  applyPlan,
+  buildReadinessReport,
+  buildSourceCheckoutRefreshPlan,
+  formatReadinessReport,
+  summarizePlan
+} from '../lib/copy-template.js';
+
+function parseSourceRefreshArgs(args) {
+  const options = { dryRun: false, target: process.cwd() };
+  for (const arg of args) {
+    if (arg === '--dry-run') {
+      options.dryRun = true;
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown source-refresh option: ${arg}`);
+    } else {
+      options.target = resolve(arg);
+    }
+  }
+  return options;
+}
+
+export async function runSourceRefresh(args, { io, fileSystem } = {}) {
+  const options = parseSourceRefreshArgs(args);
+  const plan = await buildSourceCheckoutRefreshPlan(options.target);
+
+  await applyPlan(plan, { dryRun: options.dryRun, fileSystem });
+  io.writeOut(summarizePlan(plan, options.dryRun));
+  if (options.dryRun) {
+    const readiness = await buildReadinessReport(plan, { fileSystem });
+    io.writeOut(formatReadinessReport(readiness));
+  }
+  io.writeOut('Source checkout refresh: template/.cowork-flow -> .cowork-flow; template/skills -> host Skill replicas\n');
+  if (!options.dryRun) {
+    io.writeOut('Next check: ./.cowork-flow/run doctor --all --json\n');
+  }
+  return 0;
+}

package/src/lib/copy-template.js

@@ -24,10 +24,13 @@ async function listFiles(root, current = root) {
   const files = [];
 
   for (const entry of entries) {
+    if (entry.name === '__pycache__') {
+      continue;
+    }
     const absolute = join(current, entry.name);
     if (entry.isDirectory()) {
       files.push(...await listFiles(root, absolute));
-    } else if (entry.isFile()) {
+    } else if (entry.isFile() && !entry.name.endsWith('.pyc')) {
       files.push(relative(root, absolute));
     }
   }
@@ -116,6 +119,67 @@ async function appendSkillFileActions(actions, {
   }
 }
 
+async function appendSkillTargetActions(actions, {
+  targetDir,
+  skillTargets,
+  seen,
+  sync = false
+}) {
+  const normalizedTargets = [...new Set(skillTargets.map(toTemplatePath))].sort();
+  for (const skill of await listSkillDirs()) {
+    const skillFiles = await listSkillFiles(skill);
+    for (const destBase of normalizedTargets) {
+      for (const skillFile of skillFiles) {
+        const destination = join(
+          targetDir,
+          destBase,
+          skill.id,
+          skillFile.skillRelativePath
+        );
+        if (seen.has(destination)) continue;
+        seen.add(destination);
+        const exists = await pathExists(destination);
+        const unchanged = sync && exists
+          ? await sourceMatchesDestination(skillFile.source, destination)
+          : false;
+        actions.push({
+          action: exists ? (sync ? (unchanged ? 'skip' : 'update') : 'skip') : 'create',
+          source: skillFile.source,
+          destination,
+          relativePath: join(destBase, skill.id, skillFile.skillRelativePath)
+        });
+      }
+    }
+  }
+}
+
+function isSourceCheckoutProtected(relativePath) {
+  const normalized = toTemplatePath(relativePath);
+  if (hostRegistry.syncPolicy.protectedFiles.includes(normalized)) {
+    return true;
+  }
+  return hostRegistry.syncPolicy.protectedPrefixes
+    .filter((prefix) => prefix !== '.cowork-flow/spec/')
+    .some((prefix) => normalized.startsWith(prefix))
+    || normalized.startsWith('.cowork-flow/.runtime/');
+}
+
+function shouldIncludeSourceCheckoutRuntimeFile(relativePath) {
+  const normalized = toTemplatePath(relativePath);
+  return normalized.startsWith('.cowork-flow/')
+    && normalized !== '.cowork-flow/.version'
+    && !isSourceCheckoutProtected(normalized);
+}
+
+function isSourceRefreshObsoleteFile(relativePath) {
+  const normalized = toTemplatePath(relativePath);
+  if (isSourceCheckoutProtected(normalized)) {
+    return false;
+  }
+  return normalized.startsWith('.cowork-flow/')
+    || hostRegistry.skillTargets.some((target) => normalized.startsWith(`${target}/`));
+}
+
 export async function buildInitPlan(targetDir, options = {}) {
   const files = await listFiles(templateRoot);
   const actions = [];
@@ -230,6 +294,71 @@ async function buildFileSyncAction({ source, destination, relativePath }) {
   };
 }
 
+export async function buildSourceCheckoutRefreshPlan(targetDir, options = {}) {
+  const files = await listFiles(templateRoot);
+  const actions = [];
+  const seen = new Set();
+
+  for (const file of files) {
+    const templatePath = toTemplatePath(file);
+    if (!shouldIncludeSourceCheckoutRuntimeFile(templatePath)) {
+      continue;
+    }
+    const source = join(templateRoot, file);
+    const destination = join(targetDir, file);
+    seen.add(destination);
+    const exists = await pathExists(destination);
+    if (!exists) {
+      actions.push({ action: 'create', source, destination, relativePath: file });
+      continue;
+    }
+    actions.push(await buildFileSyncAction({
+      source,
+      destination,
+      relativePath: file
+    }));
+  }
+
+  await appendSkillTargetActions(actions, {
+    targetDir,
+    skillTargets: options.skillTargets ?? hostRegistry.skillTargets,
+    seen,
+    sync: true
+  });
+
+  const deletedObsoleteParents = [];
+  for (const file of hostRegistry.obsoleteSyncFiles()) {
+    if (!isSourceRefreshObsoleteFile(file) || isCoveredByDeletedParent(file, deletedObsoleteParents)) {
+      continue;
+    }
+    const destination = join(targetDir, file);
+    if (await pathExists(destination)) {
+      deletedObsoleteParents.push(file);
+      actions.push({ action: 'delete', source: null, destination, relativePath: file });
+    }
+  }
+
+  const versionDestination = join(targetDir, '.cowork-flow', '.version');
+  const versionSource = join(templateRoot, '.cowork-flow', '.version');
+  const versionContent = await readFile(versionSource, 'utf8');
+  const versionExists = await pathExists(versionDestination);
+  const versionUnchanged = versionExists
+    && (await readFile(versionDestination, 'utf8')) === versionContent;
+  actions.push({
+    action: versionExists ? (versionUnchanged ? 'skip' : 'update') : 'create',
+    source: null,
+    destination: versionDestination,
+    relativePath: '.cowork-flow/.version',
+    content: versionContent
+  });
+
+  return createAssetPlan({
+    kind: 'source-refresh',
+    targetDir,
+    actions
+  });
+}
+
 export async function buildSyncPlan(targetDir, options = {}) {
   if (!await pathExists(join(targetDir, '.cowork-flow'))) {
     throw new Error(`Target is not initialized: ${targetDir}`);

package/src/lib/host-assets.js

@@ -4,13 +4,14 @@ import { join } from 'node:path';
 import { templateRoot } from './paths.js';
 
 
-export const hostAssetManifestPath = join(
-  templateRoot,
-  '.cowork-flow',
-  'spec',
-  'runtime',
-  'host-assets.json'
-);
+export const hostAssetManifestPath = process.env.COWORK_FLOW_HOST_ASSET_MANIFEST
+  || join(
+    templateRoot,
+    '.cowork-flow',
+    'spec',
+    'runtime',
+    'host-assets.json'
+  );
 
 const REQUIRED_HOST_NEUTRAL_CAPABILITIES = [
   'task_action',
@@ -24,6 +25,45 @@ const REQUIRED_CAPABILITY_MATRIX_HOSTS = [
   'opencode',
   'zcode'
 ];
+const CAPABILITY_STATUS_VALUES = [
+  'native',
+  'shim',
+  'plugin',
+  'external',
+  'experimental',
+  'unsupported'
+];
+const CAPABILITY_DECLARATION_KEYS = ['status', 'fallback'];
+const COMMAND_TARGET_KEYS = ['config', 'format', 'target'];
+const COMMAND_TARGET_FORMATS = ['json', 'toml', 'yaml'];
+const MANIFEST_KEYS = [
+  'schemaVersion',
+  'capabilityValues',
+  'capabilityMatrix',
+  'platforms',
+  'excludedPrefixes',
+  'syncPolicy'
+];
+const PLATFORM_KEYS = [
+  'id',
+  'displayName',
+  'aliases',
+  'detectAny',
+  'assetPrefixes',
+  'assetFiles',
+  'skillTarget',
+  'adapterPath',
+  'capabilities',
+  'commandTargets'
+];
+const SYNC_POLICY_KEYS = [
+  'protectedFiles',
+  'protectedPrefixes',
+  'safeFiles',
+  'safePrefixes',
+  'managedBlockFiles',
+  'obsoleteFiles'
+];
 
 
 export function loadHostAssetManifest(path = hostAssetManifestPath) {
@@ -229,74 +269,135 @@ function validateManifest(manifest) {
   if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
     throw new Error('Host Asset Manifest must be an object');
   }
+  assertKnownKeys(manifest, MANIFEST_KEYS, 'Host Asset Manifest');
   if (manifest.schemaVersion !== 1) {
     throw new Error(
       `Unsupported Host Asset Manifest schemaVersion: ${manifest.schemaVersion}`
     );
   }
+  const allowed = validateCapabilityValues(manifest.capabilityValues);
   if (!Array.isArray(manifest.platforms) || manifest.platforms.length === 0) {
     throw new Error(
       'Host Asset Manifest platforms must be a non-empty array'
     );
   }
-  if (!Array.isArray(manifest.excludedPrefixes)) {
+  const platformIds = [];
+  const seenPlatformIds = new Set();
+  const aliases = new Map();
+  for (const platform of manifest.platforms) {
+    validatePlatform(platform, allowed, seenPlatformIds, aliases);
+    platformIds.push(platform.id);
+  }
+  validateStringArray(
+    manifest.excludedPrefixes,
+    'Host Asset Manifest excludedPrefixes'
+  );
+  validateCapabilityMatrix(manifest.capabilityMatrix, allowed, platformIds);
+  validateSyncPolicy(manifest.syncPolicy);
+}
+
+function validateCapabilityValues(values) {
+  validateStringArray(
+    values,
+    'Host Asset Manifest capabilityValues',
+    { unique: true }
+  );
+  if (!arraysEqual(values, CAPABILITY_STATUS_VALUES)) {
     throw new Error(
-      'Host Asset Manifest excludedPrefixes must be an array'
+      `Host Asset Manifest capabilityValues must be ${CAPABILITY_STATUS_VALUES.join(', ')}`
     );
   }
-  validateCapabilityMatrix(manifest);
-  if (!manifest.syncPolicy || typeof manifest.syncPolicy !== 'object') {
-    throw new Error('Host Asset Manifest syncPolicy must be an object');
+  return new Set(CAPABILITY_STATUS_VALUES);
+}
+
+function validatePlatform(platform, allowed, seenPlatformIds, aliases) {
+  if (!platform || typeof platform !== 'object' || Array.isArray(platform)) {
+    throw new Error('Every host platform must be an object');
   }
-  for (const platform of manifest.platforms) {
-    if (!platform || typeof platform !== 'object' || !platform.id) {
-      throw new Error('Every host platform must define an id');
-    }
-    for (const key of [
-      'aliases',
-      'detectAny',
-      'assetPrefixes',
-      'assetFiles',
-      'commandTargets'
-    ]) {
-      if (!Array.isArray(platform[key])) {
-        throw new Error(
-          `Host platform ${platform.id} ${key} must be an array`
-        );
-      }
+  assertKnownKeys(platform, PLATFORM_KEYS, `Host platform ${platform.id ?? '<unknown>'}`);
+  validateRequiredString(platform.id, 'Host platform id');
+  if (seenPlatformIds.has(platform.id)) {
+    throw new Error(`Duplicate host platform id: ${platform.id}`);
+  }
+  seenPlatformIds.add(platform.id);
+  validateRequiredString(platform.displayName, `Host platform ${platform.id} displayName`);
+  validateStringArray(platform.aliases, `Host platform ${platform.id} aliases`);
+  for (const alias of platform.aliases) {
+    const normalized = alias.toLowerCase();
+    const owner = aliases.get(normalized);
+    if (owner !== undefined) {
+      throw new Error(`Duplicate platform alias: ${alias}`);
     }
+    aliases.set(normalized, platform.id);
   }
-  for (const key of [
-    'protectedFiles',
-    'protectedPrefixes',
-    'safeFiles',
-    'safePrefixes',
-    'managedBlockFiles',
-    'obsoleteFiles'
-  ]) {
-    if (!Array.isArray(manifest.syncPolicy[key])) {
-      throw new Error(
-        `Host Asset Manifest syncPolicy.${key} must be an array`
-      );
+  validateStringArray(platform.detectAny, `Host platform ${platform.id} detectAny`);
+  validateStringArray(platform.assetPrefixes, `Host platform ${platform.id} assetPrefixes`);
+  validateStringArray(platform.assetFiles, `Host platform ${platform.id} assetFiles`);
+  if (platform.skillTarget !== null && typeof platform.skillTarget !== 'string') {
+    throw new Error(`Host platform ${platform.id} skillTarget must be a string or null`);
+  }
+  if (typeof platform.skillTarget === 'string' && platform.skillTarget.length === 0) {
+    throw new Error(`Host platform ${platform.id} skillTarget must be a non-empty string or null`);
+  }
+  validateRequiredString(platform.adapterPath, `Host platform ${platform.id} adapterPath`);
+  validatePlatformCapabilities(platform, allowed);
+  if (!Array.isArray(platform.commandTargets)) {
+    throw new Error(`Host platform ${platform.id} commandTargets must be an array`);
+  }
+  for (const target of platform.commandTargets) {
+    validateCommandTarget(target, platform.id);
+  }
+}
+
+function validatePlatformCapabilities(platform, allowed) {
+  if (!platform.capabilities || typeof platform.capabilities !== 'object' || Array.isArray(platform.capabilities)) {
+    throw new Error(`Host platform ${platform.id} capabilities must be an object`);
+  }
+  if (Object.keys(platform.capabilities).length === 0) {
+    throw new Error(`Host platform ${platform.id} capabilities must be a non-empty object`);
+  }
+  for (const [name, value] of Object.entries(platform.capabilities)) {
+    validateRequiredString(name, `Host platform ${platform.id} capability name`);
+    if (typeof value !== 'string' || !allowed.has(value)) {
+      throw new Error(`Host platform ${platform.id} illegal capability status ${name}=${value}`);
     }
   }
 }
 
+function validateCommandTarget(target, platformId) {
+  if (!target || typeof target !== 'object' || Array.isArray(target)) {
+    throw new Error(`Host platform ${platformId} commandTargets must be objects`);
+  }
+  assertKnownKeys(target, COMMAND_TARGET_KEYS, `Host platform ${platformId} commandTarget`);
+  validateRequiredString(target.config, `Host platform ${platformId} commandTarget.config`);
+  validateRequiredString(target.target, `Host platform ${platformId} commandTarget.target`);
+  if (!COMMAND_TARGET_FORMATS.includes(target.format)) {
+    throw new Error(`Host platform ${platformId} commandTarget.format must be json, toml, or yaml`);
+  }
+}
 
-function validateCapabilityMatrix(manifest) {
-  if (!Array.isArray(manifest.capabilityValues) || manifest.capabilityValues.length === 0) {
-    throw new Error('Host Asset Manifest capabilityValues must be a non-empty array');
+function validateSyncPolicy(syncPolicy) {
+  if (!syncPolicy || typeof syncPolicy !== 'object' || Array.isArray(syncPolicy)) {
+    throw new Error('Host Asset Manifest syncPolicy must be an object');
   }
-  const allowed = new Set(manifest.capabilityValues);
-  for (const value of allowed) {
-    if (typeof value !== 'string' || value.length === 0) {
-      throw new Error('Host Asset Manifest capabilityValues entries must be strings');
-    }
+  assertKnownKeys(syncPolicy, SYNC_POLICY_KEYS, 'Host Asset Manifest syncPolicy');
+  for (const key of SYNC_POLICY_KEYS) {
+    validateStringArray(
+      syncPolicy[key],
+      `Host Asset Manifest syncPolicy.${key}`
+    );
   }
-  const matrix = manifest.capabilityMatrix;
+}
+
+function validateCapabilityMatrix(matrix, allowed, platformIds) {
   if (!matrix || typeof matrix !== 'object' || Array.isArray(matrix)) {
     throw new Error('Host Asset Manifest capabilityMatrix must be an object');
   }
+  assertKnownKeys(matrix, ['required', 'hosts'], 'Host Asset Manifest capabilityMatrix');
+  validateStringArray(
+    matrix.required,
+    'Host Asset Manifest capabilityMatrix.required'
+  );
   if (!arraysEqual(matrix.required, REQUIRED_HOST_NEUTRAL_CAPABILITIES)) {
     throw new Error(
       `Host Asset Manifest capabilityMatrix.required must be ${REQUIRED_HOST_NEUTRAL_CAPABILITIES.join(', ')}`
@@ -307,7 +408,7 @@ function validateCapabilityMatrix(manifest) {
   }
   const requiredHosts = new Set([
     ...REQUIRED_CAPABILITY_MATRIX_HOSTS,
-    ...manifest.platforms.map((platform) => platform.id)
+    ...platformIds
   ]);
   for (const hostId of [...requiredHosts].sort()) {
     if (!matrix.hosts[hostId]) {
@@ -315,6 +416,7 @@ function validateCapabilityMatrix(manifest) {
     }
   }
   for (const [hostId, capabilities] of Object.entries(matrix.hosts)) {
+    validateRequiredString(hostId, 'Host Asset Manifest capabilityMatrix host id');
     if (!capabilities || typeof capabilities !== 'object' || Array.isArray(capabilities)) {
       throw new Error(`Host Asset Manifest capabilityMatrix host ${hostId} must be an object`);
     }
@@ -324,31 +426,74 @@ function validateCapabilityMatrix(manifest) {
       }
     }
     for (const capability of REQUIRED_HOST_NEUTRAL_CAPABILITIES) {
-      const declaration = capabilities[capability];
-      if (!declaration || typeof declaration !== 'object' || Array.isArray(declaration)) {
-        throw new Error(`Host Asset Manifest missing host-neutral capability ${hostId}:${capability}`);
-      }
-      if (!allowed.has(declaration.status)) {
-        throw new Error(
-          `Host Asset Manifest illegal host-neutral capability ${hostId}:${capability}=${declaration.status}`
-        );
-      }
-      if (declaration.fallback !== undefined && (
-        typeof declaration.fallback !== 'string' || declaration.fallback.length === 0
-      )) {
-        throw new Error(
-          `Host Asset Manifest capability fallback must be a non-empty string: ${hostId}:${capability}`
-        );
-      }
-      if (declaration.status === 'unsupported' && !declaration.fallback) {
-        throw new Error(
-          `Host Asset Manifest unsupported capability requires fallback: ${hostId}:${capability}`
-        );
-      }
+      validateCapabilityDeclaration(
+        capabilities[capability],
+        allowed,
+        hostId,
+        capability
+      );
+    }
+  }
+}
+
+function validateCapabilityDeclaration(declaration, allowed, hostId, capability) {
+  if (!declaration || typeof declaration !== 'object' || Array.isArray(declaration)) {
+    throw new Error(`Host Asset Manifest missing host-neutral capability ${hostId}:${capability}`);
+  }
+  assertKnownKeys(
+    declaration,
+    CAPABILITY_DECLARATION_KEYS,
+    `Host Asset Manifest capabilityMatrix.hosts.${hostId}.${capability}`
+  );
+  if (!allowed.has(declaration.status)) {
+    throw new Error(
+      `Host Asset Manifest illegal host-neutral capability ${hostId}:${capability}=${declaration.status}`
+    );
+  }
+  if (declaration.fallback !== undefined && (
+    typeof declaration.fallback !== 'string' || declaration.fallback.length === 0
+  )) {
+    throw new Error(
+      `Host Asset Manifest capability fallback must be a non-empty string: ${hostId}:${capability}`
+    );
+  }
+  if (declaration.status === 'unsupported' && !declaration.fallback) {
+    throw new Error(
+      `Host Asset Manifest unsupported capability requires fallback: ${hostId}:${capability}`
+    );
+  }
+}
+
+function validateRequiredString(value, label) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+}
+
+function validateStringArray(value, label, { unique = false } = {}) {
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array`);
+  }
+  const seen = new Set();
+  for (const item of value) {
+    if (typeof item !== 'string' || item.length === 0) {
+      throw new Error(`${label} entries must be non-empty strings`);
     }
+    if (unique && seen.has(item)) {
+      throw new Error(`${label} entries must be unique: ${item}`);
+    }
+    seen.add(item);
   }
 }
 
+function assertKnownKeys(value, allowedKeys, label) {
+  const allowed = new Set(allowedKeys);
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) {
+      throw new Error(`${label} unknown field: ${key}`);
+    }
+  }
+}
 
 function normalizeCapabilityMatrix(matrix) {
   return {

package/template/.codex/hooks.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": ".codex/hooks/inject-workflow-state.py",
+            "command": ".cowork-flow/run python .codex/hooks/inject-workflow-state.py",
             "timeout": 5
           }
         ]

package/template/.cowork-flow/.version

@@ -1 +1 @@
-0.0.48
+0.0.49