mancode 0.4.1 → 0.5.0

package/README.en.md

@@ -17,7 +17,7 @@
 <p align="center">
   <a href="./LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg?style=flat-square" alt="License: AGPL-3.0" /></a>
   <a href="https://www.npmjs.com/package/mancode"><img src="https://img.shields.io/npm/v/mancode?style=flat-square" alt="npm version" /></a>
-  <img src="https://img.shields.io/badge/status-Continuity%20v0.4.1-2f855a?style=flat-square" alt="Status: mancode Continuity v0.4.1" />
+  <img src="https://img.shields.io/badge/status-Continuity%20v0.5.0-2f855a?style=flat-square" alt="Status: mancode Continuity v0.5.0" />
   <img src="https://img.shields.io/badge/platforms-Claude%20Code%20%7C%20Cursor%20%7C%20Codex%20%7C%20Copilot%20%7C%20ZCode-5865F2?style=flat-square" alt="Platforms: Claude Code, Cursor, Codex in ChatGPT desktop and CLI, GitHub Copilot, ZCode" />
 </p>
 
@@ -137,6 +137,13 @@ the code baseline, then run
 `MANCODE_GIT_REF_DEFERRED_SYNC_REQUIRED`; cross-clone synchronization is
 complete only after the push returns a receipt.
 
+Atomic git-ref mutations that explicitly require `--sync`, such as
+`workflow update`, complete the remote CAS before materializing the local
+projection. If a resumable `in_progress` or `blocked` task leaves tracked
+`.mancode/shared` changes, commit that projection and run the same
+`team sync push` with the unchanged task revision to rebind the remote code
+head. Another clone must not resume until this push returns a receipt.
+
 For a new project, start with one platform you actually use:
 
 ```bash
@@ -165,8 +172,9 @@ By default, `mancode init` creates mancode workflow and platform integration fil
 ├── schema.json
 ├── shared/config.json
 ├── shared/context/project.json
+├── shared/context/design-policy.json # optional; created by design configure
 ├── shared/team/
-└── local/                         # sessions, workflows, manps reports
+└── local/                         # sessions, workflows, scan reports, style cache
 
 .claude/skills/                  # Claude Code: bootstrap + original mode skills
 .cursor/rules/ + commands/       # Cursor: bootstrap + original mode commands
@@ -199,7 +207,7 @@ the original mode entries, never task/session snapshots. `mancode init
 - **Support team context**: use `/manteam` with confirmed typed entities under
   `.mancode/shared/`.
 - **Scan project health**: use `mancode manps` to detect stale TODOs, unused
-  dependencies, risky packages, and hardcoded design values.
+  dependencies, risky packages, mixed icon systems, and hardcoded design values.
 
 ## Best Fit
 
@@ -374,7 +382,7 @@ it should behave, and why previous decisions were made.
 
 ## Installation
 
-**Status**: mancode Continuity v0.4.1. Claude Code, Cursor, Codex in the ChatGPT
+**Status**: mancode Continuity v0.5.0. Claude Code, Cursor, Codex in the ChatGPT
 desktop app and CLI, GitHub Copilot, and ZCode adapters are included.
 
 Requires Node.js 20 or newer. macOS, Linux, Windows CMD, PowerShell, and Git Bash
@@ -469,8 +477,12 @@ mancode workflow verify <namespace:ULID> apply --file <verification-ledger.json>
 mancode workflow reframe <local:ULID> --expected-revision <n> --checkpoint-id <ULID> --session <id>
 mancode workflow complete <namespace:ULID> --expected-revision <n> --session <id>
 mancode manps [area]
+mancode design status --json
+mancode design context --json
+mancode design configure --expected-revision <n> [options]
+mancode design disable --expected-revision <n>
 mancode refresh-project
-mancode refresh-style
+mancode refresh-style [--root <relative-path>]
 mancode version
 ```
 
@@ -481,7 +493,7 @@ mancode version
 Simplified output:
 
 ```text
-mancode v0.4.1
+mancode v0.5.0
 
 Project:     my-app
 Runtime:     ready
@@ -571,6 +583,53 @@ Outputs:
 .mancode/local/preseason-reports/<timestamp>-<area>.md
 ```
 
+### `mancode design`
+
+Project design policy is opt-in. `mancode init` does not create a policy. When
+the policy is missing, disabled, or corrupt, `design context` safely resolves to
+`preserve`; ordinary coding and workflow recovery continue normally.
+Legacy projects can read this safe context, but only current Continuity projects
+can configure the shared policy.
+
+- `preserve` retains the existing hierarchy, layout, component system, and
+  interaction patterns while making only task-required UI changes.
+- `refine` improves hierarchy, typography, spacing, states, and responsive
+  behavior without changing the product structure.
+- `experimental` permits one coherent, product-appropriate visual direction
+  and more advanced composition or motion, but requires
+  `--confirm-experimental`. It never authorizes new product behavior,
+  information-architecture changes, or broader task scope.
+
+For a new UI surface or aesthetic redesign, if the user has not selected a
+visual direction, the agent first presents 2-3 distinct,
+product-appropriate directions with concise tradeoffs and a recommendation,
+then waits for the user to choose. Scoped UI fixes, changes within an existing
+design system, and tasks with an already selected direction continue directly.
+For brand, campaign, editorial, portfolio, and launch surfaces, `experimental`
+emphasizes a memorable first viewport and a visual motif carried through the
+full page; task-oriented products still prioritize workflow clarity.
+
+The policy stores only strict enums for preset, icons, emoji, motion, and browser
+validation, never free-form prompt text. Agents read code-generated guidance,
+quality gates, and a sanitized style summary through `mancode design context
+--json`. `--icons lucide` does not install Lucide; dependency changes still need
+explicit task approval.
+
+```bash
+mancode design status --json
+mancode design configure --expected-revision 0 --preset refine --icons lucide --emoji forbid-as-interface-icon --motion purposeful --browser-validation when-available
+mancode design context --json
+mancode design disable --expected-revision 1
+
+# experimental always needs an extra confirmation
+mancode design configure --expected-revision 0 --preset experimental --confirm-experimental
+```
+
+The policy lives at `.mancode/shared/context/design-policy.json` and should be
+reviewed and committed like other repository configuration. `configure` and
+`disable` update only the current checkout; they do not publish a git-ref remote
+sync receipt.
+
 ### `mancode refresh-style`
 
 Refreshes the project profile and, when UI assets are detected, rescans design
@@ -581,6 +640,11 @@ tokens. It updates:
 .mancode/shared/context/project.json
 ```
 
+For a monorepo, select one repository-relative UI root explicitly, for example
+`mancode refresh-style --root apps/web`. Absolute paths, traversal, and symlinks
+that escape the repository are rejected. Omitting `--root` preserves the
+whole-repository scan behavior.
+
 Platform adapters are static bootstraps that embed no task or style snapshot, so
 refreshing project facts does not require reinstalling them.
 
@@ -628,14 +692,16 @@ mancode/
 - Complete real-host session acceptance for Claude Code, Codex, Cursor,
   GitHub Copilot, and ZCode on one release candidate; verified host sessions
   and isolated explicit sessions are both valid evidence paths.
-- Run `npm run release:check -- --candidate <full-commit-sha>` for the clean
-  checkout, automated two-clone/legacy checks, tarball SHA-256, and install
-  smoke; complete cross-host recovery separately.
+- Merge the final candidate into `main`, then run
+  `npm run release:check -- --candidate <full-commit-sha>` from that same
+  `origin/main` commit for the clean checkout, automated two-clone/legacy
+  checks, tarball SHA-256, and install smoke; complete cross-host recovery
+  separately.
 - Confirm ZCode project-skill discovery and workspace-command paths; keep the
   adapter provisional until then.
 - Evaluate Windsurf, Cline, and Roo Code adapters based on real demand.
 
-See [0.4.1 Continuity Release Acceptance](./docs/release-acceptance.md) for the complete gate.
+See [0.4.2 Continuity Release Acceptance](./docs/release-acceptance.md) for the complete gate.
 
 ## Troubleshooting
 
@@ -660,7 +726,9 @@ hook architecture still uses `mancode init --legacy --force`.
 This means the platform's target files are missing or their digest is stale.
 Preview `mancode adapter upgrade --platform <platform> --dry-run`, inspect the
 staged result, then run it with the returned `--operation-id`, an active session,
-and `--confirm`. For managed-block
+and `--confirm`. A successful confirmation removes that operation's staging
+preview so internal temporary files cannot make a later Git sync report a dirty
+worktree. For managed-block
 platforms (Codex, ZCode, Copilot), the managed block in `AGENTS.md` or
 `.github/copilot-instructions.md` may have been manually edited or deleted.
 

package/README.md

@@ -17,7 +17,7 @@
 <p align="center">
   <a href="./LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg?style=flat-square" alt="许可证：AGPL-3.0" /></a>
   <a href="https://www.npmjs.com/package/mancode"><img src="https://img.shields.io/npm/v/mancode?style=flat-square" alt="npm 版本" /></a>
-  <img src="https://img.shields.io/badge/status-Continuity%20v0.4.1-2f855a?style=flat-square" alt="状态：mancode Continuity v0.4.1" />
+  <img src="https://img.shields.io/badge/status-Continuity%20v0.5.0-2f855a?style=flat-square" alt="状态：mancode Continuity v0.5.0" />
   <img src="https://img.shields.io/badge/platforms-Claude%20Code%20%7C%20Cursor%20%7C%20Codex%20%7C%20Copilot%20%7C%20ZCode-5865F2?style=flat-square" alt="平台：Claude Code、Cursor、ChatGPT 桌面端 Codex、Codex CLI、GitHub Copilot、ZCode" />
 </p>
 
@@ -116,6 +116,12 @@ git-ref 下的 workflow create、requirements、plan、review 和 verification
 `--sync` 会返回 `MANCODE_GIT_REF_DEFERRED_SYNC_REQUIRED`；只有拿到 push receipt
 才表示跨 clone 同步完成。
 
+`workflow update` 等明确要求 `--sync` 的原子 git-ref mutation 会先完成远端 CAS，
+再 materialize 本地投影。如果仍需 resume 的 `in_progress` 或 `blocked` 任务因此产生
+tracked `.mancode/shared` 变更，应先提交这些投影，再用不变的 task revision 执行同一条
+`team sync push`，把远端 code head 重绑到新提交；另一个 clone 只能在这次 push 返回
+receipt 后 resume。
+
 在全新项目中，从一个实际使用的平台开始：
 
 ```bash
@@ -153,8 +159,9 @@ legacy `state.json` 与当前工作流权威数据。
 ├── schema.json
 ├── shared/config.json
 ├── shared/context/project.json
+├── shared/context/design-policy.json # 可选：design configure 后创建
 ├── shared/team/
-└── local/                         # session、workflow、manps 报告
+└── local/                         # session、workflow、扫描报告和样式缓存
 
 .claude/skills/                  # Claude Code：bootstrap + 原 mode skills
 .cursor/rules/ + commands/       # Cursor：bootstrap + 原 mode commands
@@ -176,7 +183,7 @@ AGENTS.md                        # Codex（ChatGPT 桌面端/CLI）：托管 ins
 - **自由选择执行强度**：计划确认后，可只保留计划、交给默认 `solo` 轻量开发，或继续完整 `/man` 的验证与有界风险审查。
 - **保留工作流产物**：调研、计划、审查报告和总结会保存到 `.mancode/<namespace>/workflows/<ULID>/`。
 - **支持团队上下文**：`/manteam` 通过 `.mancode/shared/` 的类型化实体共享已确认信息。
-- **扫描项目健康度**：`mancode manps` 检测陈旧 TODO、未使用依赖、风险依赖和硬编码设计值。
+- **扫描项目健康度**：`mancode manps` 检测陈旧 TODO、未使用依赖、风险依赖、混用图标系统和硬编码设计值。
 
 ## 适合什么项目？
 
@@ -329,7 +336,7 @@ src/components/
 
 ## 安装
 
-**状态**：mancode Continuity v0.4.1。Claude Code、Cursor、ChatGPT 桌面端中的
+**状态**：mancode Continuity v0.5.0。Claude Code、Cursor、ChatGPT 桌面端中的
 Codex、Codex CLI、GitHub Copilot 和 ZCode adapter 均已接入。
 
 需要 Node.js 20 或更高版本。原生支持 macOS、Linux、Windows CMD、
@@ -422,8 +429,12 @@ mancode workflow verify <namespace:ULID> apply --file <verification-ledger.json>
 mancode workflow reframe <local:ULID> --expected-revision <n> --checkpoint-id <ULID> --session <id>
 mancode workflow complete <namespace:ULID> --expected-revision <n> --session <id>
 mancode manps [area]
+mancode design status --json
+mancode design context --json
+mancode design configure --expected-revision <n> [options]
+mancode design disable --expected-revision <n>
 mancode refresh-project
-mancode refresh-style
+mancode refresh-style [--root <relative-path>]
 mancode version
 ```
 
@@ -434,7 +445,7 @@ mancode version
 以下是简化输出示例：
 
 ```text
-mancode v0.4.1
+mancode v0.5.0
 
 Project:     my-app
 Runtime:     ready
@@ -521,6 +532,35 @@ mancode manps config
 .mancode/local/preseason-reports/<timestamp>-<area>.md
 ```
 
+### `mancode design`
+
+项目设计策略是显式启用功能。`mancode init` 不会创建策略；策略缺失、禁用或损坏时，
+`design context` 会安全降级为 `preserve`，普通编码和工作流恢复不受影响。
+Legacy 项目也可读取这个安全上下文，但只有当前 Continuity 项目能配置共享策略。
+
+- `preserve`：保持现有层级、布局、组件系统和交互模式，只完成任务要求的 UI 改动。
+- `refine`：在不改变产品结构的前提下改善层级、排版、间距、状态和响应式行为。
+- `experimental`：允许一个符合产品语境的统一视觉方向和更高级的构图/动效，但必须显式传入 `--confirm-experimental`；它不授权新增产品功能、改变信息架构或扩大任务范围。
+
+新建 UI 或视觉重做时，如果用户尚未选定视觉方向，Agent 会先给出 2–3 个差异明确、符合产品语境的方向，简述取舍并推荐一个，等待用户选择后再实现。局部 UI 修复、既有设计系统内的改动，以及用户已经选定方向的任务不会被这一步打断。`experimental` 对品牌、活动、编辑、作品集和发布型页面强调首屏记忆点与贯穿全页的视觉母题；对任务型产品仍优先保证工作流清晰度。
+
+策略只保存 preset、图标、表情、动效和浏览器验证的严格枚举，不保存自由文本提示词。
+Agent 通过 `mancode design context --json` 获取代码生成的固定指导、质量门槛和经过清洗的
+样式摘要。`--icons lucide` 不会自动安装 Lucide；依赖变更仍需任务明确授权。
+
+```bash
+mancode design status --json
+mancode design configure --expected-revision 0 --preset refine --icons lucide --emoji forbid-as-interface-icon --motion purposeful --browser-validation when-available
+mancode design context --json
+mancode design disable --expected-revision 1
+
+# experimental 必须额外确认
+mancode design configure --expected-revision 0 --preset experimental --confirm-experimental
+```
+
+策略保存在 `.mancode/shared/context/design-policy.json`，应像其他仓库配置一样审查并提交。
+`configure`/`disable` 只更新当前 checkout，不会发布 git-ref 远端同步回执。
+
 ### `mancode refresh-style`
 
 刷新项目 profile；检测到 UI 资产时，还会重新扫描设计 token。它会更新：
@@ -530,6 +570,9 @@ mancode manps config
 .mancode/shared/context/project.json
 ```
 
+Monorepo 可显式选择一个仓库内 UI 根目录，例如 `mancode refresh-style --root apps/web`。
+绝对路径、路径穿越和逃逸仓库的符号链接会被拒绝；不传 `--root` 时保持整仓扫描行为。
+
 平台 adapter 是不嵌入 task/style 快照的静态 bootstrap，因此刷新项目事实后不需要重装。
 
 ## 项目文件
@@ -570,11 +613,11 @@ mancode/
 ## 仍在推进
 
 - 在同一发布候选上完成 Claude Code、Codex、Cursor、GitHub Copilot 和 ZCode 的真实宿主 session 验收；宿主自动 session 和显式双 session 都是合法证据路径。
-- 使用 `npm run release:check -- --candidate <完整提交 SHA>` 完成干净 checkout、自动双 clone/legacy、tarball SHA-256 和安装 smoke；另完成跨真实宿主恢复。
+- 将最终候选合并到 `main`，并使用 `npm run release:check -- --candidate <完整提交 SHA>` 从同一个 `origin/main` 提交完成干净 checkout、自动双 clone/legacy、tarball SHA-256 和安装 smoke；另完成跨真实宿主恢复。
 - 确认 ZCode 项目级 skill 发现和 workspace command 路径；完成前继续标记为 provisional。
 - 根据真实需求评估 Windsurf、Cline 和 Roo Code adapter。
 
-完整发布条件见 [0.4.1 Continuity 发布验收](./docs/release-acceptance.md)。
+完整发布条件见 [0.4.2 Continuity 发布验收](./docs/release-acceptance.md)。
 
 ## 故障排查
 
@@ -596,7 +639,8 @@ mancode/
 
 该平台的目标文件缺失或 digest 不匹配。先运行
 `mancode adapter upgrade --platform <platform> --dry-run`，确认 staging 结果后再用
-该预览返回的 `--operation-id` 和 active session 执行 `--confirm`。
+该预览返回的 `--operation-id` 和 active session 执行 `--confirm`。确认成功后会删除
+该 operation 的 staging 预览，避免内部临时文件让后续 Git 同步误判工作区不干净。
 对于 Codex、ZCode 和 Copilot，`AGENTS.md` 或 `.github/copilot-instructions.md`
 中的受控区可能被手动编辑或删除了。
 

package/dist/{chunk-S3BAOJPP.js → chunk-3FOBYCF4.js}

@@ -3632,10 +3632,6 @@ var WorkflowPolicyVersionUnsupportedError = class extends Error {
     this.requiredWriter = requiredWriter;
     this.name = "WorkflowPolicyVersionUnsupportedError";
   }
-  component;
-  observedVersion;
-  supportedVersions;
-  requiredWriter;
   code = "MANCODE_POLICY_VERSION_UNSUPPORTED";
 };
 var TRANSITION_STATES = /* @__PURE__ */ new Set([
@@ -7275,4 +7271,4 @@ export {
   V3ContextStore,
   storedTaskAggregateDigest
 };
-//# sourceMappingURL=chunk-S3BAOJPP.js.map
+//# sourceMappingURL=chunk-3FOBYCF4.js.map