@ai-content-space/loopx 0.1.2 → 0.1.3

package/README.zh-CN.md

@@ -0,0 +1,392 @@
+# loopx
+
+[English](./README.md)
+
+`loopx` 是一个面向 Codex 的 skill-first 工作流工具包。它把需求澄清、共识规划、持久执行、独立评审组织成一条可追踪的本地工作流，并通过 CLI 与 Codex Skill 两种方式暴露同一套运行时。
+
+当前公开流程：
+
+```text
+clarify -> plan -> build -> review
+```
+
+评审通过并进入 `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/`，便于审计、恢复和迁移。
+- `plan` 默认采用 Planner -> Architect -> Critic 的共识规划循环。
+- `plan` 会写入借鉴 OpenSpec 的 change artifacts：proposal、spec delta、design、tasks 和 artifact dependency graph。
+- `build` 默认包含执行记录、验证证据、架构验收、deslop 清理和回归再验证。
+- `review` 作为独立验收面，输出中文评审结论和 go/no-go 判断。
+- 支持 `archive`，把已批准的 change delta 同步进长期 `.loopx/specs/` source of truth。
+- 支持从旧 `.codex-helper/` 运行时迁移到 `.loopx/`。
+
+## 安装
+
+### npm 全局安装
+
+```bash
+npm install -g @ai-content-space/loopx
+```
+
+安装后会自动运行：
+
+```bash
+node scripts/install-skills.mjs
+```
+
+该脚本会把 loopx 管理的 skills 安装到：
+
+```text
+~/.agents/skills/
+```
+
+并更新：
+
+```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
+loopx review my-task
+```
+
+把已接受行为归档到长期 specs：
+
+```text
+$archive my-task
+```
+
+查看状态：
+
+```bash
+loopx status my-task
+loopx status my-task --json
+```
+
+也可以让 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 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 暴露。
+
+## 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`
+
+### 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`，执行独立验收和代码评审，并生成：
+
+```text
+.loopx/workflows/<slug>/review-report.md
+```
+
+最终用户可见评审结果要求使用中文。
+
+如果评审通过，仍然需要显式批准 `review -> done`。如果评审要求修实现问题，则运行 `$build --from-review .loopx/workflows/<slug>/review-report.md`。只有当 review 明确指出计划或需求本身错误时，才回到 `$plan <slug>` 或 `$clarify <slug>`。
+
+### archive
+
+`archive` 消费已完成工作流，并把 `.loopx/changes/active/<change-id>/spec-delta.md` 合并进 `.loopx/specs/` 下的长期领域规格。归档后的 change 目录会移动到：
+
+```text
+.loopx/changes/archive/<change-id>/
+```
+
+### 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
+  specs/
+    <domain>/
+      spec.md
+  changes/
+    active/
+      <change-id>/
+        proposal.md
+        spec-delta.md
+        design.md
+        tasks.md
+        artifact-graph.json
+    archive/
+      <change-id>/
+  plans/
+  context/
+  workflows/
+    <slug>/
+      state.json
+      spec.md
+      plan.md
+      architecture.md
+      development-plan.md
+      test-plan.md
+      execution-record.md
+      review-report.md
+      plan-reviews/
+      build-support/
+  autopilot/
+    <slug>/
+      run.json
+```
+
+旧的 `.codex-helper/` 可通过 `loopx migrate` 迁移。`.omx/` 仍保留为外部编排/规划元数据，不属于 loopx 运行时命名空间。
+
+## 安装诊断与修复
+
+检查运行时和 skill 安装状态：
+
+```bash
+loopx doctor
+```
+
+修复 loopx 管理的 skill 安装：
+
+```bash
+loopx repair-install
+```
+
+只检查当前 skill discovery 状态：
+
+```bash
+node scripts/install-skills.mjs --check
+```
+
+## 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`：设置安装来源。
+
+## 开发
+
+安装依赖后运行测试：
+
+```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`
+- `src/`
+- `skills/`，包含公开 loopx skills 以及随包发布的兼容/内部 skill 源文件
+- `templates/`
+- `plugins/loopx/`
+
+## 版本
+
+当前 npm 包版本：`0.1.2`。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-content-space/loopx",
   "type": "module",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Skill-first loopx workflow product for Codex",
   "repository": {
     "type": "git",
@@ -19,8 +19,11 @@
   },
   "files": [
     "README.md",
+    "README.zh-CN.md",
     "package.json",
     "scripts/install-skills.mjs",
+    "scripts/codex-stop-hook.mjs",
+    "scripts/codex-workflow-hook.mjs",
     "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',
 ];
 

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

@@ -0,0 +1,39 @@
+---
+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.
+
+## 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 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.

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

@@ -1,7 +1,7 @@
 ---
 name: build
 description: Ralph-style loopx execution runtime under the public build stage.
-argument-hint: "[--no-deslop] <approved workflow slug>"
+argument-hint: "[--no-deslop] <approved PRD path or workflow slug> | --from-review <review artifact path>"
 ---
 
 # loopx Build
@@ -14,6 +14,7 @@ By default, `build` is not a one-shot draft writer. It is a persistence loop wit
 
 <Use_When>
 - `plan -> build` has already been explicitly approved.
+- `review -> build` was requested for implementation fixes and a review artifact is supplied with `--from-review`.
 - Canonical plan artifacts already exist and execution should now proceed.
 - The task needs execution persistence, verification evidence, and explicit pre-review quality gates.
 </Use_When>
@@ -29,34 +30,97 @@ By default, `build` is not a one-shot draft writer. It is a persistence loop wit
 - Execution may parallelize internally without exposing a public `team` stage.
 - `build` does not replace `review`.
 - `execution-record.md` remains the sole canonical execution and verification artifact.
+- Feature work and bug fixes should use `tdd`: write a failing test, confirm it fails for the intended reason, then implement the smallest passing change.
+- Bug, test-failure, build-failure, and unexpected-behavior work should use `debug` before proposing fixes.
+- Completion and review-ready claims should use `verify` before they are stated.
+- Go edits should use `go-style` and preserve local repository conventions.
+- Go-Kratos work should use `kratos` when Kratos project signals or Kratos-specific tasks are present.
 - Fresh evidence is required before review handoff.
 - Deslop and regression re-verification are part of the default build path.
+- `build` has one owner for persistence. Delegation may run in parallel, but the owner remains accountable for draining delegated work and proving completion before review handoff.
 </Core_Principles>
 
 <Preconditions>
-`build` starts only when all of the following are true:
+For initial execution, `build` starts only when all of the following are true:
 
 - approved `plan -> build` transition exists
 - `.loopx/plans/prd-<slug>.md` exists
 - `.loopx/plans/test-spec-<slug>.md` exists
 - workflow-local planning artifacts required by the execution lane exist
+
+For review-requested implementation fixes, `build` may instead start from:
+
+- `$build --from-review .loopx/workflows/<slug>/review-report.md`
+- or `$build --from-review .loopx/workflows/<slug>/review.md`
+
+In that mode, the review artifact is the direct rework contract. The approved PRD, test spec, previous execution record, and workflow-local plan package remain required context, but they are not the primary user-facing argument.
 </Preconditions>
 
+<Inputs>
+Preferred skill input:
+
+- `.loopx/plans/prd-<slug>.md`
+
+Preferred review rework input:
+
+- `--from-review .loopx/workflows/<slug>/review-report.md`
+
+Compatible skill / CLI input:
+
+- `<slug>`
+
+When invoked with a PRD path, derive `<slug>` from `prd-<slug>.md` and still use the matching workflow-local plan package and test spec.
+
+When invoked with `--from-review`, derive `<slug>` from the workflow directory, treat the review artifact as the implementation-fix contract, and load the matching PRD, test spec, previous `execution-record.md`, and workflow-local plan package as supporting context. This Codex skill invocation consumes the `review -> build` rework intent; users should not need a separate bash `loopx approve ... --from review --to build` step for the normal Codex-facing flow.
+</Inputs>
+
 <Execution_Model>
 `build` should behave like a Ralph-style execution runtime:
 
 1. Initialize or resume build iteration state.
-2. Run internal execution / evidence / verification lanes in parallel.
-3. Aggregate lane results into canonical `execution-record.md`.
-4. Run fresh verification and read actual output.
-5. Run architect verification as a hard pre-review gate.
-6. Run deslop on build-owned changes.
-7. Re-run regression verification after deslop.
-8. Stop only when review handoff gates are satisfied or a real blocker remains.
+2. If running from `--from-review`, load the review artifact first and constrain implementation work to the requested implementation fixes unless the review artifact exposes a real plan or clarify blocker.
+3. Run internal execution / evidence / verification lanes in parallel.
+4. For implementation work, apply `tdd` unless the approved plan explicitly classifies the change as non-behavioral or test-inapplicable.
+5. For failures discovered during execution or verification, apply `debug` before attempting fixes.
+6. For `.go` edits, apply `go-style`; for Kratos API/service/biz/data work, apply `kratos` before changing framework structure.
+7. Aggregate lane results into canonical `execution-record.md`.
+8. Run fresh verification and read actual output using `verify` discipline.
+9. Run architect verification as a hard pre-review gate.
+10. Run deslop on build-owned changes.
+11. Re-run regression verification after deslop.
+12. Write/update the build delegation ledger and ensure blocking delegated work is drained.
+13. Write/update the completion audit mapping approved plan, slices, and review rework inputs to evidence.
+14. Stop only when review handoff gates are satisfied or a real blocker remains.
 
 `build` may persist support artifacts for runtime inspection, but they must not replace `execution-record.md`.
 </Execution_Model>
 
+<Continuation_Discipline>
+`build` is a persistence loop, not a "one phase per invocation" runner.
+
+If approved plan work remains, continue executing within the same `$build` invocation until either review handoff gates are satisfied or a real blocker prevents further progress.
+
+The following are **not** real blockers by themselves:
+
+- a planned phase is unfinished
+- a runtime adapter is not fully migrated yet
+- store-layer branches still need to be moved to the new service/client path
+- more files remain in the approved implementation scope
+- verification has not been rerun after the latest edits
+
+Those are remaining execution work. Keep working them down.
+
+A real blocker must identify why execution cannot safely continue now, such as:
+
+- missing human product/architecture decision that is not specified by the approved plan
+- unavailable credential, service, fixture, dependency, or environment that cannot be mocked or bypassed responsibly
+- verification failure caused by a pre-existing repository condition that blocks evaluating this change and cannot be isolated
+- repeated implementation failure after the build iteration budget is exhausted
+- a conflict between the approved plan and current repository facts that requires re-planning
+
+Do not end a build response with "continue in the next build" for unfinished approved work. If work remains and no real blocker exists, keep executing. If a real blocker exists, name the concrete blocker and record it in `execution-record.md`.
+</Continuation_Discipline>
+
 <Runtime_State_Machine>
 `build` should track at minimum:
 
@@ -72,6 +136,14 @@ By default, `build` is not a one-shot draft writer. It is a persistence loop wit
 - `build_blockers`
 - `build_progress_artifact_paths`
 - `build_support_evidence_paths`
+- `build_owner_id`
+- `build_owner_session_id`
+- `build_owner_status`
+- `build_delegation_status`
+- `build_delegation_ledger_path`
+- `build_active_delegation_count`
+- `build_completion_audit_status`
+- `build_completion_audit_path`
 - `execution_record_status`
 
 `build -> review` is blocked until:
@@ -81,6 +153,8 @@ By default, `build` is not a one-shot draft writer. It is a persistence loop wit
 - architect verification is approved
 - deslop is complete, unless explicitly skipped
 - post-deslop regression passes
+- blocking delegated build work is drained
+- completion audit passes
 - `execution-record.md` is complete
 </Runtime_State_Machine>
 
@@ -89,6 +163,15 @@ Canonical artifact:
 
 - `execution-record.md`
 
+`execution-record.md` must make the completion scope explicit when a plan is larger than the current implementation slice:
+
+- `planned_scope`: the approved PRD/workflow scope being measured.
+- `implemented_scope`: the scope actually completed in this build run.
+- `remaining_scope`: empty only when the approved workflow scope is fully implemented.
+- `completion_claim`: use `full` only when the whole approved workflow is complete; use `slice` or another non-full value for partial implementation.
+
+If `remaining_scope` is non-empty or `completion_claim` is not `full`, build may still hand off for slice review, but review/archive must not treat that as full workflow completion.
+
 Support artifacts may exist for:
 
 - iteration progress
@@ -96,6 +179,8 @@ Support artifacts may exist for:
 - architect gate summaries
 - deslop summaries
 - regression summaries
+- `build-support/delegation-ledger.json`
+- `build-support/completion-audit.json`
 
 These support artifacts are runtime aids only. They must not become new canonical review inputs.
 </Artifact_Contract>
@@ -106,6 +191,23 @@ These support artifacts are runtime aids only. They must not become new canonica
 - review continues to own provenance checks, evidence completeness checks, completion/rollback decisions, and code-review
 </Review_Boundary>
 
+<Final_Response_Contract>
+When `build` reaches review handoff readiness, the final response must include an explicit next skill command using the execution record path:
+
+```text
+Next:
+$review .loopx/workflows/<slug>/execution-record.md
+```
+
+If the user needs the CLI/runtime-debug form, use:
+
+```bash
+loopx review <slug>
+```
+
+Do not end with prose-only guidance such as "next step should enter review" when the workflow is ready for review. Do not emit `$review <slug>` as the primary skill handoff when the execution record path is known. If review handoff is blocked, state the blocker instead of emitting a `$review` command.
+</Final_Response_Contract>
+
 <Flags>
 - `--no-deslop`: skip the deslop pass and the post-deslop regression loop, while still requiring the latest successful pre-deslop verification evidence
 </Flags>