@ai-content-space/loopx 0.1.3 → 0.1.5

package/README.md

@@ -1,4 +1,12 @@
-# loopx
+<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">
+  Skill-first workflow runtime for Codex.
+</p>
 
 [中文文档](./README.zh-CN.md)
 
@@ -17,15 +25,18 @@ clarify -> plan -> build -> review -> approve review->done -> archive
 ## Features
 
 - Installs and exposes eleven bundled loopx Codex skills: workflow skills `clarify`, `plan`, `build`, `review`, `archive`, and `autopilot`; quality support skills `debug`, `tdd`, and `verify`; and Go support skills `go-style` and `kratos`.
+- Keeps bundled skill routing explicit in `skills/RESOLVER.md`, with deterministic governance checks for frontmatter, plugin mirrors, resolver coverage, local references, package inclusion, and version alignment.
 - Supports npm global install and Codex plugin install through the same install/discovery core.
+- Installs a managed Codex workflow hook that surfaces loopx workflow state and safe next-action hints inside Codex.
 - Stores runtime state and stage artifacts locally under `.loopx/` for auditability, recovery, and migration.
+- Stores clarify intake snapshots under `.loopx/intake/` so `.loopx/specs/` stays reserved for long-lived domain specs.
+- Records existing project AI rule files, existing spec sources, and detected verification commands in `.loopx/config.json` during init so loopx can preserve local sources of truth while still running the full workflow.
 - Runs `plan` with a Planner -> Architect -> Critic consensus loop by default.
 - Writes OpenSpec-inspired change artifacts during `plan`: proposal, spec delta, design, vertical slices, tasks, and an artifact dependency graph.
 - Provides per-repo agent context under `.loopx/agents/` and `.loopx/context/domain.md`, consumed by build/review context manifests.
 - Runs `build` with execution records, verification evidence, architect validation, deslop cleanup, and regression re-verification.
 - Keeps `review` as an independent acceptance surface with code review plus an internal architecture-smell lane.
 - Supports `archive` to sync approved change deltas into long-lived `.loopx/specs/` source-of-truth files and emit ADR candidates.
-- Supports migration from the legacy `.codex-helper/` runtime namespace to `.loopx/`.
 
 ## Installation
 
@@ -47,6 +58,12 @@ The script materializes loopx-owned skills under:
 ~/.agents/skills/
 ```
 
+It also installs the loopx-managed Codex workflow hook at:
+
+```text
+~/.codex/hooks/codex-workflow-hook.mjs
+```
+
 and updates:
 
 ```text
@@ -108,7 +125,6 @@ Complete an approved review:
 
 ```bash
 loopx approve my-task --from review --to done
-loopx review my-task
 ```
 
 Archive accepted behavior into long-lived specs:
@@ -124,6 +140,12 @@ loopx status my-task
 loopx status my-task --json
 ```
 
+Render derived HTML reading views:
+
+```bash
+loopx render my-task
+```
+
 You can also create a planning workflow directly from an existing spec:
 
 ```bash
@@ -142,6 +164,7 @@ 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
@@ -151,7 +174,25 @@ loopx repair-install
 
 The CLI is primarily for runtime, debugging, status inspection, and maintenance. The normal Codex-facing product surface is the bundled skill set, for example `$clarify`, `$plan`, `$build`, `$review`, `$archive`, `$autopilot`, `$debug`, `$tdd`, `$verify`, `$go-style`, and `$kratos`.
 
-`loopx status` remains a CLI/runtime diagnostic command rather than a Codex skill.
+`loopx status` remains a CLI/runtime diagnostic command rather than a Codex skill. `loopx render` generates human-readable HTML views from existing runtime artifacts; without a slug it renders every non-legacy workflow plus the workspace index. Markdown and JSON remain the canonical machine-readable and editable sources.
+
+## Skill Routing and Governance
+
+The bundled skill resolver lives at:
+
+```text
+skills/RESOLVER.md
+```
+
+It is the human-readable routing map for the eleven bundled skills. Keep it aligned with each `skills/<name>/SKILL.md` and mirrored `plugins/loopx/skills/<name>/SKILL.md`.
+
+Skill governance is enforced by:
+
+```bash
+node scripts/verify-skills.mjs
+```
+
+The verifier checks that bundled skill frontmatter is triggerable and bounded, `metadata.version` matches `package.json`, plugin skill mirrors match the canonical skills, `skills/RESOLVER.md` covers every bundled skill without stale bundled-skill references, local skill references exist, the plugin manifest version matches the package version, and the verifier itself is included in the npm package.
 
 ## Skills
 
@@ -183,6 +224,8 @@ Main artifacts:
 - `.loopx/workflows/<slug>/development-plan.md`
 - `.loopx/workflows/<slug>/test-plan.md`
 
+`spec-delta.md` uses requirement deltas: `## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements`, and `## RENAMED Requirements`. ADDED and MODIFIED entries are full `### Requirement:` blocks with SHALL/MUST language and `#### Scenario:` examples, so archive can merge them into the current long-lived spec state.
+
 ### build
 
 `build` executes an approved plan and records changes, evidence, and limitations in the canonical artifact:
@@ -229,6 +272,8 @@ The architecture-smell lane is part of review; it does not add a new stage. It r
 
 Archive also writes an advisory ADR candidate under `.loopx/decisions/adr-candidates/<change-id>.md`. It is not promoted to `docs/adr/` automatically.
 
+Archive applies requirement deltas semantically instead of appending per-change history blocks. ADDED creates requirements, MODIFIED replaces a full existing requirement block, REMOVED deletes a requirement, and RENAMED changes the requirement title while preserving its body.
+
 ### autopilot
 
 `autopilot` is the end-to-end orchestration entrypoint. It may run internal phases such as expansion, planning, execution, QA, and validation, but canonical artifacts still come from the public `clarify -> plan -> build -> review` flow.
@@ -267,6 +312,10 @@ loopx writes runtime state under `.loopx/` in the current project:
 .loopx/
   README.md
   config.json
+  intake/
+    clarify-<slug>-<timestamp>.md
+  views/
+    index.html
   specs/
     <domain>/
       spec.md
@@ -300,14 +349,52 @@ loopx writes runtime state under `.loopx/` in the current project:
       test-plan.md
       execution-record.md
       review-report.md
+      view/
+        index.html
+        intake.html
+        plan.html
+        build.html
+        review.html
       plan-reviews/
       build-support/
+      review-support/
   autopilot/
     <slug>/
       run.json
 ```
 
-Legacy `.codex-helper/` state can be migrated with `loopx migrate`. The `.omx/` tree remains external orchestration/planning metadata and is not part of the loopx runtime namespace.
+`config.json` records the loopx product contract plus init-time project discovery: existing AI rules such as `AGENTS.md` / `CLAUDE.md` / Cursor / Copilot files, existing spec sources such as `docs/changes` or ADR/RFC folders, and detected install/test/lint/typecheck/build/E2E commands. This does not create a lighter loopx mode; it keeps project facts available to `plan`, `build`, and `review` while preserving loopx's full closed workflow.
+
+`intake` contains immutable clarify snapshots for a specific request. `workflows` contains the active runtime working set. `changes` contains the proposed change delta for the current request. `specs` contains accepted long-lived behavior after archive.
+
+`views/` and `workflows/<slug>/view/` are derived HTML reading views generated by `loopx render`. They are for human review only and are safe to regenerate; agents and tooling should continue to read and update the Markdown and JSON artifacts.
+
+### Document Boundaries
+
+Documents users normally need to watch:
+
+- `README.md` / `README.zh-CN.md`: product usage, commands, and runtime layout.
+- `.loopx/workflows/<slug>/spec.md`: the current requirement working copy.
+- `.loopx/workflows/<slug>/plan.md`, `architecture.md`, `development-plan.md`, and `test-plan.md`: the current task's plan, architecture, execution, and verification contract.
+- `.loopx/workflows/<slug>/execution-record.md` and `review-report.md`: execution evidence and review result.
+- `.loopx/views/index.html` and `.loopx/workflows/<slug>/view/index.html`: reading entrypoints generated by `loopx render`.
+
+Documents users may read and modify as workflow fact sources:
+
+- `.loopx/workflows/<slug>/*.md`: editable working-copy artifacts for the active workflow; changes still need to pass the relevant stage gates.
+- `.loopx/config.json`: workspace configuration, project-rule/spec-source discovery, and default verification commands; update it if the repository's canonical commands or project-rule files change.
+- `.loopx/context/domain.md` and `.loopx/agents/*.md`: project context, domain vocabulary, and agent collaboration guidance.
+- `.loopx/changes/active/<change-id>/*.md`: plan-generated change proposal, design, tasks, and spec delta; edits should be followed by plan/build/review validation.
+- `.loopx/specs/<domain>/spec.md`: long-lived archived behavior specs; normally synced by `archive`, and manual edits should stay consistent with later change deltas.
+
+Documents and data the tools depend on, or generate as derived evidence:
+
+- `.loopx/workflows/<slug>/state.json`, `build-context.jsonl`, and `review-context.jsonl`: runtime state and context manifests; tools depend on these and manual edits are discouraged.
+- `.loopx/workflows/<slug>/plan-reviews/`, `build-support/`, and `review-support/`: stage evidence and internal review outputs for diagnostics and review.
+- `.loopx/intake/clarify-*.md`: immutable clarify snapshots for audit and traceability; do not treat them as long-lived specs.
+- `.loopx/changes/active/<change-id>/slices.json` and `artifact-graph.json`: structured planning data consumed by build/review/archive.
+- `.loopx/autopilot/<slug>/run.json` and `.loopx/build-active.json`: orchestration and stop-hook runtime state.
+- `.loopx/views/` and `.loopx/workflows/<slug>/view/`: derived HTML views; they can be deleted and regenerated with `loopx render`, and should not be edited as fact sources.
 
 ## Diagnostics and Repair
 
@@ -329,6 +416,24 @@ Check skill discovery state only:
 node scripts/install-skills.mjs --check
 ```
 
+Verify bundled skill governance:
+
+```bash
+node scripts/verify-skills.mjs
+```
+
+## Codex Workflow Hook
+
+`install-skills.mjs` and the Codex plugin installer automatically install `scripts/codex-workflow-hook.mjs` to:
+
+```text
+~/.codex/hooks/codex-workflow-hook.mjs
+```
+
+The hook reads the nearest `.loopx/workflows/<slug>/state.json` and emits advisory context for the active workflow: current stage, blockers, readiness, authorization, evidence, and the next safe loopx action. It is advisory only; runtime gates remain authoritative.
+
+Set `LOOPX_HOOKS=0` to disable the workflow hook output.
+
 ## Codex Stop Hook
 
 loopx includes a Codex stop-hook helper that prevents an active build from stopping before review handoff readiness:
@@ -358,6 +463,7 @@ Install and discovery logic supports these environment variables:
 - `LOOPX_DISTRIBUTION_CHANNEL`: set the install channel, default `npm`.
 - `LOOPX_INSTALLATION_IDENTITY`: set the install identity, default `loopx`.
 - `LOOPX_SOURCE_URL`: set the install source.
+- `LOOPX_HOOKS`: set to `0` to disable workflow hook output.
 
 ## Development
 
@@ -367,9 +473,17 @@ Run tests:
 npm test
 ```
 
+`npm test` runs bundled skill governance first, then the Node test suites:
+
+```bash
+node scripts/verify-skills.mjs
+node --test test/*.test.mjs
+```
+
 Useful verification commands:
 
 ```bash
+node scripts/verify-skills.mjs
 node --test test/*.test.mjs
 node scripts/install-skills.mjs --check
 node --test plugins/loopx/scripts/plugin-install.test.mjs
@@ -386,7 +500,10 @@ node src/cli.mjs status --json
 - `README.zh-CN.md`
 - `package.json`
 - `scripts/install-skills.mjs`
+- `scripts/verify-skills.mjs`
 - `scripts/codex-stop-hook.mjs`
+- `scripts/codex-workflow-hook.mjs`
+- `assets/logo.svg`
 - `src/`
 - `skills/`, including public loopx skills plus compatibility/internal skill sources shipped with the package
 - `templates/`
@@ -394,4 +511,4 @@ node src/cli.mjs status --json
 
 ## Version
 
-Current npm package version: `0.1.2`.
+Current npm package version: `0.1.4`.

package/README.zh-CN.md

@@ -1,4 +1,12 @@
-# loopx
+<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)
 
@@ -7,9 +15,11 @@
 当前公开流程：
 
 ```text
-clarify -> plan -> build -> review
+clarify -> plan -> build -> review -> approve review->done -> archive
 ```
 
+`done` 是通过 `loopx approve <slug> --from review --to done` 进入的运行时完成状态，不是单独的 Codex skill。
+
 评审通过并进入 `done` 后，可以执行 archive，把本次被接受的 change delta 合并到长期 specs。
 
 其中 `autopilot` 是端到端编排入口，会在内部复用这套公开阶段，而不是引入另一套流程真相。
@@ -17,14 +27,18 @@ clarify -> plan -> build -> review
 ## 特性
 
 - 安装并公开 11 个 loopx Codex skills：工作流 skills `clarify`、`plan`、`build`、`review`、`archive`、`autopilot`，质量辅助 skills `debug`、`tdd`、`verify`，以及 Go 支持 skills `go-style`、`kratos`。
+- 通过 `skills/RESOLVER.md` 明确 bundled skill 路由，并用确定性治理脚本检查 frontmatter、plugin 镜像、resolver 覆盖、本地引用、发布包包含项和版本一致性。
 - 支持 npm 全局安装和 Codex plugin 安装，两种安装方式共享同一套 install/discovery 逻辑。
+- 自动安装 loopx 管理的 Codex workflow hook，在 Codex 中提示当前 workflow 状态和安全下一步。
 - 所有运行时状态和阶段产物都写入项目本地 `.loopx/`，便于审计、恢复和迁移。
+- clarify 需求快照写入 `.loopx/intake/`，让 `.loopx/specs/` 只承载长期领域规格。
+- init 时会把已有项目 AI 规则、既有 spec 来源和自动发现的验证命令记录到 `.loopx/config.json`，让 loopx 保留项目原有事实源，同时继续执行完整闭环。
 - `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` 作为独立验收面，输出中文评审结论和 go/no-go 判断。
-- 支持 `archive`，把已批准的 change delta 同步进长期 `.loopx/specs/` source of truth。
-- 支持从旧 `.codex-helper/` 运行时迁移到 `.loopx/`。
+- `review` 作为独立验收面，包含代码审查和内部 architecture-smell lane，并输出中文评审结论和 go/no-go 判断。
+- 支持 `archive`，把已批准的 change delta 同步进长期 `.loopx/specs/` source of truth，并生成 ADR candidate。
 
 ## 安装
 
@@ -46,6 +60,12 @@ node scripts/install-skills.mjs
 ~/.agents/skills/
 ```
 
+同时也会把 loopx 管理的 Codex workflow hook 安装到：
+
+```text
+~/.codex/hooks/codex-workflow-hook.mjs
+```
+
 并更新：
 
 ```text
@@ -107,7 +127,6 @@ loopx review my-task
 
 ```bash
 loopx approve my-task --from review --to done
-loopx review my-task
 ```
 
 把已接受行为归档到长期 specs：
@@ -123,6 +142,12 @@ loopx status my-task
 loopx status my-task --json
 ```
 
+生成派生 HTML 阅读视图：
+
+```bash
+loopx render my-task
+```
+
 也可以让 loopx 根据一个现成 spec 直接创建规划工作流：
 
 ```bash
@@ -141,6 +166,7 @@ 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
@@ -150,7 +176,25 @@ 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 status` 仍然是 CLI/runtime 诊断命令，不作为单独 Codex skill 暴露。`loopx render` 会基于现有运行时产物生成给人阅读的 HTML 视图；不传 slug 时会渲染所有非 legacy workflow 和工作区首页。Markdown 和 JSON 仍然是机器可读、可编辑的事实源。
+
+## Skill 路由与治理
+
+bundled skill resolver 位于：
+
+```text
+skills/RESOLVER.md
+```
+
+它是 11 个 bundled skills 的可读路由表。修改任一 `skills/<name>/SKILL.md` 或镜像的 `plugins/loopx/skills/<name>/SKILL.md` 时，都要保持 resolver 同步。
+
+skill 治理由下面的确定性脚本执行：
+
+```bash
+node scripts/verify-skills.mjs
+```
+
+该脚本会检查 bundled skill frontmatter 是否可触发且有排除边界、`metadata.version` 是否匹配 `package.json`、plugin skill 镜像是否与 canonical skills 一致、`skills/RESOLVER.md` 是否覆盖所有 bundled skills 且没有陈旧 bundled-skill 引用、本地 skill 引用是否存在、plugin manifest 版本是否匹配 package 版本，以及 verifier 本身是否进入 npm 发布包。
 
 ## Skill 说明
 
@@ -175,12 +219,15 @@ CLI 主要用于运行时、调试、状态观察和维护。日常面向 Codex
 - `.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>/slices.json`
 - `.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：
@@ -214,7 +261,7 @@ $build --from-review .loopx/workflows/<slug>/review-report.md
 
 ### review
 
-`review` 消费 build 输出的 `execution-record.md`，执行独立验收和代码评审，并生成：
+`review` 消费 build 输出的 `execution-record.md`，执行独立验收、代码评审和轻量 architecture-smell lane，并生成：
 
 ```text
 .loopx/workflows/<slug>/review-report.md
@@ -224,6 +271,8 @@ $build --from-review .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 目录会移动到：
@@ -232,6 +281,10 @@ $build --from-review .loopx/workflows/<slug>/review-report.md
 .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` 流程。
@@ -270,6 +323,10 @@ loopx 在当前项目下写入 `.loopx/`：
 .loopx/
   README.md
   config.json
+  intake/
+    clarify-<slug>-<timestamp>.md
+  views/
+    index.html
   specs/
     <domain>/
       spec.md
@@ -280,11 +337,19 @@ loopx 在当前项目下写入 `.loopx/`：
         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
@@ -295,14 +360,52 @@ loopx 在当前项目下写入 `.loopx/`：
       test-plan.md
       execution-record.md
       review-report.md
+      view/
+        index.html
+        intake.html
+        plan.html
+        build.html
+        review.html
       plan-reviews/
       build-support/
+      review-support/
   autopilot/
     <slug>/
       run.json
 ```
 
-旧的 `.codex-helper/` 可通过 `loopx migrate` 迁移。`.omx/` 仍保留为外部编排/规划元数据，不属于 loopx 运行时命名空间。
+`config.json` 记录 loopx 产品契约和 init 时的项目发现结果：已有 AI 规则文件，例如 `AGENTS.md`、`CLAUDE.md`、Cursor / Copilot 规则；已有 spec 来源，例如 `docs/changes`、ADR/RFC 目录；以及自动发现的 install/test/lint/typecheck/build/E2E 命令。这不会引入轻量版 loopx；它只是让 `plan`、`build`、`review` 能看到项目事实，同时保持完整闭环。
+
+`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/config.json`：workspace 配置、项目规则/spec 来源发现结果和默认验证命令；当仓库的 canonical 命令或规则文件变化时可以更新。
+- `.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` 重新生成，不应作为事实源编辑。
 
 ## 安装诊断与修复
 
@@ -324,6 +427,24 @@ loopx repair-install
 node scripts/install-skills.mjs --check
 ```
 
+检查 bundled skill 治理状态：
+
+```bash
+node scripts/verify-skills.mjs
+```
+
+## 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 之前提前停止：
@@ -353,6 +474,7 @@ node scripts/codex-stop-hook.mjs
 - `LOOPX_DISTRIBUTION_CHANNEL`：设置安装渠道，默认 `npm`。
 - `LOOPX_INSTALLATION_IDENTITY`：设置安装身份，默认 `loopx`。
 - `LOOPX_SOURCE_URL`：设置安装来源。
+- `LOOPX_HOOKS`：设置为 `0` 时关闭 workflow hook 输出。
 
 ## 开发
 
@@ -362,9 +484,17 @@ node scripts/codex-stop-hook.mjs
 npm test
 ```
 
+`npm test` 会先运行 bundled skill 治理检查，再运行 Node 测试套件：
+
+```bash
+node scripts/verify-skills.mjs
+node --test test/*.test.mjs
+```
+
 也可以直接执行项目内的验证命令：
 
 ```bash
+node scripts/verify-skills.mjs
 node --test test/*.test.mjs
 node scripts/install-skills.mjs --check
 node --test plugins/loopx/scripts/plugin-install.test.mjs
@@ -381,7 +511,10 @@ node src/cli.mjs status --json
 - `README.zh-CN.md`
 - `package.json`
 - `scripts/install-skills.mjs`
+- `scripts/verify-skills.mjs`
 - `scripts/codex-stop-hook.mjs`
+- `scripts/codex-workflow-hook.mjs`
+- `assets/logo.svg`
 - `src/`
 - `skills/`，包含公开 loopx skills 以及随包发布的兼容/内部 skill 源文件
 - `templates/`
@@ -389,4 +522,4 @@ node src/cli.mjs status --json
 
 ## 版本
 
-当前 npm 包版本：`0.1.2`。
+当前 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>