code-workspace-zhuiyi 0.1.0-beta.1

package/.env.example

@@ -0,0 +1,3 @@
+# Code Workspace init operation lock
+CODE_WORKSPACE_INIT_LOCK_UPDATE_MS=5000
+CODE_WORKSPACE_INIT_LOCK_STALE_MS=30000

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 icebearx-ai
+
+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,168 @@
+# Code Workspace
+
+Code Workspace is a local multi-project registry and safety layer for Claude Code and Codex. It manages workspace identity, project locations and branches, agent instructions, writable-root permissions, validation, and optional monitoring.
+
+## Requirements
+
+- Node.js 20.19.0 or newer
+- Git repositories for projects you register
+
+## Install
+
+```bash
+npm install -g @icebearx-ai/code-workspace
+```
+
+The package provides `code-workspace` and the shorter alias `code-w`.
+
+## Initialize
+
+Interactive initialization:
+
+```bash
+code-workspace init .
+```
+
+Non-interactive initialization:
+
+```bash
+code-workspace init . \
+  --tools claude,codex \
+  --extensions none \
+  --language en-US \
+  --yes
+```
+
+Use `--tools claude`, `--tools codex`, or `--tools none` to override the default tool selection. Codex monitoring is enabled by default when Codex is selected; use `--no-monitor` to disable it.
+
+Initialization writes only Workspace-owned state and integrations:
+
+- `.code-workspace/config.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
+- `.codex/hooks.json` when monitoring is enabled
+
+It does not create `openspec/`, install native `/opsx` commands, or install native `openspec-*` skills.
+
+### Experimental built-in extensions
+
+`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 none --yes
+code-w extension install
+code-w extension install openspec-workspace --yes
+code-w extension uninstall openspec-workspace --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.
+
+`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.
+
+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.
+
+Extensions may own complete files or contribute Host-managed Codex TOML blocks and Hook fragments. Shared targets are composed and verified by Code Workspace; extensions never patch the real Workspace directly. Uninstall uses recorded installed state and does not execute extension code. Unknown changes to extension-owned files or contributions stop the operation instead of being overwritten.
+
+This is fault isolation, not a malicious-code security sandbox. The experimental release trusts only extension code shipped with Code Workspace; network sources, external extension directories, dependencies, arbitrary patches, force uninstall, disable commands, and automatic extension updates through `code-w update` are not supported. The developer contract is in `docs/extensions.md`.
+
+## Register projects
+
+Inspecting a repository is read-only:
+
+```bash
+code-workspace project inspect /absolute/path/to/project --json
+```
+
+Claude Code users can invoke:
+
+```text
+/code-workspace:add-projects /absolute/path/to/project-a /absolute/path/to/project-b
+```
+
+Codex users can invoke `$code-workspace-add-projects` with the same explicit paths. For low-level automation, prepare a complete project record and run:
+
+```bash
+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.
+
+## Daily commands
+
+```bash
+code-workspace project list --json
+code-workspace project show payments --json
+code-workspace project verify payments --json
+code-workspace project branch inspect payments --json
+code-workspace project branch verify payments --json
+code-workspace project branch use-registered payments --yes --json
+code-workspace project branch accept-actual payments --yes --json
+code-workspace project branch update-latest payments --json
+code-workspace permissions apply --yes --json
+code-workspace doctor --json
+```
+
+`project branch inspect` reports `registeredBranch`, `actualBranch`, whether they match, worktree cleanliness, local registered-branch availability, and remote-tracking candidates for only the named project. `project branch verify` is the narrower assertion used after reconciliation: it checks only whether the registered and actual branches match, without running overall project-health validation. A `PROJECT_BRANCH_MISMATCH` diagnostic uses `registeredBranch`, `actualBranch`, and `location`; consumers of older branch diagnostic/result fields must migrate to this canonical state contract.
+
+The two reconciliation directions are deliberately separate:
+
+- `project branch use-registered` switches the selected worktree to its registered branch. By default it requires confirmation, a clean worktree, and an existing local branch. `--allow-remote` permits creating a local tracking branch from one existing remote-tracking branch; `--remote <name>` explicitly authorizes fetching the registered branch from that remote before creating and switching the local tracking branch.
+- `project branch accept-actual` updates only the selected registry record so its registered branch accepts the actual branch. Existing branch-adoption scripts should migrate to this command.
+
+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`:
+
+```yaml
+projects:
+  - name: payments
+    updateLatest: true
+```
+
+AI/Agent must not directly edit this file. They may read the policy and invoke the registered CLI command; users remain responsible for manual configuration changes.
+
+`permissions apply` shows the complete authorization plan for the selected Agent tools, requires confirmation when changes are needed, applies and verifies the requested grants, and reports the result per tool. Agent directory access remains a user authorization. The command adds missing registered-project access but does not revoke additional directories; use `project remove` or edit the Agent settings explicitly to revoke access.
+
+## Update and language
+
+```bash
+code-workspace update --json
+code-workspace update --language zh-CN --json
+code-workspace language --json
+```
+
+`update` refreshes only Workspace-owned managed assets and never changes Agent directory authorization. Unknown local edits stop the batch before writes; review them or pass `--force` explicitly.
+
+## Monitor
+
+```bash
+code-workspace monitor --port 3211
+```
+
+The monitor binds to loopback, combines events from multiple initialized workspaces, and keeps hook reporting failure-open. Review and trust project hooks in Codex before relying on reports.
+
+## Completion
+
+```bash
+code-workspace completion --shell zsh
+code-workspace completion --shell bash
+```
+
+`completion` prints a script generated from the full command registry, including subcommands and command-specific options. It does not install the script or modify shell configuration. With `--json`, the script is returned in `data.script`.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run check
+npm run pack:check
+```
+
+The release manifest contains only Workspace-owned asset sources and managed files. Checksums make installation and update deterministic.

package/README.zh-CN.md

@@ -0,0 +1,168 @@
+# Code Workspace
+
+Code Workspace 是面向 Claude Code 与 Codex 的本地多项目注册表和安全边界层，负责工作区身份、项目路径与分支、Agent 指令、可写目录权限、校验以及可选监控。
+
+## 环境要求
+
+- Node.js 20.19.0 或更高版本
+- 待注册项目是 Git 仓库
+
+## 安装
+
+```bash
+npm install -g @icebearx-ai/code-workspace
+```
+
+软件包提供 `code-workspace` 命令及短别名 `code-w`。
+
+## 初始化
+
+交互式初始化：
+
+```bash
+code-workspace init .
+```
+
+非交互式初始化：
+
+```bash
+code-workspace init . \
+  --tools claude,codex \
+  --extensions none \
+  --language zh-CN \
+  --yes
+```
+
+可用 `--tools claude`、`--tools codex` 或 `--tools none` 覆盖默认工具选择。选择 Codex 时默认启用监控；可传 `--no-monitor` 关闭。
+
+初始化只写入 Workspace 自有状态和集成：
+
+- `.code-workspace/config.yaml` 与 `.code-workspace/state.json`
+- `USER_GUIDE.md`
+- `CLAUDE.md` 和/或 `AGENTS.md`
+- 名称以 `code-workspace-` 开头或使用 `/code-workspace` 命名空间的 Workspace 专用命令与 Skill
+- 启用监控时的 `.codex/hooks.json`
+
+它不会创建 `openspec/`，不会安装原生 `/opsx` 命令，也不会安装原生 `openspec-*` Skill。
+
+### 试验性内置扩展
+
+`init` 可以从 npm 包内随附的版本化 `extensions/` 仓库安装集成。交互模式按扩展名多选；非交互模式传入逗号分隔的扩展名。独立安装命令接受一个或多个扩展名；不传名称时打开内置扩展多选，按 ESC 可无修改退出：
+
+```bash
+code-w init . --extensions openspec-workspace --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
+```
+
+`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` 只跳过本次扩展初始化，不会卸载已有制品。
+
+`extension install` 不会重新执行 Workspace 核心初始化。在 JSON、非 TTY 或 `--yes` 模式下，必须至少提供一个扩展名。多个名称按顺序安装，只确认一次且各自使用独立事务；任一扩展失败会使安装命令失败，但后续扩展仍会继续执行。
+
+内置 `openspec-workspace` 扩展会为选中的 Agent 工具安装命名空间为 `code-workspace-openspec-propose` 的 Skill；它不会创建 `openspec/` 目录，也不会安装 OpenSpec 原生命令。
+
+扩展入口在独立 Node 进程中运行，只向临时 staging 目录生成文件。Host 会在事务安装前拒绝未声明、缺失、符号链接、非文件、路径逃逸、目标冲突和 hash 不匹配的制品。Workspace 状态存放在 `.code-workspace/ext-manifest.json`。扩展失败以 warning 报告，不回滚已成功的核心初始化，也不阻止后续扩展；升级失败会恢复并保留旧的已安装版本。
+
+扩展可以独占完整文件，也可以贡献由 Host 管理的 Codex TOML 配置块和 Hook 片段。共享目标由 Code Workspace 合成和验证；扩展不会直接 patch 真实 Workspace。卸载只使用已安装状态，不执行扩展代码；扩展所有的文件或贡献存在未知修改时会拒绝覆盖或删除。
+
+这是故障隔离，不是恶意代码安全沙箱。试验版本只信任随 Code Workspace 发布的扩展代码；暂不支持网络源、外部扩展目录、扩展依赖、任意 patch、强制卸载、禁用命令，也不会通过 `code-w update` 自动更新扩展。开发契约见 `docs/extensions.zh-CN.md`。
+
+## 注册项目
+
+项目检查是只读操作：
+
+```bash
+code-workspace project inspect /absolute/path/to/project --json
+```
+
+Claude Code 用户可显式调用：
+
+```text
+/code-workspace:add-projects /absolute/path/to/project-a /absolute/path/to/project-b
+```
+
+Codex 用户可对相同的显式路径调用 `$code-workspace-add-projects`。底层自动化可准备完整项目记录，然后运行：
+
+```bash
+code-workspace project add --projects-file projects.json --yes --json
+```
+
+注册表保存项目名称、真实路径、注册分支、类型和上下文。注册分支是 Code Workspace 的期望状态，实际分支是从选中 Git worktree 观测到的状态。Workspace 不会根据对话猜测路径，也不会自动判断哪一侧分支更权威。
+
+## 日常命令
+
+```bash
+code-workspace project list --json
+code-workspace project show payments --json
+code-workspace project verify payments --json
+code-workspace project branch inspect payments --json
+code-workspace project branch verify payments --json
+code-workspace project branch use-registered payments --yes --json
+code-workspace project branch accept-actual payments --yes --json
+code-workspace project branch update-latest payments --json
+code-workspace permissions apply --yes --json
+code-workspace doctor --json
+```
+
+`project branch inspect` 只检查命名项目，返回 `registeredBranch`、`actualBranch`、是否一致、worktree 是否干净、注册分支是否在本地存在以及远程跟踪候选。`project branch verify` 是协调后的窄范围断言，只检查注册分支和实际分支是否一致，不执行项目整体健康校验。`PROJECT_BRANCH_MISMATCH` 诊断使用 `registeredBranch`、`actualBranch` 和 `location`；使用旧分支诊断或结果字段的调用方必须迁移到这套规范状态合同。
+
+两个协调方向通过独立命令表达：
+
+- `project branch use-registered` 将选中 worktree 切换到注册分支，默认要求确认、干净 worktree 和已存在的本地注册分支。提供 `--allow-remote` 时，可以从唯一已有的远程跟踪分支创建本地 tracking 分支；提供 `--remote <name>` 时，可以在确认后仅 fetch 指定远程的注册分支，再创建本地 tracking 分支并切换。
+- `project branch accept-actual` 只更新选中项目的注册记录，让注册分支接受实际分支；已有“接受实际分支”脚本应迁移到该命令。
+
+两条命令都会检查计划漂移并验证后置条件。`project branch update-latest` 是独立的显式配置路径：仅当项目 `updateLatest: true` 时，才对干净且分支一致的 worktree fetch upstream 并 fast-forward。Code Workspace 不会创建或下载分支，也不会执行 stash、reset、rebase、非 fast-forward merge、生产代码编辑或冲突处理。
+
+用户可以手动在 `.code-workspace/config.yaml` 中设置项目策略：
+
+```yaml
+projects:
+  - name: payments
+    updateLatest: true
+```
+
+AI/Agent 不得直接编辑该文件；可以读取策略并调用已注册的 CLI，手动配置结果由用户负责。
+
+`permissions apply` 会展示选中 Agent 工具的完整授权计划，在需要修改时要求确认，实施并验证请求的授权，并按工具报告结果。Agent 目录访问仍属于用户授权。该命令只补齐已注册项目缺失的访问权限，不撤销额外目录；如需撤销，请使用 `project remove` 或显式编辑 Agent 设置。
+
+## 更新与语言
+
+```bash
+code-workspace update --json
+code-workspace update --language en-US --json
+code-workspace language --json
+```
+
+`update` 只刷新 Workspace 自有托管资产，绝不会修改 Agent 目录授权。遇到未知本地修改时，会在任何写入前终止批次；请先审查修改，或显式传入 `--force`。
+
+## 监控
+
+```bash
+code-workspace monitor --port 3211
+```
+
+监控服务仅绑定 loopback，可汇总多个已初始化工作区的事件；hook 上报失败不会阻断 Agent。依赖监控前，请在 Codex 中检查并信任项目 hook。
+
+## 命令补全
+
+```bash
+code-workspace completion --shell zsh
+code-workspace completion --shell bash
+```
+
+`completion` 会根据完整命令注册表输出脚本，包括子命令和各命令专属选项；它不会安装脚本或修改 Shell 配置。使用 `--json` 时，脚本位于 `data.script`。
+
+## 开发
+
+```bash
+npm install
+npm test
+npm run check
+npm run pack:check
+```
+
+发布清单只包含 Workspace 自有资产源和托管文件，并通过校验和保证安装与更新的确定性。

package/artifacts/manifest.json

@@ -0,0 +1,183 @@
+{
+  "schemaVersion": 2,
+  "releaseVersion": "0.1.0-beta.1",
+  "requirements": {
+    "node": ">=20.19.0"
+  },
+  "tools": [
+    "claude",
+    "codex"
+  ],
+  "sources": [
+    {
+      "id": "workspace-user-guide-en-US",
+      "kind": "asset",
+      "path": "templates/user-guide/en-US.md",
+      "sha256": "d6e3f59fc86262c4e71d2320fb2fba21394d7b4f099ef465fdec765d0b6c7754"
+    },
+    {
+      "id": "workspace-user-guide-zh-CN",
+      "kind": "asset",
+      "path": "templates/user-guide/zh-CN.md",
+      "sha256": "4dc207305a3975ab7272addedf3bc2930054e860c2b0b2b6e0e102f4457f5cc0"
+    }
+  ],
+  "managedFiles": [
+    {
+      "id": "workspace-user-guide",
+      "target": "USER_GUIDE.md",
+      "allowMissing": true,
+      "desired": {
+        "source": "templates/USER_GUIDE.template.md",
+        "sha256": "79d635871bd3917ba2a99ad7aa6d68794a4f1c4b2b6da482f227b1437bd7114c"
+      },
+      "render": {
+        "variables": [
+          "WORKSPACE_USER_GUIDE"
+        ]
+      },
+      "provenance": {
+        "kind": "template"
+      }
+    },
+    {
+      "id": "workspace-claude-instructions",
+      "target": "CLAUDE.md",
+      "tools": [
+        "claude"
+      ],
+      "allowMissing": true,
+      "desired": {
+        "source": "templates/agents/WORKSPACE_GUARD.md.template",
+        "sha256": "6510cce83138fad46330d2c175506e56e9c98d5086195a699eafc7cc74163bf3"
+      },
+      "render": {
+        "variables": [
+          "ADD_PROJECTS_INVOCATION"
+        ],
+        "values": {
+          "ADD_PROJECTS_INVOCATION": "/code-workspace:add-projects /absolute/path/to/project"
+        }
+      },
+      "provenance": {
+        "kind": "template"
+      }
+    },
+    {
+      "id": "workspace-codex-instructions",
+      "target": "AGENTS.md",
+      "tools": [
+        "codex"
+      ],
+      "allowMissing": true,
+      "desired": {
+        "source": "templates/agents/WORKSPACE_GUARD.md.template",
+        "sha256": "6510cce83138fad46330d2c175506e56e9c98d5086195a699eafc7cc74163bf3"
+      },
+      "render": {
+        "variables": [
+          "ADD_PROJECTS_INVOCATION"
+        ],
+        "values": {
+          "ADD_PROJECTS_INVOCATION": "$code-workspace-add-projects /absolute/path/to/project"
+        }
+      },
+      "provenance": {
+        "kind": "template"
+      }
+    },
+    {
+      "id": "workspace-codex-monitor-hooks",
+      "target": ".codex/hooks.json",
+      "tools": [
+        "codex"
+      ],
+      "capabilities": [
+        "monitor"
+      ],
+      "allowMissing": true,
+      "desired": {
+        "source": "templates/codex/hooks.json",
+        "sha256": "64d68809a2681b11d4b50bee3ca711fa8f5ea0a297c2281e5c7f8937e968e22e"
+      },
+      "provenance": {
+        "kind": "template"
+      }
+    },
+    {
+      "id": "workspace-claude-add-projects-command",
+      "target": ".claude/commands/code-workspace/add-projects.md",
+      "tools": [
+        "claude"
+      ],
+      "allowMissing": true,
+      "desired": {
+        "source": "templates/claude/commands/code-workspace/add-projects.md",
+        "sha256": "7cd5a47c88185d276c0c4c38e18577e009e5e6d4ed99062554ff116b7e8d1812"
+      },
+      "provenance": {
+        "kind": "template"
+      }
+    },
+    {
+      "id": "workspace-claude-add-projects-skill",
+      "target": ".claude/skills/code-workspace-add-projects/SKILL.md",
+      "tools": [
+        "claude"
+      ],
+      "allowMissing": true,
+      "desired": {
+        "source": "templates/codex/skills/code-workspace-add-projects/SKILL.md",
+        "sha256": "f95847b00c93c2dd287247e226fecd6953286064dfde99b8ede830d181ef276f"
+      },
+      "provenance": {
+        "kind": "template"
+      }
+    },
+    {
+      "id": "workspace-codex-add-projects-skill",
+      "target": ".codex/skills/code-workspace-add-projects/SKILL.md",
+      "tools": [
+        "codex"
+      ],
+      "allowMissing": true,
+      "desired": {
+        "source": "templates/codex/skills/code-workspace-add-projects/SKILL.md",
+        "sha256": "f95847b00c93c2dd287247e226fecd6953286064dfde99b8ede830d181ef276f"
+      },
+      "provenance": {
+        "kind": "template"
+      }
+    },
+    {
+      "id": "workspace-claude-resolve-branch-skill",
+      "target": ".claude/skills/code-workspace-resolve-branch/SKILL.md",
+      "tools": [
+        "claude"
+      ],
+      "allowMissing": true,
+      "desired": {
+        "source": "templates/agents/skills/code-workspace-resolve-branch/SKILL.md",
+        "sha256": "d09b0e1847f5b39e6409ba3ac43f26fa5829a15690a3e216576e51535fb6b161"
+      },
+      "provenance": {
+        "kind": "template"
+      }
+    },
+    {
+      "id": "workspace-codex-resolve-branch-skill",
+      "target": ".codex/skills/code-workspace-resolve-branch/SKILL.md",
+      "tools": [
+        "codex"
+      ],
+      "allowMissing": true,
+      "desired": {
+        "source": "templates/agents/skills/code-workspace-resolve-branch/SKILL.md",
+        "sha256": "d09b0e1847f5b39e6409ba3ac43f26fa5829a15690a3e216576e51535fb6b161"
+      },
+      "provenance": {
+        "kind": "template"
+      }
+    }
+  ]
+}

package/artifacts/templates/USER_GUIDE.template.md

@@ -0,0 +1 @@
+{{WORKSPACE_USER_GUIDE}}

package/artifacts/templates/agents/WORKSPACE_GUARD.md.template

@@ -0,0 +1,73 @@
+# Workspace Context
+
+This directory is the Code Workspace control plane for multiple independent software projects. The workspace is not a project and is not the default location for production code.
+
+The registry is authoritative for project identity, ownership, location, and the registered branch. A project's `registeredBranch` is the Code Workspace expected state; its `actualBranch` is the selected Git worktree's observed state. A mismatch does not make either side automatically authoritative—the user chooses the reconciliation direction, and the CLI enforces it safely.
+
+## Select One Project Scope
+
+If the user explicitly names a registered project, resolve it directly:
+
+```bash
+code-w project show "<project.name>" --json
+```
+
+Only when project ownership cannot be determined, list registry metadata:
+
+```bash
+code-w project list --json
+```
+
+Use `name`, `type`, and `context` only to identify relevant candidates and ask the user to choose. Do not inspect candidate repositories while selecting.
+
+- You MUST NOT guess a project path or scan parent/sibling directories for projects.
+- If the registry is empty, ask which projects to manage and tell the user to run `{{ADD_PROJECTS_INVOCATION}}`.
+- If the user names an unregistered project, require registration before using its path.
+- Once selected, freeze the scope to that project. Do not read, verify, modify, repair, or comment on another registered project unless the user explicitly expands the request.
+- If multiple projects are explicitly included, pass their names as separate arguments to one targeted `project verify` invocation. When two or more results report `PROJECT_BRANCH_MISMATCH`, the branch Skill may present them in one combined choice. Batch CLI invocations are allowed, but their effects, diagnostics, transactions, and verification results remain project-isolated.
+
+Meta, help, or workspace-tool maintenance tasks that do not depend on registered project ownership do not require project selection.
+
+## Verify the Selected Project
+
+Before reading or modifying selected project code, run:
+
+```bash
+code-w project verify "<project.name>" --json
+```
+
+For several explicitly selected projects, use:
+
+```bash
+code-w project verify "<project-a>" "<project-b>" --json
+```
+
+- For one project, continue only when the targeted result has `ok: true`. For a multi-project result, evaluate every ordered project result independently: continue passed projects and keep failed projects paused even when the top-level `ok` is false.
+- On `PROJECT_BRANCH_MISMATCH`, pause affected project work and invoke the installed `code-workspace-resolve-branch` Skill. The Skill may combine mismatches from the explicitly selected scope into one concise question; do not choose a branch direction yourself.
+- For any other failure, report the targeted diagnostics and wait for user direction for the affected project; a failure in one batch result does not block unrelated successful selected projects. Do not escalate to full-workspace validation.
+- The branch Skill completes after `project branch verify` confirms alignment; it does not own overall project readiness. After its handoff, discard branch-dependent context and rerun targeted `project verify` for the successfully reconciled projects before resuming work.
+- If that overall verification fails for a non-branch reason, keep the affected project paused and handle the project-level diagnostic here without treating the branch Skill as failed. If a new `PROJECT_BRANCH_MISMATCH` appears because the branch drifted again, re-enter the Skill. Do not list or verify unrelated projects.
+- After branch verification succeeds—including projects whose branches were already aligned—run `project branch update-latest` for the selected projects:
+
+```bash
+code-w project branch update-latest "<project-a>" "<project-b>" --json
+```
+
+  Pass each selected project name as a separate argument; for a single project, pass only that project name. Evaluate each project result independently, including when the batch-level `ok` is `false`: continue only for projects whose individual result has `ok: true`, and treat `disabled` and `already-latest` as successful skips. If an update fails, keep that project paused and do not run ad-hoc `fetch`, `pull`, `reset`, `stash`, or `rebase` commands. For each successful or skipped project, discard pre-update context and rerun targeted `project verify` before starting project work.
+
+## Workspace Write Boundary
+
+The AI/Agent MUST NOT directly create, edit, move, or delete Workspace-owned files under the workspace root, including:
+
+- `.code-workspace/config.yaml` or `.code-workspace/state.json`
+- `.codex/config.toml`
+- `CLAUDE.md`, `AGENTS.md`, or other managed workspace files
+
+AI/Agent registry changes must use an approved `code-w` command. Users may manually edit `.code-workspace/config.yaml` and are responsible for the resulting configuration; AI/Agent must not imitate that edit with a script or direct file write. The CLI owns confirmation, concurrency checks, persistence or safe external effects, postconditions, rollback/compensation, and structured output. This boundary does not prevent user-requested production-code changes inside the selected external `project.location`.
+
+## Responsibilities
+
+- The CLI collects and verifies branch facts, performs safe reconciliation, and executes the explicitly configured latest-branch fast-forward.
+- The Agent explains facts, invokes the branch Skill, follows the user's selected direction, and invokes `project branch update-latest` after branch alignment.
+- The user decides whether to use the registered branch, accept the actual branch, or resolve manually.
+- Code Workspace does not edit production code, create branches, or resolve conflicts. Only `project branch update-latest` may fetch and fast-forward an explicitly enabled project; it never runs reset, stash, rebase, or non-fast-forward merge.