fix: finalize workflow documentation

AGENTS.md

@@ -4,6 +4,7 @@
 
 - 当前领域背景和术语：`CONTEXT.md`
 - 已确认的迁移期待办：`docs/migration-backlog.md`
+- 迁移契约和接口实现要点：`scripts/contract/CONTRACT-NOTES.md`
 - 历史需求、设计和任务：`docs/legacy/openspec/`
 - 新的长期技术决定：未来按需创建 `docs/adr/`
 
@@ -29,6 +30,18 @@ grill-with-docs
 - `implement`：按 Spec 或 Ticket 开发、测试和提交。
 - `code-review`：开发完成后检查变更。
 
+### Restore project skills
+
+Skill files are generated directories and are intentionally ignored by Git. After a fresh clone or worktree, materialize the ten locked matt-pocock Skills for Codex and Claude Code:
+
+```bash
+npx --yes skills add mattpocock/skills --skill grill-with-docs --skill implement --skill setup-matt-pocock-skills --skill to-spec --skill to-tickets --skill code-review --skill domain-modeling --skill grilling --skill tdd --skill triage --agent codex --copy -y
+npx --yes skills add mattpocock/skills --skill grill-with-docs --skill implement --skill setup-matt-pocock-skills --skill to-spec --skill to-tickets --skill code-review --skill domain-modeling --skill grilling --skill tdd --skill triage --agent claude-code --copy -y
+git restore --source=HEAD -- skills-lock.json
+```
+
+The first two commands materialize `.agents/skills/` and `.claude/skills/`. The final command keeps the repository's locked versions unchanged after the installer checks upstream metadata. Do not hand-edit `skills-lock.json`.
+
 ### Issue tracker
 
 正式 Spec 和 Ticket 使用本地 Markdown，位于 `.scratch/<feature-slug>/`，并提交到 Git。详细约定见 `docs/agents/issue-tracker.md`。
@@ -48,5 +61,5 @@ GitLab 用于代码分支、Merge Request、代码审查和合并，不为同一
 - 新需求从 matt-pocock 流程开始，不新建根目录 `openspec/` 或 `docs/legacy/openspec/changes/`。
 - 历史 `tasks.md` 不等同于当前任务清单；创建新 Ticket 前先核对当前代码和 `docs/migration-backlog.md`。
 - 正式 `.scratch/` 文件提交到 Git；临时讨论不写入 `.scratch/`。
-- 同一任务只选择 `.scratch/` 或 GitLab Issue 之一作为任务来源。
+- 同一任务只在 `.scratch/` 中维护一份正式记录；GitLab 只负责代码分支、Merge Request、审查和合并。
 - 修改前先读取相关 `CONTEXT.md` 和适用的 ADR；修改后验证实际行为或文档链接。

CONTEXT.md

@@ -4,26 +4,6 @@
 
 本项目是学有为内部资产管理后台，用于管理公司主体、人员、手机号、企微账号及其他业务资产。
 
-## 当前技术结构
-
-- 前端：Vue 3 + Vite，部署前缀为 `/asset/`。
-- 默认后端：TypeScript NestJS，前端开发代理默认指向 `127.0.0.1:7691`。
-- Java 后端：迁移期间保留，用作行为契约对拍基准，默认端口 `7690`。
-- 数据库：现有 MySQL 数据库，表名使用 `as_` 前缀；NestJS 的 Prisma schema 由现有数据库反向生成，只作只读映射。
-- 前端包管理器：pnpm；`frontend/package.json` 中的 `packageManager` 和 `volta` 字段是版本约束。
-
-## 迁移边界
-
-NestJS 迁移期间，Java 和 NestJS 并行运行。契约对拍要求两个后端的行为保持一致，因此迁移期间确认过的行为变更记录在 `docs/migration-backlog.md`，在契约全绿并完成迁移前不主动修改。
-
-当前已迁移的主要模块包括：
-
-- 认证和系统账号；
-- 公司档案和公司人员；
-- 手机号资产；
-- 企业微信账号；
-- 设备资产。
-
 ## 领域词汇
 
 | 术语 | 含义 |
@@ -33,29 +13,28 @@ NestJS 迁移期间，Java 和 NestJS 并行运行。契约对拍要求两个后
 | 手机号资产 | 台账中的手机号记录，可能来自手动建档或其他业务资产 |
 | 企微账号 | 企业微信账号及其与手机号资产的关联 |
 | 设备资产 | 设备及其图片、归属等信息 |
-| 微信账号 | 微信业务账号资产；当前仍保留在 Java 基准侧，尚未迁移到 NestJS。 |
-| 抖音账号 | 抖音业务账号资产；当前仍保留在 Java 基准侧，尚未迁移到 NestJS。 |
-| 域名资产 | 域名及其账号关联资产；当前仍保留在 Java 基准侧，尚未迁移到 NestJS。 |
-| 商户 | 商户业务资产记录；当前仍保留在 Java 基准侧，尚未迁移到 NestJS。 |
+| 微信账号 | 微信业务账号资产；当前仍保留在 Java 基准侧，尚未迁移到 NestJS |
+| 抖音账号 | 抖音业务账号资产；当前仍保留在 Java 基准侧，尚未迁移到 NestJS |
+| 域名资产 | 域名及其账号关联资产；当前仍保留在 Java 基准侧，尚未迁移到 NestJS |
+| 商户 | 商户业务资产记录；当前仍保留在 Java 基准侧，尚未迁移到 NestJS |
 | 资产来源 | 记录资产从哪类业务对象创建或关联而来 |
 | 系统账号 | 登录后台并受角色、状态和页面权限控制的用户 |
 | 契约对拍 | 用同一组请求对比 Java 和 NestJS 响应，确认迁移行为一致 |
 
-## 当前规则
+## 领域关系与约束
 
-- 前端默认使用 NestJS；需要与 Java 对拍时使用 `pnpm dev:java`。
-- 两个后端共享现有数据库，禁止在迁移期间执行 Prisma migration 改动表结构。
-- 资产来源关系是业务可追溯信息，修改资产关联规则时需要保留来源语义。
-- 角色、会话、软删除和错误响应属于迁移契约的一部分，行为变更先记录到迁移待办，再单独决策。
+- 公司主体可以关联公司人员和多类资产。
+- 手机号资产可以由人工建档，也可以由其他业务资产创建；资产来源用于保留这条追溯关系。
+- 企微账号可以与手机号资产关联；变更关联时必须保留可追溯的来源语义。
+- 系统账号受角色、状态和页面权限控制。
+- 迁移期间 Java 与 NestJS 的对外行为需要保持一致，已确认但暂缓的行为变更记录在 `docs/migration-backlog.md`。
 
-## 文档优先级
+## 文档入口
 
-```text
-当前代码
-> CONTEXT.md
-> docs/migration-backlog.md
-> docs/adr/ 中适用的当前 ADR
-> docs/legacy/openspec/ 中的历史资料
-```
+- 运行、启动和环境说明：`README.md`
+- 迁移契约、错误响应和对拍实现要点：`scripts/contract/CONTRACT-NOTES.md`
+- 已确认的迁移期待办：`docs/migration-backlog.md`
+- 当前架构决策：`docs/adr/` 中适用的 ADR（目录不存在时不视为阻塞）
+- 历史需求和设计：`docs/legacy/openspec/`
 
-OpenSpec 已封存到 `docs/legacy/openspec/`，不再作为新需求或当前任务的创建入口。
+OpenSpec 已封存，不再作为新需求或当前任务的创建入口。

README.md

@@ -13,7 +13,7 @@ docs/           迁移待办与设计记录
 ```
 
 迁移期两个后端并行运行：Java 占 **7690**，NestJS 占 **7691**。
-前端默认连 Java，通过环境变量可切到 NestJS，切换与回退都不需要改代码。
+前端默认连 NestJS（7691）；需要与 Java 对拍时使用 `pnpm dev:java`，切换不需要修改代码。
 
 ## 环境要求
 

docs/agents/domain.md

@@ -7,6 +7,7 @@
 - `CONTEXT.md`：当前项目背景、领域术语和系统边界。
 - `docs/adr/`：如果目录存在，读取与当前工作区域相关的 ADR。
 - `docs/migration-backlog.md`：涉及 NestJS 迁移期间暂缓的行为变更时读取。
+- `scripts/contract/CONTRACT-NOTES.md`：涉及接口行为、错误响应或 Java/NestJS 对拍时读取的契约依据。
 
 如果某个文档或目录尚不存在，继续当前工作，不要把它当作阻塞项；新的领域决定在确认后再创建对应文档。
 

docs/agents/issue-tracker.md

@@ -15,8 +15,8 @@
 
 - 正式 Spec 和 Ticket 必须提交到 Git，确保不同 worktree 和电脑可以读取同一份任务记录。
 - 临时讨论和一次性草稿不写入 `.scratch/`。
-- 同一事项只能选择 `.scratch/` 或 GitLab Issue 作为唯一任务来源，不重复创建。
-- GitLab 继续负责代码分支、Merge Request、审查和合并，不承担本地 Spec/Ticket 的重复记录。
+- `.scratch/` 是本项目正式 Spec/Ticket 的唯一任务来源；GitLab 不重复创建同一事项的 Issue。
+- GitLab 继续负责代码分支、Merge Request、审查和合并。
 
 ## Skill 行为
 

docs/plans/2026-09-16-openspec-to-matt-pocock-migration.md

@@ -211,11 +211,11 @@ chore: archive openspec history
 
 实施顺序：
 
-1. 在迁移 worktree 运行 `npx skills --help`，确认可用命令和 lockfile 行为；
-2. 通过安装工具支持的 `add` 流程从 `mattpocock/skills` 选择最小核心 Skill；
+1. 在迁移 worktree 运行 `npx --yes skills --help`，确认安装工具可用；
+2. 使用 `skills add` 从 `mattpocock/skills` 安装十个锁定 Skill，分别指定 `--agent codex` 和 `--agent claude-code`；
 3. 检查 `.agents/skills/`、`.claude/skills/` 和 `skills-lock.json` 的实际结果；
-4. 只有安装工具成功生成记录时，才提交 `skills-lock.json`；
-5. 如果安装工具不可用，继续完成 OpenSpec 封存，在 `AGENTS.md` 记录用户级 Skill 前提，并跳过 lockfile 修改。
+4. 如果安装工具顺手重算了无关 Skill 的 hash，运行 `git restore --source=HEAD -- skills-lock.json` 保留仓库锁定版本；
+5. 安装失败不阻塞 OpenSpec 封存，在 `AGENTS.md` 记录恢复命令和用户级前提。
 
 Skill 安装失败不得阻塞阶段一的历史封存。
 
@@ -319,7 +319,8 @@ wontfix
 ```text
 正式 Spec 和 Ticket → 提交到 Git，供不同 worktree 和电脑共享
 临时讨论和一次性草稿 → 不写入 .scratch/
-同一任务只能选择 .scratch/ 或 GitLab Issue 作为唯一来源，不得重复创建
+.scratch/ 是本项目正式 Spec/Ticket 的唯一任务来源
+GitLab 只负责代码分支、Merge Request、审查和合并
 ```
 
 当前 `.gitignore` 不忽略 `.scratch/`；未来创建正式任务时保持该约定。