@ai-content-space/loopx 0.1.2 → 0.1.4

package/README.zh-CN.md

@@ -0,0 +1,485 @@
+<p align="center">
+  <img src="./assets/logo.svg" alt="loopx fox logo" width="128" height="128">
+</p>
+
+<h1 align="center">loopx</h1>
+
+<p align="center">
+  面向 Codex 的 skill-first 工作流运行时。
+</p>
+
+[English](./README.md)
+
+`loopx` 是一个面向 Codex 的 skill-first 工作流工具包。它把需求澄清、共识规划、持久执行、独立评审组织成一条可追踪的本地工作流，并通过 CLI 与 Codex Skill 两种方式暴露同一套运行时。
+
+当前公开流程：
+
+```text
+clarify -> plan -> build -> review -> approve review->done -> archive
+```
+
+`done` 是通过 `loopx approve <slug> --from review --to done` 进入的运行时完成状态，不是单独的 Codex skill。
+
+评审通过并进入 `done` 后，可以执行 archive，把本次被接受的 change delta 合并到长期 specs。
+
+其中 `autopilot` 是端到端编排入口，会在内部复用这套公开阶段，而不是引入另一套流程真相。
+
+## 特性
+
+- 安装并公开 11 个 loopx Codex skills：工作流 skills `clarify`、`plan`、`build`、`review`、`archive`、`autopilot`，质量辅助 skills `debug`、`tdd`、`verify`，以及 Go 支持 skills `go-style`、`kratos`。
+- 支持 npm 全局安装和 Codex plugin 安装，两种安装方式共享同一套 install/discovery 逻辑。
+- 自动安装 loopx 管理的 Codex workflow hook，在 Codex 中提示当前 workflow 状态和安全下一步。
+- 所有运行时状态和阶段产物都写入项目本地 `.loopx/`，便于审计、恢复和迁移。
+- clarify 需求快照写入 `.loopx/intake/`，让 `.loopx/specs/` 只承载长期领域规格。
+- `plan` 默认采用 Planner -> Architect -> Critic 的共识规划循环。
+- `plan` 会写入借鉴 OpenSpec 的 change artifacts：proposal、spec delta、design、tasks 和 artifact dependency graph。
+- 提供项目级 agent context：`.loopx/agents/` 和 `.loopx/context/domain.md`，供 build/review 的 context manifest 消费。
+- `build` 默认包含执行记录、验证证据、架构验收、deslop 清理和回归再验证。
+- `review` 作为独立验收面，包含代码审查和内部 architecture-smell lane，并输出中文评审结论和 go/no-go 判断。
+- 支持 `archive`，把已批准的 change delta 同步进长期 `.loopx/specs/` source of truth，并生成 ADR candidate。
+
+## 安装
+
+### npm 全局安装
+
+```bash
+npm install -g @ai-content-space/loopx
+```
+
+安装后会自动运行：
+
+```bash
+node scripts/install-skills.mjs
+```
+
+该脚本会把 loopx 管理的 skills 安装到：
+
+```text
+~/.agents/skills/
+```
+
+同时也会把 loopx 管理的 Codex workflow hook 安装到：
+
+```text
+~/.codex/hooks/codex-workflow-hook.mjs
+```
+
+并更新：
+
+```text
+~/.agents/.skill-lock.json
+```
+
+### Codex plugin 安装
+
+插件入口位于：
+
+```text
+plugins/loopx/
+```
+
+插件安装脚本：
+
+```bash
+node plugins/loopx/scripts/plugin-install.mjs
+```
+
+npm 安装和 plugin 安装会收敛到同一个 `installationIdentity=loopx`，避免 Codex 里出现重复的 loopx skill 集合。
+
+## 快速开始
+
+初始化一个工作流：
+
+```bash
+loopx init --slug my-task
+```
+
+进入澄清阶段：
+
+```bash
+loopx clarify my-task
+```
+
+澄清完成后批准进入计划阶段：
+
+```bash
+loopx approve my-task --from clarify --to plan
+loopx plan my-task
+```
+
+计划完成后批准执行：
+
+```bash
+loopx approve my-task --from plan --to build
+loopx build my-task
+```
+
+执行完成后进入评审：
+
+```bash
+loopx approve my-task --from build --to review
+loopx review my-task
+```
+
+评审通过后完成工作流：
+
+```bash
+loopx approve my-task --from review --to done
+```
+
+把已接受行为归档到长期 specs：
+
+```text
+$archive my-task
+```
+
+查看状态：
+
+```bash
+loopx status my-task
+loopx status my-task --json
+```
+
+生成派生 HTML 阅读视图：
+
+```bash
+loopx render my-task
+```
+
+也可以让 loopx 根据一个现成 spec 直接创建规划工作流：
+
+```bash
+loopx plan --direct ./path/to/spec.md
+```
+
+## CLI 命令
+
+```bash
+loopx init [--slug <slug>]
+loopx clarify <slug> [--standard|--deep]
+loopx approve <slug> --from <stage> --to <stage>
+loopx plan [slug] [--direct <spec-path>] [--interactive] [--deliberate]
+loopx build <slug> [--no-deslop]
+loopx build --from-review <review-report-path> [--no-deslop]
+loopx review <slug> [--reviewer <name>]
+loopx archive <slug>
+loopx autopilot <slug> [--reviewer <name>]
+loopx render [slug|--all]
+loopx status [slug] [--json]
+loopx setup-context
+loopx doctor
+loopx migrate
+loopx repair-install
+```
+
+CLI 主要用于运行时、调试、状态观察和维护。日常面向 Codex 的主入口是同名 skills，例如 `$clarify`、`$plan`、`$build`、`$review`、`$archive`、`$autopilot`、`$debug`、`$tdd`、`$verify`、`$go-style`、`$kratos`。
+
+`loopx status` 仍然是 CLI/runtime 诊断命令，不作为单独 Codex skill 暴露。`loopx render` 会基于现有运行时产物生成给人阅读的 HTML 视图；不传 slug 时会渲染所有非 legacy workflow 和工作区首页。Markdown 和 JSON 仍然是机器可读、可编辑的事实源。
+
+## Skill 说明
+
+### clarify
+
+`clarify` 用于把模糊请求转成可执行 spec。它会维护歧义分数、非目标、决策边界和压力测试结果。只有满足门禁后，才建议进入 `plan`。
+
+默认 profile：
+
+- `--standard`：目标歧义分数 `<= 0.20`，最多 `15` 轮。
+- `--deep`：目标歧义分数 `<= 0.10`，最多 `25` 轮。
+
+### plan
+
+`plan` 把已批准的 clarify spec 或直接输入的 spec 转成计划包。默认包含 Planner、Architect、Critic 三段式评审循环，最多迭代到通过或达到上限。
+
+主要产物：
+
+- `.loopx/plans/prd-<slug>.md`
+- `.loopx/plans/test-spec-<slug>.md`
+- `.loopx/changes/active/<change-id>/proposal.md`
+- `.loopx/changes/active/<change-id>/spec-delta.md`
+- `.loopx/changes/active/<change-id>/design.md`
+- `.loopx/changes/active/<change-id>/tasks.md`
+- `.loopx/changes/active/<change-id>/artifact-graph.json`
+- `.loopx/workflows/<slug>/plan.md`
+- `.loopx/workflows/<slug>/architecture.md`
+- `.loopx/workflows/<slug>/development-plan.md`
+- `.loopx/workflows/<slug>/test-plan.md`
+
+`spec-delta.md` 使用 requirement delta：`## ADDED Requirements`、`## MODIFIED Requirements`、`## REMOVED Requirements` 和 `## RENAMED Requirements`。ADDED / MODIFIED 必须是完整的 `### Requirement:` 块，包含 SHALL/MUST 约束和 `#### Scenario:` 场景，archive 才能把它们合并进长期 spec 当前状态。
+
+### build
+
+`build` 执行已批准的计划，并把执行过程、验证证据和限制记录到 canonical artifact：
+
+```text
+.loopx/workflows/<slug>/execution-record.md
+```
+
+`build` 内部保留结构化 runtime lanes，同时增加 Ralph-like owner loop：单一 owner 持续推进，可并行 delegation，但进入 review handoff 前必须满足 blocking delegation 已 drain，并通过 completion audit。相关运行态证据写入：
+
+```text
+.loopx/workflows/<slug>/build-support/delegation-ledger.json
+.loopx/workflows/<slug>/build-support/completion-audit.json
+```
+
+这些仍然是 build 支撑证据，不替代 `execution-record.md`。
+
+默认流程包含 deslop 清理；如果确实要跳过，可以使用：
+
+```bash
+loopx build <slug> --no-deslop
+```
+
+当 review 要求修实现问题时，Codex 侧的正常回路把 review artifact 作为本轮返工合同：
+
+```text
+$build --from-review .loopx/workflows/<slug>/review-report.md
+```
+
+已批准 PRD、test spec、上次 `execution-record.md` 和 workflow-local plan package 仍会作为支撑上下文加载，但不再让用户把 PRD 当成本轮返工的主参数。
+
+### review
+
+`review` 消费 build 输出的 `execution-record.md`，执行独立验收、代码评审和轻量 architecture-smell lane，并生成：
+
+```text
+.loopx/workflows/<slug>/review-report.md
+```
+
+最终用户可见评审结果要求使用中文。
+
+如果评审通过，仍然需要显式批准 `review -> done`。如果评审要求修实现问题，则运行 `$build --from-review .loopx/workflows/<slug>/review-report.md`。只有当 review 明确指出计划或需求本身错误时，才回到 `$plan <slug>` 或 `$clarify <slug>`。
+
+architecture-smell lane 是 review 的一部分，不会增加新阶段。它会把发现记录到 `review-support/architecture-smell.json`，只有当模块边界、可测试性、领域词汇或计划架构假设存在实质性错误时才阻断。
+
+### archive
+
+`archive` 消费已完成工作流，并把 `.loopx/changes/active/<change-id>/spec-delta.md` 合并进 `.loopx/specs/` 下的长期领域规格。归档后的 change 目录会移动到：
+
+```text
+.loopx/changes/archive/<change-id>/
+```
+
+Archive 还会在 `.loopx/decisions/adr-candidates/<change-id>.md` 写入建议性 ADR candidate，不会自动提升到 `docs/adr/`。
+
+Archive 现在按语义应用 requirement delta，而不是追加每次 change 的历史块。ADDED 新增 requirement，MODIFIED 替换完整 requirement 块，REMOVED 删除 requirement，RENAMED 只修改 requirement 标题并保留正文。
+
+### autopilot
+
+`autopilot` 是端到端编排入口，会在内部组织 expansion、planning、execution、qa、validation 等阶段，但 canonical artifact 仍然来自公开的 `clarify -> plan -> build -> review` 流程。
+
+自动编排 ledger 写入：
+
+```text
+.loopx/autopilot/<slug>/run.json
+```
+
+### debug
+
+`debug` 是用于 bug、测试失败、回归和异常行为的质量辅助 skill。它要求先完成根因调查，再进入模式对比、假设验证和修复实现，避免直接猜测式打补丁。
+
+### tdd
+
+`tdd` 是用于功能开发和 bug 修复的质量辅助 skill。它要求先写失败测试，确认失败原因正确，再实现最小可通过改动。
+
+### verify
+
+`verify` 是用于最终完成声明前的质量辅助 skill。它要求在声称完成、修好、测试通过、可提交或可评审之前，先运行 fresh verification 并读取真实输出。
+
+### go-style
+
+`go-style` 是 Go 语言支持 skill。它用于指导 `.go` 文件编辑，强调 idiomatic Go、保留项目本地风格、清晰错误处理、小接口、表驱动测试，以及 `gofmt` 和 Go 验证。
+
+### kratos
+
+`kratos` 是 Go-Kratos 框架支持 skill。当项目出现 `buf.yaml`、proto API、`internal/service`、`internal/biz`、`internal/data` 或 `github.com/go-kratos/kratos/v2` 等信号时使用，并提供 proto 设计、分层架构、配置、中间件、认证、HTTP 定制和排错参考。
+
+## 运行时目录
+
+loopx 在当前项目下写入 `.loopx/`：
+
+```text
+.loopx/
+  README.md
+  config.json
+  intake/
+    clarify-<slug>-<timestamp>.md
+  views/
+    index.html
+  specs/
+    <domain>/
+      spec.md
+  changes/
+    active/
+      <change-id>/
+        proposal.md
+        spec-delta.md
+        design.md
+        tasks.md
+        slices.json
+        artifact-graph.json
+    archive/
+      <change-id>/
+  decisions/
+    adr-candidates/
+  plans/
+  agents/
+    issue-tracker.md
+    domain.md
+    triage-labels.md
+  context/
+    domain.md
+  workflows/
+    <slug>/
+      state.json
+      spec.md
+      plan.md
+      architecture.md
+      development-plan.md
+      test-plan.md
+      execution-record.md
+      review-report.md
+      view/
+        index.html
+        intake.html
+        plan.html
+        build.html
+        review.html
+      plan-reviews/
+      build-support/
+  autopilot/
+    <slug>/
+      run.json
+```
+
+`intake` 保存一次需求的 clarify 快照；`workflows` 保存当前任务的运行时工作副本；`changes` 保存本次需求对长期行为的 change delta；`specs` 只保存 archive 后的长期领域行为契约。
+
+`views/` 和 `workflows/<slug>/view/` 是 `loopx render` 生成的派生 HTML 阅读视图，只服务于人的浏览和评审，可以随时重新生成；agent 和工具仍应读取、修改 Markdown 与 JSON 产物。
+
+### 文档关注边界
+
+用户日常需要关注的文档：
+
+- `README.md` / `README.zh-CN.md`：产品用法、命令和目录约定。
+- `.loopx/workflows/<slug>/spec.md`：当前需求工作副本。
+- `.loopx/workflows/<slug>/plan.md`、`architecture.md`、`development-plan.md`、`test-plan.md`：当前任务的计划、架构和验证约定。
+- `.loopx/workflows/<slug>/execution-record.md`、`review-report.md`：执行证据和评审结论。
+- `.loopx/views/index.html` 与 `.loopx/workflows/<slug>/view/index.html`：由 `loopx render` 生成的阅读入口。
+
+用户可以阅读和按流程修改的事实源文档：
+
+- `.loopx/workflows/<slug>/*.md`：当前 workflow 的可编辑工作副本；修改后仍需通过对应阶段门禁。
+- `.loopx/context/domain.md` 和 `.loopx/agents/*.md`：项目级背景、术语和 agent 协作约定。
+- `.loopx/changes/active/<change-id>/*.md`：plan 生成的 change proposal、design、tasks 和 spec delta；修改后应重新过 plan/build/review。
+- `.loopx/specs/<domain>/spec.md`：archive 后的长期行为规格；通常由 `archive` 同步，人工改动需要保持和后续 change delta 一致。
+
+工具运行依赖或派生的文档/数据：
+
+- `.loopx/workflows/<slug>/state.json`、`build-context.jsonl`、`review-context.jsonl`：运行时状态和 context manifest，工具依赖，不建议手改。
+- `.loopx/workflows/<slug>/plan-reviews/`、`build-support/`、`review-support/`：阶段证据和内部审查结果，供诊断和 review 使用。
+- `.loopx/intake/clarify-*.md`：clarify 快照，用于审计和追溯；不要当作长期 specs 修改。
+- `.loopx/changes/active/<change-id>/slices.json`、`artifact-graph.json`：计划结构化数据，build/review/archive 会消费。
+- `.loopx/autopilot/<slug>/run.json`、`.loopx/build-active.json`：编排和 stop-hook 运行态。
+- `.loopx/views/` 和 `.loopx/workflows/<slug>/view/`：HTML 派生视图，可删除后用 `loopx render` 重新生成，不应作为事实源编辑。
+
+## 安装诊断与修复
+
+检查运行时和 skill 安装状态：
+
+```bash
+loopx doctor
+```
+
+修复 loopx 管理的 skill 安装：
+
+```bash
+loopx repair-install
+```
+
+只检查当前 skill discovery 状态：
+
+```bash
+node scripts/install-skills.mjs --check
+```
+
+## Codex Workflow Hook
+
+`install-skills.mjs` 和 Codex plugin 安装脚本会自动把 `scripts/codex-workflow-hook.mjs` 安装到：
+
+```text
+~/.codex/hooks/codex-workflow-hook.mjs
+```
+
+该 hook 会读取最近的 `.loopx/workflows/<slug>/state.json`，为当前 workflow 输出建议性上下文：当前阶段、blockers、readiness、authorization、evidence 和安全下一步。它只提供提示；真正的运行时门禁仍以 loopx runtime 为准。
+
+设置 `LOOPX_HOOKS=0` 可以关闭 workflow hook 输出。
+
+## Codex Stop Hook
+
+loopx 内置一个 Codex stop-hook 辅助脚本，用于防止活跃 build 在达到 review handoff 之前提前停止：
+
+```bash
+node scripts/codex-stop-hook.mjs
+```
+
+`loopx build` 运行期间会写入持久状态：
+
+```text
+.loopx/build-active.json
+```
+
+如果状态显示 build 仍处于 `starting`、`executing`、`verifying` 或 `fixing`，hook 会返回 `allow: false` 和继续执行提示。只有 build 已经 `review-ready`、被真实 blocker 阻塞、失败、取消或不活跃时，hook 才允许停止。
+
+## 环境变量
+
+安装和 discovery 逻辑支持以下环境变量：
+
+- `LOOPX_HOME`：覆盖默认 home 目录。
+- `LOOPX_AGENTS_ROOT`：覆盖 `.agents` 根目录。
+- `LOOPX_SKILLS_ROOT`：覆盖已安装 skills 目录。
+- `LOOPX_SKILL_LOCK_PATH`：覆盖 skill lock 文件路径。
+- `LOOPX_PROJECT_ROOT`：覆盖 loopx 项目根目录。
+- `LOOPX_SKILL_SOURCE_ROOT`：覆盖 skill 源目录。
+- `LOOPX_DISTRIBUTION_CHANNEL`：设置安装渠道，默认 `npm`。
+- `LOOPX_INSTALLATION_IDENTITY`：设置安装身份，默认 `loopx`。
+- `LOOPX_SOURCE_URL`：设置安装来源。
+- `LOOPX_HOOKS`：设置为 `0` 时关闭 workflow hook 输出。
+
+## 开发
+
+安装依赖后运行测试：
+
+```bash
+npm test
+```
+
+也可以直接执行项目内的验证命令：
+
+```bash
+node --test test/*.test.mjs
+node scripts/install-skills.mjs --check
+node --test plugins/loopx/scripts/plugin-install.test.mjs
+node src/cli.mjs --help
+node src/cli.mjs doctor
+node src/cli.mjs status --json
+```
+
+## 发布内容
+
+`package.json` 的 `files` 字段会发布以下内容：
+
+- `README.md`
+- `README.zh-CN.md`
+- `package.json`
+- `scripts/install-skills.mjs`
+- `scripts/codex-stop-hook.mjs`
+- `scripts/codex-workflow-hook.mjs`
+- `assets/logo.svg`
+- `src/`
+- `skills/`，包含公开 loopx skills 以及随包发布的兼容/内部 skill 源文件
+- `templates/`
+- `plugins/loopx/`
+
+## 版本
+
+当前 npm 包版本：`0.1.4`。

package/assets/logo.svg

@@ -0,0 +1,89 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" role="img" aria-labelledby="title desc">
+  <title id="title">loopx fox logo</title>
+  <desc id="desc">A cute black and white fox mascot in left-facing profile with a curled tail.</desc>
+<g transform="translate(0.000000,256.000000) scale(0.025000,-0.025000)"
+fill="#000000" stroke="none">
+<path d="M5828 9086 c-59 -21 -132 -81 -223 -184 -395 -444 -774 -1140 -908
+-1667 -18 -71 -37 -131 -42 -133 -6 -1 -57 9 -115 22 -103 25 -262 46 -337 46
+l-38 0 76 -74 77 -73 -109 -7 c-119 -7 -305 -36 -384 -60 -27 -8 -50 -14 -52
+-12 -5 5 136 62 212 85 39 12 98 25 133 28 34 3 65 9 67 14 3 4 -28 36 -69 72
+l-74 65 45 6 c117 16 292 5 493 -30 l35 -6 12 54 c7 29 27 97 44 150 l32 97
+-58 73 c-262 326 -572 612 -891 822 -279 182 -403 179 -451 -12 -21 -81 -28
+-399 -14 -563 27 -304 117 -651 222 -861 16 -32 29 -61 29 -65 0 -4 -18 -21
+-40 -36 -22 -16 -40 -31 -40 -35 0 -4 48 -6 107 -5 105 3 107 2 83 -15 -230
+-161 -385 -319 -497 -507 -119 -200 -152 -337 -163 -670 -6 -224 -9 -245 -34
+-320 -54 -161 -155 -291 -319 -413 -168 -125 -284 -186 -394 -207 -92 -18
+-179 -59 -208 -98 -33 -46 -27 -137 14 -214 61 -115 199 -252 270 -270 14 -3
+46 -25 71 -47 56 -52 126 -100 187 -130 27 -12 68 -42 93 -65 56 -53 197 -122
+310 -153 74 -20 108 -23 260 -22 158 0 195 4 380 38 326 59 478 59 564 -2 109
+-76 104 -238 -11 -381 -54 -67 -92 -102 -248 -227 -77 -61 -158 -131 -181
+-155 -50 -55 -128 -169 -120 -176 3 -3 33 0 67 6 34 7 100 16 148 19 l87 7
+-69 -79 c-88 -103 -142 -196 -186 -321 -33 -94 -35 -108 -35 -230 -1 -165 23
+-267 99 -420 138 -279 371 -495 708 -655 244 -116 483 -177 722 -186 116 -4
+137 -2 121 8 -10 7 -57 39 -105 70 -47 31 -102 70 -121 86 l-35 30 160 -6
+c605 -19 1215 178 1665 538 89 72 227 206 219 214 -2 3 -33 -1 -69 -9 -194
+-40 -295 -50 -530 -49 -195 0 -255 4 -350 22 -398 73 -641 226 -704 441 -56
+190 20 400 217 608 68 71 246 223 262 223 4 0 5 -19 2 -43 -7 -50 3 -187 13
+-187 4 0 44 62 90 138 100 164 159 246 282 387 168 193 181 209 224 276 87
+133 132 269 141 424 5 93 -2 160 -33 295 -4 20 0 16 21 -15 45 -69 83 -149
+111 -236 32 -99 35 -96 65 79 24 141 25 341 3 467 -45 261 -171 492 -384 705
+-63 64 -136 131 -162 150 -27 18 -46 35 -44 38 7 7 154 -75 223 -124 153 -109
+270 -248 354 -418 68 -141 100 -273 108 -451 l6 -140 105 -6 c112 -7 162 -17
+250 -47 263 -91 456 -295 506 -532 23 -107 14 -345 -15 -454 -82 -297 -270
+-573 -551 -808 -336 -282 -844 -513 -1274 -580 -42 -6 -76 -15 -76 -19 0 -19
+211 -74 362 -94 932 -123 1887 474 2182 1365 68 206 80 288 80 545 0 212 -2
+240 -26 356 -99 459 -337 832 -722 1131 -49 38 -170 123 -270 190 -255 172
+-308 211 -271 203 55 -12 129 -36 208 -67 43 -17 80 -28 84 -25 9 10 -63 153
+-118 232 -67 98 -185 209 -288 272 -45 28 -78 53 -74 56 17 11 141 29 238 35
+l100 7 -50 37 c-86 64 -204 130 -340 190 -71 32 -135 58 -141 58 -6 0 -24 -28
+-40 -62 -35 -77 -128 -217 -184 -278 l-40 -45 34 60 c80 141 141 319 183 530
+25 127 25 501 0 670 -69 465 -238 944 -470 1330 -187 313 -349 454 -469 411z
+m91 -422 c80 -67 234 -356 310 -579 86 -256 129 -488 138 -751 14 -420 -80
+-781 -283 -1087 -64 -96 -66 -100 -56 -136 31 -102 111 -189 316 -343 194
+-146 191 -143 141 -122 -104 43 -606 309 -644 341 -16 12 16 7 92 -17 48 -15
+87 -24 87 -19 0 11 -119 160 -174 217 -61 65 -169 151 -275 221 -51 33 -90 61
+-87 61 12 0 151 -39 195 -55 24 -8 46 -14 48 -12 2 2 -29 34 -68 72 -130 122
+-334 240 -521 302 -100 32 -98 29 -98 169 0 392 184 908 486 1364 132 200 306
+400 347 400 9 0 29 -12 46 -26z m-2425 -576 c108 -185 314 -628 291 -628 -2 0
+-32 18 -66 40 -34 22 -64 38 -66 36 -8 -7 62 -149 120 -244 31 -51 57 -95 57
+-97 0 -1 -33 8 -72 20 -40 13 -75 22 -77 19 -6 -6 62 -107 103 -152 21 -23 37
+-44 35 -45 -2 -2 -24 -12 -48 -22 -24 -11 -80 -43 -124 -72 -44 -29 -81 -52
+-81 -50 -58 154 -111 370 -142 577 -34 238 -27 710 11 710 3 0 29 -42 59 -92z
+m528 -2172 c132 -40 244 -122 317 -231 56 -84 92 -176 71 -183 -55 -19 -175
+-90 -222 -131 l-56 -51 -7 39 c-11 64 -61 158 -110 205 -59 58 -122 87 -199
+93 -133 11 -234 -55 -300 -196 -44 -94 -70 -221 -61 -301 7 -66 32 -157 49
+-185 13 -19 11 -20 -71 -20 l-84 0 6 110 c30 540 154 794 420 862 59 15 178 9
+247 -11z m-134 -377 c36 -18 74 -46 93 -70 68 -86 90 -219 48 -289 -32 -52
+-88 -118 -120 -140 l-27 -20 25 72 c22 63 25 85 21 173 -3 73 -10 112 -25 146
+-26 57 -88 128 -128 145 l-30 13 41 1 c26 0 63 -11 102 -31z m-224 -78 c49
+-54 15 -163 -53 -169 -49 -5 -71 20 -71 79 0 86 77 142 124 90z m1291 -361
+c50 -6 126 -17 170 -26 86 -17 272 -77 287 -92 6 -6 -23 -10 -74 -11 -119 -2
+-338 -42 -338 -61 0 -4 33 -10 74 -13 207 -18 461 -103 611 -207 78 -54 169
+-146 221 -222 44 -67 113 -215 114 -246 0 -7 -29 3 -77 27 -99 49 -193 78
+-313 96 -99 15 -212 20 -223 9 -4 -4 19 -22 51 -41 69 -41 171 -140 214 -206
+31 -49 78 -165 78 -193 0 -10 -26 8 -66 44 -75 69 -196 134 -294 157 -116 27
+-118 24 -36 -57 46 -46 86 -97 107 -138 33 -63 34 -68 34 -185 0 -112 -2 -125
+-31 -190 -79 -182 -200 -307 -558 -575 -142 -106 -304 -237 -359 -289 -209
+-201 -328 -391 -399 -636 -19 -67 -23 -103 -23 -225 1 -136 3 -151 32 -239
+l32 -94 -41 39 c-86 84 -159 206 -199 334 -19 62 -24 96 -23 195 0 74 6 144
+16 183 8 35 12 62 7 60 -5 -2 -29 -30 -54 -63 -46 -62 -95 -168 -95 -207 0
+-16 -3 -19 -11 -11 -21 21 -14 229 10 322 49 187 179 378 356 522 36 29 63 54
+61 56 -2 2 -86 -6 -186 -17 -100 -12 -184 -20 -186 -17 -8 8 69 71 231 188
+174 127 300 248 352 339 36 63 63 148 63 197 0 32 4 36 65 64 36 16 86 32 111
+36 24 3 46 9 49 13 8 12 -138 78 -220 99 -119 31 -205 41 -350 41 -146 0 -233
+-11 -550 -72 -198 -38 -234 -42 -365 -42 -159 1 -254 20 -347 68 l-48 25 86 1
+c285 1 546 111 724 302 105 114 128 178 61 178 -31 0 -41 -10 -71 -69 -77
+-154 -278 -283 -510 -326 -67 -13 -123 -16 -220 -12 -145 5 -230 26 -325 80
+-55 31 -150 112 -150 128 0 4 13 28 30 52 39 58 86 179 95 242 4 34 2 65 -8
+92 l-14 42 46 10 c94 21 158 23 335 11 313 -21 423 8 776 205 113 63 252 135
+309 160 319 139 660 198 956 165z m-2567 -537 l57 -28 -87 -6 c-51 -4 -104
+-15 -131 -27 l-45 -20 -26 27 c-24 25 -25 29 -11 41 55 46 162 51 243 13z"/>
+<path d="M5937 8202 c-48 -198 -131 -379 -247 -532 -22 -30 -36 -56 -31 -58
+16 -5 144 65 189 104 22 19 42 34 45 34 2 0 -2 -35 -10 -77 -32 -169 -114
+-321 -248 -462 -44 -46 -71 -81 -62 -81 28 0 152 42 210 72 67 34 66 37 22
+-75 -39 -98 -86 -167 -181 -265 l-92 -95 65 6 c37 4 99 21 149 40 l85 35 -6
+-32 c-6 -25 -44 -109 -113 -249 -7 -14 65 20 113 53 147 101 249 270 306 507
+16 69 22 132 26 293 6 236 -6 349 -62 565 -29 115 -112 335 -125 335 -3 0 -18
+-53 -33 -118z"/>
+</g>
+</svg>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-content-space/loopx",
   "type": "module",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Skill-first loopx workflow product for Codex",
   "repository": {
     "type": "git",
@@ -19,8 +19,12 @@
   },
   "files": [
     "README.md",
+    "README.zh-CN.md",
     "package.json",
     "scripts/install-skills.mjs",
+    "scripts/codex-stop-hook.mjs",
+    "scripts/codex-workflow-hook.mjs",
+    "assets/logo.svg",
     "src/",
     "skills/",
     "templates/",

package/plugins/loopx/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "loopx",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Skill-first loopx workflow product for Codex",
   "skills": "./skills/",
   "interface": {

package/plugins/loopx/scripts/plugin-install.test.mjs

@@ -23,6 +23,7 @@ const LOOPX_SKILLS = [
   'plan',
   'build',
   'review',
+  'archive',
   'autopilot',
 ];
 
@@ -82,6 +83,19 @@ describe('loopx plugin shell', () => {
     assert.equal(ralplanSkill.includes('$plan --consensus'), false);
   });
 
+  it('locks clarify handoff to plan instead of direct implementation', async () => {
+    const clarifySkill = await readFile(join(ROOT_SKILLS_DIR, 'clarify', 'SKILL.md'), 'utf8');
+    const pluginClarifySkill = await readFile(join(PLUGIN_SKILLS_DIR, 'clarify', 'SKILL.md'), 'utf8');
+
+    assert.equal(pluginClarifySkill, clarifySkill);
+    assert.match(clarifySkill, /Recommended invocation: `\$plan <slug>`/);
+    assert.doesNotMatch(clarifySkill, /hand off to `build` only/i);
+    assert.doesNotMatch(clarifySkill, /direct execution/i);
+    assert.doesNotMatch(clarifySkill, /direct implementation/i);
+    assert.doesNotMatch(clarifySkill, /directly to implementation/i);
+    assert.doesNotMatch(clarifySkill, /Proceed directly to implementation/i);
+  });
+
   it('reuses the shared install core while materializing skills from the plugin shell', async () => {
     const home = await mkdtemp(join(tmpdir(), 'loopx-plugin-home-'));
     const env = loopxEnv(home);

package/plugins/loopx/skills/archive/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: archive
+description: Sync an approved loopx change delta into long-lived specs after review is done.
+argument-hint: "<workflow slug>"
+---
+
+# loopx Archive
+
+## Purpose
+
+Use `archive` after a loopx workflow has reached `done`. It syncs the accepted change delta into long-lived `.loopx/specs/` files, archives the change staging directory, and writes an advisory ADR candidate.
+
+The accepted delta is requirement-based, not a changelog block. Archive applies:
+
+- `## ADDED Requirements`
+- `## MODIFIED Requirements`
+- `## REMOVED Requirements`
+- `## RENAMED Requirements`
+
+into the current long-lived `## Requirements` state for each target domain.
+
+## Inputs
+
+- `<workflow slug>` for a completed loopx workflow
+
+## Behavior
+
+Run:
+
+```bash
+loopx archive <slug>
+```
+
+Then report in Chinese:
+
+- whether the change was archived
+- which long-lived spec files were updated
+- the archived change path
+- the ADR candidate path, if written
+- any blocker if the workflow is not done, the spec delta is incomplete, or the execution record still declares partial scope
+
+## Boundaries
+
+- Do not run archive before `review -> done` has been approved.
+- Do not archive malformed requirement deltas. ADDED and MODIFIED entries must use `### Requirement:`, SHALL/MUST language, and at least one `#### Scenario:`.
+- Do not archive when `execution-record.md` declares non-empty `remaining_scope`, `completion_claim` other than `full`, or a mismatch between `planned_scope` and `implemented_scope`; route back to build/plan instead.
+- Do not edit implementation code.
+- Do not promote ADR candidates into `docs/adr/` automatically; report the candidate path for human follow-up.
+- Do not treat `loopx status` as a user-facing skill. Use status only as a runtime diagnostic when needed.