code-workspace-zhuiyi 0.1.0-beta.2 → 0.1.0-beta.3

package/README.md

@@ -37,7 +37,7 @@ Use `--tools claude`, `--tools codex`, or `--tools none` to override the default
 
 Initialization writes only Workspace-owned state and integrations:
 
-- `.code-workspace/config.yaml` and `.code-workspace/state.json`
+- `.code-workspace/config.yaml`, `.code-workspace/config-projects.yaml`, and `.code-workspace/state.json`
 - `USER_GUIDE.md`
 - `CLAUDE.md` and/or `AGENTS.md`
 - Workspace-specific commands and skills whose names start with `code-workspace-` or use the `/code-workspace` namespace
@@ -50,20 +50,20 @@ It does not create `openspec/`, install native `/opsx` commands, or install nati
 `init` can install integrations from the versioned `extensions/` repository shipped inside this npm package. Select extension names interactively, or pass a comma-separated name list non-interactively. The dedicated install command accepts one or more names; without names it opens the built-in extension multiselect, where ESC exits without changes:
 
 ```bash
-code-w init . --extensions openspec-workspace --yes
+code-w init . --extensions zhuiyi-jira-mcp --yes
 code-w init . --extensions none --yes
 code-w extension install
-code-w extension install openspec-workspace --yes
-code-w extension uninstall openspec-workspace --yes
+code-w extension install zhuiyi-jira-mcp --yes
+code-w extension uninstall zhuiyi-jira-mcp --yes
 ```
 
 The Workspace operation lock shared by init, extension install, and extension uninstall is configured in the Code Workspace project's `.env` (not in the target Workspace). `CODE_WORKSPACE_INIT_LOCK_UPDATE_MS` defaults to `5000`, and `CODE_WORKSPACE_INIT_LOCK_STALE_MS` defaults to `30000`; process environment variables take precedence. See `.env.example` for the project configuration names.
 
-Users select names, not versions; `openspec-workspace@1.0.0` is intentionally rejected. Code Workspace resolves the highest extension SemVer implemented against a Host-supported Extension Spec before confirmation. A new non-interactive Workspace installs no extensions unless `--extensions` is provided. Re-initializing an existing Workspace defaults to its installed extensions and upgrades them when a newer supported built-in version exists. `none` skips extension work and does not uninstall existing artifacts.
+Users select names, not versions; `zhuiyi-jira-mcp@0.1.0` is intentionally rejected. Code Workspace resolves the highest extension SemVer implemented against a Host-supported Extension Spec before confirmation. A new non-interactive Workspace installs no extensions unless `--extensions` is provided. Re-initializing an existing Workspace defaults to its installed extensions and upgrades them when a newer supported built-in version exists. `none` skips extension work and does not uninstall existing artifacts.
 
 `extension install` does not rerun core Workspace initialization. In JSON, non-TTY, or `--yes` mode, at least one extension name is required. Multiple names are installed in order with one confirmation boundary and independent transactions; any failure makes the install command fail while later extensions still run.
 
-The bundled `openspec-workspace` extension installs a namespaced `code-workspace-openspec-propose` skill for the selected Agent tools. It does not create an `openspec/` directory or install native OpenSpec commands.
+The bundled `zhuiyi-jira-mcp` extension configures the Jira MCP service for the selected Agent tools. It does not create an `openspec/` directory or install native OpenSpec commands.
 
 Extension entries run in separate Node processes and generate files in temporary staging directories. The host rejects undeclared, missing, symbolic-link, non-file, path-escaping, conflicting, and checksum-mismatched artifacts before transactionally installing them. Per-Workspace state is stored in `.code-workspace/ext-manifest.json`. A failed extension is reported as a warning and does not roll back successful core initialization or stop later extensions; a failed upgrade restores and retains the previous installed version.
 
@@ -93,6 +93,30 @@ code-workspace project add --projects-file projects.json --yes --json
 
 The registry stores each project's name, real location, registered branch, type, and context. The registered branch is the Code Workspace expected state; the actual branch is observed from the selected Git worktree. Workspace never guesses a path from a conversation or automatically decides which branch is authoritative.
 
+Project registration is always stored in the separate `.code-workspace/config-projects.yaml` file. The main configuration contains only its fixed local reference:
+
+```yaml
+# .code-workspace/config.yaml
+projects:
+  ref: config-projects.yaml
+```
+
+The referenced file uses this format:
+
+```yaml
+# .code-workspace/config-projects.yaml
+schemaVersion: 1
+projects:
+  - name: payments
+    location: /absolute/path/to/payments
+    branch: main
+    type: backend
+    context: |-
+      Service ownership and navigation context.
+```
+
+`projects.ref` is resolved relative to `config.yaml` and must be exactly `config-projects.yaml`. URLs, globs, absolute paths, path traversal, and inline `projects` arrays are not supported. All project commands keep their existing CLI semantics; they read and write the referenced project file. The `.code-workspace/` directory is ignored by default, so Git history for this local registry requires an explicit repository policy.
+
 ## Daily commands
 
 ```bash
@@ -117,11 +141,18 @@ The two reconciliation directions are deliberately separate:
 
 Both commands detect plan drift and verify postconditions. `project branch update-latest` is the separate, opt-in path for projects with `updateLatest: true`; it only fetches the configured upstream and fast-forwards a clean matching branch. Code Workspace never creates or downloads a branch and never performs stash, reset, rebase, non-fast-forward merge, production-code edits, or conflict resolution.
 
-Users may manually set the optional project policy in `.code-workspace/config.yaml`:
+Users may manually set the optional project policy in `.code-workspace/config-projects.yaml`:
 
 ```yaml
+# .code-workspace/config-projects.yaml
+schemaVersion: 1
 projects:
   - name: payments
+    location: /absolute/path/to/payments
+    branch: main
+    type: backend
+    context: |-
+      Service ownership and navigation context.
     updateLatest: true
 ```
 

package/README.zh-CN.md

@@ -37,7 +37,7 @@ code-workspace init . \
 
 初始化只写入 Workspace 自有状态和集成：
 
-- `.code-workspace/config.yaml` 与 `.code-workspace/state.json`
+- `.code-workspace/config.yaml`、`.code-workspace/config-projects.yaml` 与 `.code-workspace/state.json`
 - `USER_GUIDE.md`
 - `CLAUDE.md` 和/或 `AGENTS.md`
 - 名称以 `code-workspace-` 开头或使用 `/code-workspace` 命名空间的 Workspace 专用命令与 Skill
@@ -50,20 +50,20 @@ code-workspace init . \
 `init` 可以从 npm 包内随附的版本化 `extensions/` 仓库安装集成。交互模式按扩展名多选；非交互模式传入逗号分隔的扩展名。独立安装命令接受一个或多个扩展名；不传名称时打开内置扩展多选，按 ESC 可无修改退出：
 
 ```bash
-code-w init . --extensions openspec-workspace --yes
+code-w init . --extensions zhuiyi-jira-mcp --yes
 code-w init . --extensions none --yes
 code-w extension install
-code-w extension install openspec-workspace --yes
-code-w extension uninstall openspec-workspace --yes
+code-w extension install zhuiyi-jira-mcp --yes
+code-w extension uninstall zhuiyi-jira-mcp --yes
 ```
 
 `init`、扩展安装和扩展卸载共享的 Workspace 操作锁配置在 Code Workspace 项目自身的 `.env` 中（不在目标 Workspace 中）。`CODE_WORKSPACE_INIT_LOCK_UPDATE_MS` 默认值为 `5000`，`CODE_WORKSPACE_INIT_LOCK_STALE_MS` 默认值为 `30000`；进程环境变量优先于 `.env`。配置项名称见 `.env.example`。
 
-用户只选择扩展名，不能选择版本；`openspec-workspace@1.0.0` 会被明确拒绝。Code Workspace 在确认前，从 Host 明确支持的 Extension Spec 实现中解析最高扩展 SemVer。新 Workspace 非交互初始化时，未传 `--extensions` 就不安装扩展；已有 Workspace 重新初始化时，默认选择已安装扩展，并在存在更高受支持内置版本时升级。`none` 只跳过本次扩展初始化，不会卸载已有制品。
+用户只选择扩展名，不能选择版本；`zhuiyi-jira-mcp@0.1.0` 会被明确拒绝。Code Workspace 在确认前，从 Host 明确支持的 Extension Spec 实现中解析最高扩展 SemVer。新 Workspace 非交互初始化时，未传 `--extensions` 就不安装扩展；已有 Workspace 重新初始化时，默认选择已安装扩展，并在存在更高受支持内置版本时升级。`none` 只跳过本次扩展初始化，不会卸载已有制品。
 
 `extension install` 不会重新执行 Workspace 核心初始化。在 JSON、非 TTY 或 `--yes` 模式下，必须至少提供一个扩展名。多个名称按顺序安装，只确认一次且各自使用独立事务；任一扩展失败会使安装命令失败，但后续扩展仍会继续执行。
 
-内置 `openspec-workspace` 扩展会为选中的 Agent 工具安装命名空间为 `code-workspace-openspec-propose` 的 Skill；它不会创建 `openspec/` 目录，也不会安装 OpenSpec 原生命令。
+当前随包提供的内置扩展是 `zhuiyi-jira-mcp`，用于为选中的 Agent 工具配置 Jira MCP 服务；它不会创建 `openspec/` 目录，也不会安装 OpenSpec 原生命令。
 
 扩展入口在独立 Node 进程中运行，只向临时 staging 目录生成文件。Host 会在事务安装前拒绝未声明、缺失、符号链接、非文件、路径逃逸、目标冲突和 hash 不匹配的制品。Workspace 状态存放在 `.code-workspace/ext-manifest.json`。扩展失败以 warning 报告，不回滚已成功的核心初始化，也不阻止后续扩展；升级失败会恢复并保留旧的已安装版本。
 
@@ -93,6 +93,30 @@ code-workspace project add --projects-file projects.json --yes --json
 
 注册表保存项目名称、真实路径、注册分支、类型和上下文。注册分支是 Code Workspace 的期望状态，实际分支是从选中 Git worktree 观测到的状态。Workspace 不会根据对话猜测路径，也不会自动判断哪一侧分支更权威。
 
+项目注册配置始终独立保存于 `.code-workspace/config-projects.yaml`。主配置只保存固定的本地引用：
+
+```yaml
+# .code-workspace/config.yaml
+projects:
+  ref: config-projects.yaml
+```
+
+引用文件使用以下格式：
+
+```yaml
+# .code-workspace/config-projects.yaml
+schemaVersion: 1
+projects:
+  - name: payments
+    location: /absolute/path/to/payments
+    branch: main
+    type: backend
+    context: |-
+      服务职责和代码导航上下文。
+```
+
+`projects.ref` 相对于 `config.yaml` 解析，并且必须是 `config-projects.yaml`。不支持 URL、glob、绝对路径、路径逃逸或内联 `projects` 数组。所有项目 CLI 的语义保持不变，只是改为读取和写入引用文件。`.code-workspace/` 默认被忽略；如需 Git 历史，需要显式制定仓库策略。
+
 ## 日常命令
 
 ```bash
@@ -117,11 +141,18 @@ code-workspace doctor --json
 
 两条命令都会检查计划漂移并验证后置条件。`project branch update-latest` 是独立的显式配置路径：仅当项目 `updateLatest: true` 时，才对干净且分支一致的 worktree fetch upstream 并 fast-forward。Code Workspace 不会创建或下载分支，也不会执行 stash、reset、rebase、非 fast-forward merge、生产代码编辑或冲突处理。
 
-用户可以手动在 `.code-workspace/config.yaml` 中设置项目策略：
+用户可以手动在 `.code-workspace/config-projects.yaml` 中设置项目策略：
 
 ```yaml
+# .code-workspace/config-projects.yaml
+schemaVersion: 1
 projects:
   - name: payments
+    location: /absolute/path/to/payments
+    branch: main
+    type: backend
+    context: |-
+      服务职责和代码导航上下文。
     updateLatest: true
 ```
 

package/artifacts/manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "releaseVersion": "0.1.0-beta.2",
+  "releaseVersion": "0.1.0-beta.3",
   "requirements": {
     "node": ">=20.19.0"
   },

package/extensions/zhuiyi-jira-mcp/0.1.0/artifacts/claude/server.json

@@ -5,10 +5,12 @@
   ],
   "env": {
     "JIRA_AUTH_TYPE": "cookie",
+    "JIRA_COOKIE": "",
     "JIRA_API_VERSION": "latest",
     "JIRA_ALLOWED_HOSTS": "jira.in.wezhuiyi.com",
     "JIRA_REQUIREMENT_FIELDS": "{\"acceptanceCriteria\":\"customfield_10042\",\"storyPoints\":\"customfield_10016\"}",
     "JIRA_ATTACHMENT_DIR": ".jira-attachments",
-    "JIRA_ATTACHMENT_MAX_SIZE": "20MB"
+    "JIRA_ATTACHMENT_MAX_SIZE": "20MB",
+    "JIRA_ATTACHMENT_ALLOWED_TYPES": "pdf,png,jpg,jpeg,gif,webp,txt,md,csv,json,xml,doc,docx,xls,xlsx,ppt,pptx,html"
   }
 }

package/extensions/zhuiyi-jira-mcp/0.1.0/artifacts/codex/config.toml

@@ -4,8 +4,10 @@ args = [".code-workspace/extensions/zhuiyi-jira-mcp/0.1.0/dist/index.js"]
 
 [mcp_servers.zhuiyi-jira.env]
 JIRA_AUTH_TYPE = "cookie"
+JIRA_COOKIE = ""
 JIRA_API_VERSION = "latest"
 JIRA_ALLOWED_HOSTS = "jira.in.wezhuiyi.com"
 JIRA_REQUIREMENT_FIELDS = '{"acceptanceCriteria":"customfield_10042","storyPoints":"customfield_10016"}'
 JIRA_ATTACHMENT_DIR = ".jira-attachments"
 JIRA_ATTACHMENT_MAX_SIZE = "20MB"
+JIRA_ATTACHMENT_ALLOWED_TYPES = "pdf,png,jpg,jpeg,gif,webp,txt,md,csv,json,xml,doc,docx,xls,xlsx,ppt,pptx,html"

package/extensions/zhuiyi-jira-mcp/0.1.0/artifacts/gitignore

@@ -0,0 +1,2 @@
+# Zhuiyi Jira MCP attachments
+/.jira-attachments/

package/extensions/zhuiyi-jira-mcp/0.1.0/init.js

@@ -30,6 +30,9 @@ async function main() {
   await prepareRelease(release, runtime);
   outputs.push({ id: "runtime", source: "runtime" });
 
+  copyOutput(outputRoot, "artifacts/gitignore", "gitignore");
+  outputs.push({ id: "gitignore", source: "gitignore" });
+
   if (context.tools.includes("codex")) {
     copyOutput(outputRoot, "artifacts/codex/config.toml", "codex-config.toml");
     outputs.push({ id: "codex-config", source: "codex-config.toml" });

package/extensions/zhuiyi-jira-mcp/0.1.0/manifest.json

@@ -6,7 +6,7 @@
   "name": "Zhuiyi Jira MCP",
   "version": "0.1.0",
   "entry": "init.js",
-  "entrySha256": "af7f4a71835402235b3d763418ee1b4135da0125a85aff1153bfaa0f6c83a022",
+  "entrySha256": "53a814ffcbc5669a024f921c5c30e74385d334b749913b0212bdcc2e48a2e0bd",
   "timeoutMs": 120000,
   "capabilities": {
     "networkHosts": ["gitee.com", "raw.giteeusercontent.com"]
@@ -18,6 +18,13 @@
       "ownership": "exclusive",
       "target": ".code-workspace/extensions/zhuiyi-jira-mcp/0.1.0"
     },
+    {
+      "id": "gitignore",
+      "kind": "text-block",
+      "ownership": "shared",
+      "target": ".gitignore",
+      "format": "text"
+    },
     {
       "id": "codex-config",
       "kind": "text-block",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-workspace-zhuiyi",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.3",
   "description": "Local multi-project registry and safety layer for AI coding workspaces",
   "author": "icebearx-ai",
   "license": "MIT",

package/src/cli/commands/extension.js

@@ -95,7 +95,7 @@ async function executeExtensionInstall(invocation) {
   let requested = invocation.args.length > 0 ? normalizeExtensionNames(invocation.args) : null;
   if (requested === null && !interactive) {
     throw new WorkspaceError("EXTENSION_SELECTION_REQUIRED", "Extension installation requires one or more extension names outside interactive mode.", {
-      remediation: "Pass one or more names, for example: code-w extension install openspec-workspace --yes",
+      remediation: "Pass one or more extension names, for example: code-w extension install <extension-name> --yes",
     });
   }
 

package/src/cli/commands/project-branch.js

@@ -1,4 +1,4 @@
-const { configPath, loadConfigProjection, updateProjectBranch } = require("../../core/config");
+const { configPath, loadConfigProjection, projectConfigPath, updateProjectBranch } = require("../../core/config");
 const { WorkspaceError } = require("../../core/errors");
 const {
   assertRegisteredBranchSwitchAvailable,
@@ -54,7 +54,7 @@ function applyAcceptActual(root, plan, options = {}) {
   const currentConfig = load(root, ["projects"]);
   assertAcceptPlanCurrent(plan, inspect(currentConfig, plan.project.name, options));
 
-  const transaction = createFileTransaction([configPath(root)]);
+  const transaction = createFileTransaction([configPath(root), projectConfigPath(root)]);
   try {
     (options.updateProjectBranch || updateProjectBranch)(root, {
       name: plan.project.name,

package/src/cli/commands/update.js

@@ -5,6 +5,7 @@ const {
   configPath,
   loadConfig,
   loadState,
+  projectConfigPath,
   saveConfig,
   statePath,
 } = require("../../core/config");
@@ -82,6 +83,7 @@ function updateWorkspace(root, options = {}) {
   }
   const transaction = createFileTransaction([
     configPath(root),
+    projectConfigPath(root),
     statePath(root),
     ...managedPlan.plans.map((plan) => plan.target),
     ...obsoletePlan.map((plan) => path.join(root, plan.target)),

package/src/core/config.js

@@ -8,6 +8,8 @@ const { LANGUAGE_CODES } = require("../i18n");
 
 const LOCAL_DIRECTORY = ".code-workspace";
 const CONFIG_FILE = "config.yaml";
+const PROJECT_CONFIG_FILE = "config-projects.yaml";
+const PROJECT_CONFIG_VERSION = 1;
 const STATE_FILE = "state.json";
 const DEFAULT_WORKSPACE_NAME = "code-workspace";
 const DEFAULT_MONITOR_URL = "http://127.0.0.1:3211";
@@ -29,6 +31,10 @@ function configPath(root) {
   return path.join(root, LOCAL_DIRECTORY, CONFIG_FILE);
 }
 
+function projectConfigPath(root) {
+  return path.join(root, LOCAL_DIRECTORY, PROJECT_CONFIG_FILE);
+}
+
 function statePath(root) {
   return path.join(root, LOCAL_DIRECTORY, STATE_FILE);
 }
@@ -122,6 +128,101 @@ function normalizeProjects(value) {
   });
 }
 
+function normalizeProjectReference(value, options = {}) {
+  const file = options.file || null;
+  if (value == null || (typeof value === "object" && !Array.isArray(value) && !Object.prototype.hasOwnProperty.call(value, "ref"))) {
+    throw new WorkspaceError("PROJECT_CONFIG_REFERENCE_MISSING", "projects.ref must reference config-projects.yaml; no project configuration reference was provided", {
+      file,
+      remediation: "Set projects.ref to config-projects.yaml and move project records into .code-workspace/config-projects.yaml.",
+    });
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new WorkspaceError("PROJECT_CONFIG_INLINE_UNSUPPORTED", "projects must reference config-projects.yaml; inline project arrays are not supported", {
+      file,
+      remediation: "Set projects.ref to config-projects.yaml and move project records into .code-workspace/config-projects.yaml.",
+    });
+  }
+  const ref = String(value.ref || "").trim();
+  if (ref !== PROJECT_CONFIG_FILE) {
+    throw new WorkspaceError("PROJECT_CONFIG_REFERENCE_INVALID", `projects.ref must be ${PROJECT_CONFIG_FILE}`, {
+      file,
+      ref: ref || null,
+      expected: PROJECT_CONFIG_FILE,
+      remediation: `Set projects.ref to ${PROJECT_CONFIG_FILE}.`,
+    });
+  }
+  return { ref: PROJECT_CONFIG_FILE };
+}
+
+function readProjectConfigDocument(root) {
+  const file = projectConfigPath(root);
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new WorkspaceError("PROJECT_CONFIG_FILE_MISSING", `Missing project configuration: ${file}`, {
+        file,
+        remediation: "Create .code-workspace/config-projects.yaml with schemaVersion: 1 and projects: [].",
+      });
+    }
+    throw new WorkspaceError("PROJECT_CONFIG_FILE_INVALID", `Cannot inspect project configuration ${file}: ${error.message}`, {
+      file,
+      cause: error.code || error.name,
+    });
+  }
+  if (stat.isSymbolicLink()) {
+    throw new WorkspaceError("PROJECT_CONFIG_FILE_INVALID", `Project configuration must be a regular file, not a symbolic link: ${file}`, {
+      file,
+      kind: "symbolic-link",
+      remediation: "Replace the symbolic link with a regular .code-workspace/config-projects.yaml file.",
+    });
+  }
+  if (!stat.isFile()) {
+    throw new WorkspaceError("PROJECT_CONFIG_FILE_INVALID", `Project configuration must be a regular file: ${file}`, {
+      file,
+      kind: stat.isDirectory() ? "directory" : "special-file",
+      remediation: "Create .code-workspace/config-projects.yaml as a regular file.",
+    });
+  }
+  let value;
+  try {
+    value = yaml.load(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    if (error instanceof WorkspaceError) throw error;
+    if (error.name === "YAMLException") {
+      throw new WorkspaceError("PROJECT_CONFIG_FILE_PARSE_FAILED", `Cannot parse project configuration ${file}: ${error.message}`, {
+        file,
+      });
+    }
+    throw new WorkspaceError("PROJECT_CONFIG_FILE_INVALID", `Cannot read project configuration ${file}: ${error.message}`, {
+      file,
+      cause: error.code || error.name,
+    });
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new WorkspaceError("PROJECT_CONFIG_FILE_INVALID", `Project configuration must be a YAML object: ${file}`, { file });
+  }
+  if (value.schemaVersion !== PROJECT_CONFIG_VERSION) {
+    throw new WorkspaceError("PROJECT_CONFIG_SCHEMA_UNSUPPORTED", `Project configuration schemaVersion must be ${PROJECT_CONFIG_VERSION}: ${file}`, {
+      file,
+      version: value.schemaVersion ?? null,
+      supported: PROJECT_CONFIG_VERSION,
+    });
+  }
+  if (!Array.isArray(value.projects)) {
+    throw new WorkspaceError("PROJECT_CONFIG_FILE_INVALID", `Project configuration projects must be an array: ${file}`, { file });
+  }
+  return {
+    file,
+    schemaVersion: PROJECT_CONFIG_VERSION,
+    value: {
+      ...value,
+      projects: normalizeProjects(value.projects),
+    },
+  };
+}
+
 function configVersion(value) {
   const version = value?.schemaVersion ?? 0;
   if (!Number.isInteger(version) || version < MINIMUM_READABLE_CONFIG_VERSION) {
@@ -182,23 +283,31 @@ function normalizeConfig(value, options = {}) {
   const source = value && typeof value === "object" && !Array.isArray(value) ? value : {};
   const migration = planConfigMigration(source);
   const config = migration.value;
+  const projects = options.projects !== undefined ? normalizeProjects(options.projects) : normalizeProjects(config.projects);
   return {
     ...config,
     schemaVersion: configVersion(config),
     workspace: normalizeWorkspace(config.workspace, options),
     monitor: normalizeMonitor(config.monitor),
-    projects: normalizeProjects(config.projects),
+    projects,
   };
 }
 
 function loadConfig(root, options = {}) {
-  return normalizeConfig(readConfigDocument(root).value, options);
+  const document = readConfigDocument(root);
+  normalizeProjectReference(document.value.projects, { file: document.file });
+  const projects = readProjectConfigDocument(root);
+  return normalizeConfig(document.value, {
+    ...options,
+    projects: projects.value.projects,
+    projectConfigFile: projects.file,
+  });
 }
 
 function loadConfigProjection(root, domains, options = {}) {
   const document = readConfigDocument(root);
   const requested = new Set(domains || []);
-  if (requested.has("complete")) return normalizeConfig(document.value, options);
+  if (requested.has("complete")) return loadConfig(root, options);
   const projected = { schemaVersion: CURRENT_CONFIG_VERSION, sourceSchemaVersion: document.schemaVersion };
   const attachFile = (error) => {
     error.details = { ...(error.details || {}), file: document.file };
@@ -230,9 +339,12 @@ function loadConfigProjection(root, domains, options = {}) {
   }
   if (requested.has("projects")) {
     try {
-      projected.projects = normalizeProjects(document.value.projects);
+      normalizeProjectReference(document.value.projects, { file: document.file });
+      const projects = readProjectConfigDocument(root);
+      projected.projects = projects.value.projects;
     } catch (error) {
-      attachFile(error);
+      error.details = { ...(error.details || {}), configFile: document.file };
+      throw error;
     }
   }
   return projected;
@@ -262,7 +374,7 @@ function inspectConfigDomains(root, options = {}) {
     try {
       return { valid: true, value: project(), diagnostics: [] };
     } catch (error) {
-      error.details = { ...(error.details || {}), file: document.file };
+      error.details = { ...(error.details || {}), configFile: document.file };
       return { valid: false, value: null, diagnostics: [error] };
     }
   };
@@ -273,7 +385,11 @@ function inspectConfigDomains(root, options = {}) {
     identity: inspect(() => normalizeWorkspaceIdentity(document.value.workspace)),
     language: inspect(() => normalizeWorkspaceLanguage(document.value.workspace?.language, options)),
     monitor: inspect(() => normalizeMonitor(document.value.monitor)),
-    projects: inspect(() => normalizeProjects(document.value.projects)),
+    projects: inspect(() => {
+      normalizeProjectReference(document.value.projects, { file: document.file });
+      const projectDocument = readProjectConfigDocument(root);
+      return projectDocument.value.projects;
+    }),
   };
 }
 
@@ -282,19 +398,33 @@ function renderConfigDocument(value) {
 }
 
 function renderConfig(config) {
-  return renderConfigDocument(normalizeConfig(config));
+  const normalized = normalizeConfig(config);
+  const { projectReference: _projectReference, ...withoutProjectReference } = normalized;
+  return renderConfigDocument({
+    ...withoutProjectReference,
+    projects: { ref: PROJECT_CONFIG_FILE },
+  });
+}
+
+function renderProjectConfig(projects) {
+  return renderConfigDocument({ schemaVersion: PROJECT_CONFIG_VERSION, projects: normalizeProjects(projects) });
 }
 
 function saveConfig(root, config) {
-  atomicWrite(configPath(root), renderConfig(config));
+  const normalized = normalizeConfig(config);
+  saveProjectConfig(root, normalized.projects);
+  atomicWrite(configPath(root), renderConfig(normalized));
+}
+
+function saveProjectConfig(root, projects) {
+  atomicWrite(projectConfigPath(root), renderProjectConfig(projects));
 }
 
 function updateProjectBranch(root, update, options = {}) {
   const document = (options.readConfigDocument || readConfigDocument)(root);
-  const sourceProjects = document.value.projects;
-  if (!Array.isArray(sourceProjects)) {
-    throw new WorkspaceError("PROJECT_REGISTRY_INVALID", "projects must be an array", { file: document.file });
-  }
+  normalizeProjectReference(document.value.projects, { file: document.file });
+  const projectDocument = (options.readProjectConfigDocument || readProjectConfigDocument)(root);
+  const sourceProjects = projectDocument.value.projects;
   const sourceProject = sourceProjects.find((project) => project?.name === update.name);
   if (!sourceProject || sourceProject.branch !== update.before.registeredBranch) {
     throw new WorkspaceError(
@@ -312,10 +442,10 @@ function updateProjectBranch(root, update, options = {}) {
   }
   const project = { ...sourceProject, branch: update.after.registeredBranch };
   const nextDocument = {
-    ...document.value,
+    ...projectDocument.value,
     projects: sourceProjects.map((entry) => entry?.name === update.name ? project : entry),
   };
-  (options.atomicWrite || atomicWrite)(configPath(root), renderConfigDocument(nextDocument));
+  (options.atomicWrite || atomicWrite)(projectConfigPath(root), renderProjectConfig(nextDocument.projects));
   return project;
 }
 
@@ -345,6 +475,8 @@ function ensureLocalIgnore(root) {
 
 module.exports = {
   CONFIG_FILE,
+  PROJECT_CONFIG_FILE,
+  PROJECT_CONFIG_VERSION,
   CURRENT_CONFIG_VERSION,
   DEFAULT_MONITOR_URL,
   DEFAULT_WORKSPACE_NAME,
@@ -363,6 +495,7 @@ module.exports = {
   normalizeConfig,
   normalizeMonitor,
   normalizeProjects,
+  normalizeProjectReference,
   normalizeWorkspace,
   normalizeWorkspaceIdentity,
   normalizeWorkspaceLanguage,
@@ -370,8 +503,12 @@ module.exports = {
   readConfigDocument,
   renderConfig,
   renderConfigDocument,
+  renderProjectConfig,
   requireWorkspaceRoot,
   saveConfig,
+  saveProjectConfig,
+  readProjectConfigDocument,
+  projectConfigPath,
   saveState,
   statePath,
   updateProjectBranch,

package/src/core/extensions.js

@@ -152,7 +152,6 @@ function coreWholeFileTargets() {
     `${LOCAL_DIRECTORY}/${CONFIG_FILE}`,
     `${LOCAL_DIRECTORY}/${STATE_FILE}`,
     `${LOCAL_DIRECTORY}/${EXTENSION_STATE_FILE}`,
-    ".gitignore",
     ...manifest.managedFiles.map((entry) => entry.target),
     ...OBSOLETE_ASSETS,
   ]);
@@ -162,6 +161,7 @@ function coreManagedTargets() {
   const root = path.parse(PACKAGE_ROOT).root;
   return new Set([
     ...coreWholeFileTargets(),
+    ".gitignore",
     ...permissionTargets(root, ["claude", "codex"]).map((target) => path.relative(root, target).split(path.sep).join("/")),
   ]);
 }

package/src/core/initializer.js

@@ -8,6 +8,7 @@ const {
   DEFAULT_MONITOR_URL,
   DEFAULT_WORKSPACE_NAME,
   configPath,
+  projectConfigPath,
   ensureLocalIgnore,
   loadConfig,
   normalizeConfig,
@@ -213,6 +214,7 @@ async function initializeWorkspace(rootInput, options = {}) {
   const files = [
     statePath(root),
     configPath(root),
+    projectConfigPath(root),
     path.join(root, ".gitignore"),
     path.join(root, ".codex", "config.toml"),
     ...permissionTargets(root, options.tools),

package/src/core/project-configuration.js

@@ -1,4 +1,4 @@
-const { configPath, loadConfigProjection, loadState, saveConfig } = require("./config");
+const { configPath, loadConfigProjection, loadState, projectConfigPath, saveProjectConfig } = require("./config");
 const { WorkspaceError } = require("./errors");
 const { loadInitManifest } = require("./init");
 const { applyPermissionPlan, planPermissionChanges } = require("./permissions");
@@ -30,9 +30,9 @@ function applyProjectConfiguration(root, nextConfig, permissionPlan, options = {
     options = permissionPlan || options;
     permissionPlan = fallbackPermissionPlan(root, nextConfig, options);
   }
-  const transaction = createFileTransaction([configPath(root), ...permissionPlan.targets]);
+  const transaction = createFileTransaction([configPath(root), projectConfigPath(root), ...permissionPlan.targets]);
   try {
-    (options.saveConfig || saveConfig)(root, nextConfig);
+    (options.saveProjectConfig || saveProjectConfig)(root, nextConfig.projects);
     options.injectFailure?.("after-config-save");
     const persisted = (options.loadConfigProjection || loadConfigProjection)(root, ["projects"]);
     if (JSON.stringify(persisted.projects) !== JSON.stringify(nextConfig.projects)) {

package/docs/extensions.md

@@ -1,64 +0,0 @@
-# Built-in Extension Contract
-
-Code Workspace extensions are trusted, versioned packages shipped under `extensions/<id>/<semver>/`. The extension process is fault-isolated, but it is not a security sandbox: bundled extension code runs with the current user's operating-system permissions.
-
-Each version contains `manifest.json`, `init.js`, and any private templates, metadata, or helper code it needs. The current Host explicitly supports Extension Spec v1, defined in English at `spec/extension/v1/specification.en-US.md` and in Chinese at `spec/extension/v1/specification.zh-CN.md`, with these component schemas:
-
-- `schemas/extension-manifest-v3.json`
-- `schemas/extension-init-context-v1.json`
-- `schemas/extension-init-result-v1.json`
-
-The static manifest declares its `extensionSpecVersion`, identity, entry hash and timeout, declarative network hosts, and maximum output scope. The Host executes only explicitly supported specification versions; the Code Workspace product version is not an extension compatibility key. Code Workspace freezes the specification version, manifest, entry, and complete extension-version directory digest before confirmation, then verifies them again before execution.
-
-The Host starts the entry with independent temporary paths:
-
-```text
-node init.js --context <context-file> --output <staging-directory> --result <result-file>
-```
-
-The context contains the specification version, extension identity, Workspace display metadata, and selected tools. It does not expose the real Workspace path. The result echoes the same specification version and contains only the extension identity and `{ id, source }` entries. It must return exactly every manifest output applicable to the selected tools; it cannot redefine target, kind, ownership, selector, or digest.
-
-The Host recursively validates staging, rejects undeclared content, path escapes, symbolic links, and special files, and independently computes installed file and directory digests. Extensions never write the real Workspace or installed state directly and never provide uninstall code.
-
-## Generic output kinds
-
-- `file`: one extension-owned Workspace-relative regular file.
-- `directory`: one extension-owned Workspace-relative directory tree containing only regular files and directories.
-- `text-block`: a Host-marked fragment in a shared text file. `format: "toml"` validates both the fragment and the complete composed document.
-- `json-member`: one JSON value owned at a declared JSON Pointer in a shared object document.
-
-Exclusive targets cannot overlap core-managed paths or another extension's targets. Shared text blocks can coexist in the same text target. JSON member ownership rejects equal or parent/child selectors. The Host preserves user, core, and other extension content during install, upgrade, rollback, and uninstall.
-
-Download protocols, archive formats, package managers, Jira, MCP, and individual Agent products are not public output kinds. An extension may use those details privately to prepare a candidate file or directory in staging. Declarative `networkHosts` are shown in the plan for review; they are not operating-system-level egress enforcement.
-
-The installed manifest is the only installation fact. New records contain the installed-record version, Extension Spec version, extension version, frozen package and manifest digests, generic output ownership, Host-computed digests, and shared contribution data. Idempotency verifies both this state and the real Workspace. Upgrade handles retained, added, replaced, and removed outputs in one per-extension recoverable transaction. Uninstall reads only installed state, so it still works when the bundled package or execution specification is absent. Unknown local changes stop upgrade or uninstall; there is no force mode.
-
-Previously published installed protocol-v1/v2 records for files, Codex configuration blocks, and Codex Hooks remain readable and uninstallable. They are compatibility state, not new Extension Spec v1 output kinds.
-
-`init`, `extension install`, and `extension uninstall` share one non-blocking per-Workspace operation lock. A multi-extension install uses one confirmation boundary and an independent transaction per extension; a failure does not stop later extensions, but the overall command reports failure.
-
-## Zhuiyi Jira MCP
-
-Install it with:
-
-```bash
-code-w extension install zhuiyi-jira-mcp --yes
-```
-
-The Jira extension privately downloads the pinned Gitee release, verifies its fixed SHA-256, safely extracts it, and validates the npm package name, version, and `dist/index.js` entry inside staging. The archive already contains `dist` and runtime dependencies; initialization never runs `npm install`, `npm ci`, a build, or an archive script.
-
-After validation, the Host installs only generic outputs:
-
-```text
-.code-workspace/extensions/zhuiyi-jira-mcp/0.1.0/   # directory
-.codex/config.toml                                  # text-block when Codex is selected
-.mcp.json#/mcpServers/zhuiyi-jira                   # json-member when Claude is selected
-```
-
-The generated configuration contains non-secret defaults only. It never persists a Jira cookie, token, email, or password; provide credentials in the environment that launches the Agent, for example:
-
-```bash
-export JIRA_COOKIE='JSESSIONID=...; atlassian.xsrf.token=...'
-```
-
-Downloaded attachments default to `.jira-attachments/` in the Workspace. They are runtime user data, not installation artifacts, and are retained when the extension is upgraded or uninstalled.

package/docs/extensions.zh-CN.md

@@ -1,64 +0,0 @@
-# 内置扩展契约
-
-Code Workspace 扩展是随发布包提供、位于 `extensions/<id>/<semver>/` 下的可信版本化软件包。扩展进程具有故障隔离，但不是安全沙箱：内置扩展代码仍以当前用户的操作系统权限运行。
-
-每个版本包含 `manifest.json`、`init.js`，以及扩展需要的私有模板、元数据或辅助代码。当前 Host 明确支持 Extension Spec v1；中文规范位于 `spec/extension/v1/specification.zh-CN.md`，英文规范位于 `spec/extension/v1/specification.en-US.md`，其组件 schema 为：
-
-- `schemas/extension-manifest-v3.json`
-- `schemas/extension-init-context-v1.json`
-- `schemas/extension-init-result-v1.json`
-
-静态 manifest 通过 `extensionSpecVersion` 声明扩展实现的开发规范，并声明扩展身份、入口摘要和超时、声明性网络 host，以及最大输出范围。Host 只执行其明确支持的规范版本；Code Workspace 产品版本不参与扩展兼容判断。Code Workspace 在确认前冻结规范版本、manifest、入口和完整扩展版本目录摘要，并在执行前重新验证。
-
-Host 使用相互独立的临时路径启动入口：
-
-```text
-node init.js --context <context-file> --output <staging-directory> --result <result-file>
-```
-
-context 只包含规范版本、扩展身份、Workspace 显示元数据和所选工具，不提供真实 Workspace 路径。result 回显同一规范版本，并只包含扩展身份和 `{ id, source }`。它必须完整返回本次工具选择所适用的全部 manifest 输出，不能重新声明 target、kind、ownership、selector 或摘要。
-
-Host 递归验证 staging，拒绝未声明内容、路径逃逸、符号链接和特殊文件，并独立计算已安装文件或目录摘要。扩展不直接写入真实 Workspace 或 installed 状态，也不提供卸载脚本。
-
-## 通用输出类型
-
-- `file`：扩展独占的一个 Workspace 相对普通文件。
-- `directory`：扩展独占的一个 Workspace 相对目录树，其中只能包含普通文件和目录。
-- `text-block`：Host 使用稳定标记管理的共享文本片段；`format: "toml"` 会同时验证片段和合成后的完整文档。
-- `json-member`：扩展在共享 JSON 对象文档的声明 JSON Pointer 位置拥有一个值。
-
-独占目标不能与核心管理路径或其他扩展目标重叠。多个共享文本块可以共存于同一文本文件；JSON 成员所有权会拒绝相同 selector 及父子 selector。安装、升级、回滚和卸载均保留用户、核心及其他扩展的内容。
-
-下载协议、归档格式、包管理器、Jira、MCP 和具体 Agent 产品都不是公共输出类型。扩展可以在私有实现中使用这些知识，在 staging 中准备候选文件或目录。声明的 `networkHosts` 会展示在计划中供用户确认，但不代表操作系统级网络出口强制隔离。
-
-installed manifest 是唯一安装事实。新记录包含 installed record 版本、Extension Spec 版本、扩展版本、冻结的扩展包和 manifest 摘要、通用输出所有权、Host 计算的摘要及共享 contribution 数据。幂等判断同时验证状态和真实 Workspace。升级在单扩展可恢复事务中处理保留、新增、替换和移除的输出。卸载只读取 installed 状态，因此扩展包或执行规范已经不存在时仍可工作。发现未知本地修改时，升级或卸载会停止；基础版不提供强制模式。
-
-已经发布的 installed protocol v1/v2 文件、Codex 配置块和 Codex Hooks 记录仍可读取和卸载；它们只属于兼容状态，不再是 Extension Spec v1 的新输出类型。
-
-`init`、`extension install` 和 `extension uninstall` 共用同一个非阻塞 Workspace 操作锁。多扩展安装只确认一次，每个扩展使用独立事务；单个失败不会阻止后续扩展，但整体命令会报告失败。
-
-## Zhuiyi Jira MCP
-
-安装：
-
-```bash
-code-w extension install zhuiyi-jira-mcp --yes
-```
-
-Jira 扩展在私有实现中下载固定的 Gitee 发布包，校验固定 SHA-256，安全解压，并在 staging 中验证 npm 包名称、版本和 `dist/index.js` 入口。归档已经包含 `dist` 和运行依赖；初始化不会执行 `npm install`、`npm ci`、构建或归档内脚本。
-
-验证完成后，Host 只安装通用输出：
-
-```text
-.code-workspace/extensions/zhuiyi-jira-mcp/0.1.0/   # directory
-.codex/config.toml                                  # 选择 Codex 时的 text-block
-.mcp.json#/mcpServers/zhuiyi-jira                   # 选择 Claude 时的 json-member
-```
-
-生成配置只包含非敏感默认值，不会持久化 Jira Cookie、Token、邮箱或密码。用户需要在启动 Agent 的环境中提供凭证，例如：
-
-```bash
-export JIRA_COOKIE='JSESSIONID=...; atlassian.xsrf.token=...'
-```
-
-下载附件默认保存在 Workspace 的 `.jira-attachments/`。它是运行期用户数据，不是安装制品，扩展升级或卸载时都会保留。

package/extensions/openspec-workspace/1.0.0/artifacts/claude/SKILL.md

@@ -1,16 +0,0 @@
----
-name: code-workspace-openspec-propose
-description: Create an OpenSpec change for a selected Code Workspace project after resolving and verifying that project's registered scope.
----
-
-# Code Workspace OpenSpec Propose
-
-Use this skill only when the user explicitly asks to create an OpenSpec proposal for a project registered in Code Workspace.
-
-1. Resolve exactly one target project with `code-w project show "<project-name>" --json` and retain its `location`, `branch`, `type`, and `context` as the working boundary.
-2. Verify that target with `code-w project verify "<project-name>" --json`. If branch reconciliation is required, stop and use the Code Workspace branch-resolution workflow before creating a change.
-3. Change the working directory to the verified project location. Do not create the OpenSpec change in the Workspace registry directory.
-4. Follow the installed OpenSpec propose workflow in that project. Derive a kebab-case change name, create the change, and generate every artifact required for apply.
-5. Report the project name, change name, artifact paths, validation status, and whether the change is ready to implement.
-
-Do not modify `.code-workspace/`, do not broaden the request to other registered projects, and do not implement or archive the change unless the user asks.

package/extensions/openspec-workspace/1.0.0/artifacts/codex/SKILL.md

@@ -1,16 +0,0 @@
----
-name: code-workspace-openspec-propose
-description: Create an OpenSpec change for a selected Code Workspace project after resolving and verifying that project's registered scope.
----
-
-# Code Workspace OpenSpec Propose
-
-Use this skill only when the user explicitly asks to create an OpenSpec proposal for a project registered in Code Workspace.
-
-1. Resolve exactly one target project with `code-w project show "<project-name>" --json` and retain its `location`, `branch`, `type`, and `context` as the working boundary.
-2. Verify that target with `code-w project verify "<project-name>" --json`. If branch reconciliation is required, stop and use the Code Workspace branch-resolution workflow before creating a change.
-3. Change the working directory to the verified project location. Do not create the OpenSpec change in the Workspace registry directory.
-4. Follow the installed OpenSpec propose workflow in that project. Derive a kebab-case change name, create the change, and generate every artifact required for apply.
-5. Report the project name, change name, artifact paths, validation status, and whether the change is ready to implement.
-
-Do not modify `.code-workspace/`, do not broaden the request to other registered projects, and do not implement or archive the change unless the user asks.

package/extensions/openspec-workspace/1.0.0/init.js

@@ -1,54 +0,0 @@
-#!/usr/bin/env node
-
-const fs = require("node:fs");
-const path = require("node:path");
-
-function fail(message) {
-  process.stderr.write(`${message}\n`);
-  process.exitCode = 1;
-}
-
-function option(name) {
-  const index = process.argv.indexOf(name);
-  return index >= 0 ? process.argv[index + 1] : null;
-}
-
-try {
-  const contextFile = option("--context");
-  const outputRoot = option("--output");
-  const resultFile = option("--result");
-  if (!contextFile || !outputRoot || !resultFile) throw new Error("Usage: init.js --context <file> --output <directory> --result <file>");
-  const context = JSON.parse(fs.readFileSync(contextFile, "utf8"));
-  if (context.schemaVersion !== 1 || context.extensionSpecVersion !== 1 || context.extension?.id !== "openspec-workspace" || !Array.isArray(context.tools)) {
-    throw new Error("Invalid extension context");
-  }
-  const definitions = {
-    codex: {
-      id: "codex-propose-skill",
-      source: path.join(__dirname, "artifacts", "codex", "SKILL.md"),
-      target: ".codex/skills/code-workspace-openspec-propose/SKILL.md",
-    },
-    claude: {
-      id: "claude-propose-skill",
-      source: path.join(__dirname, "artifacts", "claude", "SKILL.md"),
-      target: ".claude/skills/code-workspace-openspec-propose/SKILL.md",
-    },
-  };
-  const outputs = [];
-  for (const tool of context.tools) {
-    const definition = definitions[tool];
-    if (!definition) continue;
-    const target = path.join(outputRoot, ...definition.target.split("/"));
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    fs.copyFileSync(definition.source, target);
-    outputs.push({ id: definition.id, source: definition.target });
-  }
-  fs.writeFileSync(resultFile, `${JSON.stringify({
-    schemaVersion: 1,
-    extensionSpecVersion: 1,
-    extension: { id: "openspec-workspace", version: "1.0.0" },
-    outputs,
-  }, null, 2)}\n`, { mode: 0o600 });
-} catch (error) {
-  fail(error.message);
-}

package/extensions/openspec-workspace/1.0.0/manifest.json

@@ -1,27 +0,0 @@
-{
-  "schemaVersion": 3,
-  "extensionSpecVersion": 1,
-  "experimental": true,
-  "id": "openspec-workspace",
-  "name": "OpenSpec Workspace",
-  "version": "1.0.0",
-  "entry": "init.js",
-  "entrySha256": "5d95dc6261ef686f81a61cc09f0cf1d87bbb5014512be8665df2cc9f9b9dae24",
-  "timeoutMs": 60000,
-  "outputs": [
-    {
-      "id": "codex-propose-skill",
-      "kind": "file",
-      "ownership": "exclusive",
-      "target": ".codex/skills/code-workspace-openspec-propose/SKILL.md",
-      "tools": ["codex"]
-    },
-    {
-      "id": "claude-propose-skill",
-      "kind": "file",
-      "ownership": "exclusive",
-      "target": ".claude/skills/code-workspace-openspec-propose/SKILL.md",
-      "tools": ["claude"]
-    }
-  ]
-}