@ai-content-space/loopx 0.1.4 → 0.1.5

package/README.md

@@ -25,10 +25,12 @@ 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.
@@ -174,6 +176,24 @@ The CLI is primarily for runtime, debugging, status inspection, and maintenance.
 
 `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
 
 ### clarify
@@ -337,11 +357,14 @@ loopx writes runtime state under `.loopx/` in the current project:
         review.html
       plan-reviews/
       build-support/
+      review-support/
   autopilot/
     <slug>/
       run.json
 ```
 
+`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.
@@ -359,6 +382,7 @@ Documents users normally need to watch:
 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.
@@ -392,6 +416,12 @@ 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:
@@ -443,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
@@ -462,6 +500,7 @@ 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`

package/README.zh-CN.md

@@ -27,10 +27,12 @@ clarify -> plan -> build -> review -> approve review->done -> archive
 ## 特性
 
 - 安装并公开 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 消费。
@@ -176,6 +178,24 @@ CLI 主要用于运行时、调试、状态观察和维护。日常面向 Codex
 
 `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 说明
 
 ### clarify
@@ -199,6 +219,7 @@ 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`
@@ -347,11 +368,14 @@ loopx 在当前项目下写入 `.loopx/`：
         review.html
       plan-reviews/
       build-support/
+      review-support/
   autopilot/
     <slug>/
       run.json
 ```
 
+`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 产物。
@@ -369,6 +393,7 @@ loopx 在当前项目下写入 `.loopx/`：
 用户可以阅读和按流程修改的事实源文档：
 
 - `.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 一致。
@@ -402,6 +427,12 @@ 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` 安装到：
@@ -453,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
@@ -472,6 +511,7 @@ 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`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-content-space/loopx",
   "type": "module",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Skill-first loopx workflow product for Codex",
   "repository": {
     "type": "git",
@@ -22,6 +22,7 @@
     "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",
@@ -35,6 +36,6 @@
   },
   "scripts": {
     "postinstall": "node scripts/install-skills.mjs",
-    "test": "node --test test/*.test.mjs"
+    "test": "node scripts/verify-skills.mjs && node --test test/*.test.mjs"
   }
 }

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

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

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

@@ -1,6 +1,9 @@
 ---
 name: archive
-description: Sync an approved loopx change delta into long-lived specs after review is done.
+description: "Archives an approved loopx change delta into long-lived specs and writes an ADR candidate after done approval. Not for active builds or unapproved reviews."
+when_to_use: "archive, done workflow, spec delta, long-lived specs, ADR candidate, review approved, 归档, 同步规格"
+metadata:
+  version: "0.1.5"
 argument-hint: "<workflow slug>"
 ---
 

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

@@ -1,6 +1,9 @@
 ---
 name: autopilot
-description: Richer internal-phase loopx autonomous orchestration over the public clarify/plan/build/review flow.
+description: "Runs one bounded autonomous loopx orchestration over clarify, plan, build, and review while preserving canonical artifacts. Not for manual gate-by-gate control."
+when_to_use: "autopilot, autonomous loopx run, end-to-end workflow, run all stages, bounded orchestration, 自动执行, 全流程"
+metadata:
+  version: "0.1.5"
 argument-hint: "<workflow slug>"
 ---
 

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

@@ -1,6 +1,9 @@
 ---
 name: build
-description: Ralph-style loopx execution runtime under the public build stage.
+description: "Executes an approved loopx plan or review rework contract with evidence, verification, deslop, and regression gates. Not for unclear requirements or independent review."
+when_to_use: "build, implement approved plan, execute PRD, --from-review, review rework, implementation fixes, 执行, 实现, 修改"
+metadata:
+  version: "0.1.5"
 argument-hint: "[--no-deslop] <approved PRD path or workflow slug> | --from-review <review artifact path>"
 ---
 
@@ -30,6 +33,7 @@ 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.
+- `.loopx/config.json` is supporting context for existing project AI rules, existing spec sources, and discovered verification commands; use it to preserve local sources of truth, not to skip loopx stages.
 - 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.
@@ -72,6 +76,8 @@ Compatible skill / CLI input:
 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.
+
+Also load `.loopx/config.json` when present. Its `project_conventions` entries identify existing project rule/spec files that should be preserved, and its `verification_commands` entries are the first project-native commands to consider for fresh evidence.
 </Inputs>
 
 <Execution_Model>

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

@@ -1,6 +1,9 @@
 ---
 name: clarify
-description: Comprehensive loopx clarify skill for requirements, boundaries, and design-ready specs.
+description: "Clarifies ambiguous loopx work into requirements, non-goals, decision boundaries, and design-ready specs before planning. Not for already-approved plans or concrete implementation tasks."
+when_to_use: "clarify, requirements, ambiguous request, unclear scope, non-goals, decision boundaries, acceptance criteria, 需求澄清, 范围不清"
+metadata:
+  version: "0.1.5"
 ---
 
 # loopx Clarify

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

@@ -1,6 +1,9 @@
 ---
 name: debug
-description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+description: "Finds root cause for bugs, failing tests, build failures, regressions, and unexpected behavior before fixes. Not for new feature planning or routine code review."
+when_to_use: "debug, bug, test failure, build failure, regression, unexpected behavior, root cause, 报错, 失败, 回归, 排查"
+metadata:
+  version: "0.1.5"
 ---
 
 # Systematic Debugging

package/plugins/loopx/skills/go-style/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: go-style
-description: Go language style support for loopx. Use before creating or editing Go (.go) files, especially inside build execution lanes.
+description: "Applies loopx Go coding style for .go edits, tests, errors, context, naming, and interface boundaries. Not for non-Go code or Kratos-specific architecture by itself."
+when_to_use: "go-style, Go, golang, .go files, go tests, gofmt, idiomatic Go, Go style, Go 代码"
+metadata:
+  version: "0.1.5"
 ---
 
 # Go Style

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

@@ -1,6 +1,9 @@
 ---
 name: kratos
-description: Go-Kratos framework support for loopx. Use for Kratos microservices, proto/buf API work, service/biz/data layering, Kratos middleware, auth, configuration, and troubleshooting.
+description: "Supports Go-Kratos microservices, proto/buf APIs, service/biz/data layers, middleware, auth, config, and troubleshooting. Not for generic Go style alone."
+when_to_use: "kratos, Go-Kratos, proto, buf, service layer, biz layer, data layer, middleware, auth, config, Kratos 微服务"
+metadata:
+  version: "0.1.5"
 ---
 
 # Kratos

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

@@ -1,6 +1,9 @@
 ---
 name: plan
-description: Consensus-first loopx planning skill with Planner, Architect, and Critic review.
+description: "Creates a consensus-first loopx plan package with Planner, Architect, and Critic review from an approved spec. Not for unresolved requirements or direct implementation."
+when_to_use: "plan, planning, consensus planning, PRD, architecture plan, test plan, approved clarify spec, 规划, 方案, 架构评审"
+metadata:
+  version: "0.1.5"
 argument-hint: "[--interactive] [--deliberate] [--direct <spec-path>] <clarified task or spec path>"
 ---
 

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

@@ -1,6 +1,9 @@
 ---
 name: review
-description: Repo-local acceptance surface for loopx.
+description: "Reviews a loopx build execution record for acceptance, code risks, evidence quality, and architecture smells. Not for doing implementation work or replanning."
+when_to_use: "review, code review, acceptance, go no-go, execution-record, architecture smell, build complete, 审查, 验收"
+metadata:
+  version: "0.1.5"
 argument-hint: "<execution-record path or workflow slug>"
 ---
 
@@ -22,6 +25,8 @@ Compatible skill / CLI input:
 
 When invoked with an execution record path, derive `<slug>` from the workflow directory and evaluate the matching active run.
 
+When present, use `.loopx/config.json` as supporting context for project-native verification commands, existing AI rule files, and existing spec sources. Do not treat those external or pre-existing sources as replacements for the loopx execution record and review artifact.
+
 ## Expected Outputs
 
 - a review artifact tied to the run being evaluated
@@ -42,6 +47,7 @@ Use stable machine values only where they are commands, file paths, JSON/state f
 - Use this only after build has produced execution and verification evidence for a specific run.
 - Stop here if review evidence is incomplete. `review` remains an independent gate and does not auto-complete the workflow.
 - Review must include code review of the build-owned implementation diff. Do not limit review to artifact/schema checks.
+- Review should compare verification evidence against project-native commands recorded in `.loopx/config.json` when available, while still accepting stronger task-specific verification from the approved plan.
 - Review must include the architecture-smell lane as part of review evidence. This is not a new workflow stage and must not create extra user steps.
 - Review must compare the execution scope against the approved workflow scope. If `execution-record.md` declares non-empty `remaining_scope`, `completion_claim` other than `full`, or a mismatch between `planned_scope` and `implemented_scope`, review must return no-go and route to build or plan. A partial slice may be accepted as useful work, but it must not be approved as full workflow completion.
 - Code review findings should focus on real bugs, regressions, missing tests, broken contracts, security/data-integrity risks, and user-visible behavior gaps.

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

@@ -1,6 +1,9 @@
 ---
 name: tdd
-description: Use when implementing any feature or bugfix, before writing implementation code
+description: "Guides feature and bugfix implementation through a failing test before production code and red-green-refactor discipline. Not for generated files or throwaway prototypes."
+when_to_use: "tdd, failing test first, feature implementation, bugfix, regression test, red green refactor, 测试先行"
+metadata:
+  version: "0.1.5"
 ---
 
 # Test-Driven Development (TDD)

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

@@ -1,6 +1,9 @@
 ---
 name: verify
-description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+description: "Requires fresh verification evidence before claiming work is complete, fixed, passing, review-ready, or ready to commit. Not for speculative confidence or stale results."
+when_to_use: "verify, completion claim, fixed claim, tests pass, review-ready, commit, fresh evidence, 验证, 完成前检查"
+metadata:
+  version: "0.1.5"
 ---
 
 # Verification Before Completion

package/scripts/verify-skills.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+
+import assert from 'node:assert/strict';
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { LOOPX_BUNDLED_SKILLS } from '../src/install-discovery.mjs';
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const packageJson = JSON.parse(await readFile(join(repoRoot, 'package.json'), 'utf8'));
+const pluginManifest = JSON.parse(await readFile(join(repoRoot, 'plugins', 'loopx', '.codex-plugin', 'plugin.json'), 'utf8'));
+const resolverPath = join(repoRoot, 'skills', 'RESOLVER.md');
+const markdownPaths = [
+  'README.md',
+  'README.zh-CN.md',
+  'AGENTS.md',
+  'skills/RESOLVER.md',
+];
+const personalPathPattern = /\/(?:Users|home)\/[A-Za-z0-9._-]+\//;
+const localRefPattern = /(?<![/.])\b(?:references|agents|scripts)\/[\w/.-]+\b/g;
+
+function parseFrontmatter(path, text) {
+  assert.equal(text.startsWith('---\n'), true, `${path} must start with YAML frontmatter`);
+  const end = text.indexOf('\n---\n', 4);
+  assert.notEqual(end, -1, `${path} frontmatter must close with ---`);
+
+  const fields = {};
+  let inMetadata = false;
+  for (const line of text.slice(4, end).split('\n')) {
+    if (line === 'metadata:') {
+      inMetadata = true;
+      continue;
+    }
+    if (inMetadata && line.startsWith('  version:')) {
+      fields.version = line.split(':', 2)[1].trim().replace(/^"|"$/g, '');
+      continue;
+    }
+    if (!line || line.startsWith(' ')) {
+      continue;
+    }
+    inMetadata = false;
+    const separator = line.indexOf(':');
+    assert.notEqual(separator, -1, `${path} has invalid frontmatter line: ${line}`);
+    const key = line.slice(0, separator).trim();
+    const raw = line.slice(separator + 1).trim();
+    fields[key] = raw.replace(/^"|"$/g, '');
+  }
+  return fields;
+}
+
+function assertSkillDescription(skillName, description) {
+  assert.ok(description, `${skillName} missing description`);
+  assert.ok(description.length >= 40, `${skillName} description is too short`);
+  assert.ok(description.length <= 500, `${skillName} description is too long`);
+  assert.match(description, /not for/i, `${skillName} description must include a Not for exclusion`);
+}
+
+async function assertMarkdownStructure(relativePath) {
+  const path = join(repoRoot, relativePath);
+  assert.equal(existsSync(path), true, `${relativePath} missing`);
+  const text = await readFile(path, 'utf8');
+  assert.equal(text.endsWith('\n'), true, `${relativePath} missing final newline`);
+
+  const fenceStack = [];
+  text.split('\n').forEach((line, index) => {
+    assert.equal(/^(<<<<<<<|=======|>>>>>>>)($| )/.test(line), false, `${relativePath}:${index + 1}: merge conflict marker`);
+    const match = line.match(/^(`{3,}|~{3,})/);
+    if (!match) {
+      return;
+    }
+    const marker = match[1];
+    if (fenceStack.length > 0 && marker[0] === fenceStack.at(-1).char && marker.length >= fenceStack.at(-1).length) {
+      fenceStack.pop();
+      return;
+    }
+    fenceStack.push({ char: marker[0], length: marker.length, line: index + 1 });
+  });
+
+  assert.deepEqual(fenceStack, [], `${relativePath} has unclosed fenced block`);
+}
+
+function assertContains(text, value, label) {
+  assert.match(text, new RegExp(value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')), `${label} missing ${value}`);
+}
+
+async function assertPublicDocsAligned() {
+  const readme = await readFile(join(repoRoot, 'README.md'), 'utf8');
+  const readmeZh = await readFile(join(repoRoot, 'README.zh-CN.md'), 'utf8');
+  const commands = [
+    'loopx init',
+    'loopx clarify',
+    'loopx approve',
+    'loopx plan',
+    'loopx build',
+    'loopx review',
+    'loopx archive',
+    'loopx autopilot',
+    'loopx render',
+    'loopx status',
+    'loopx setup-context',
+    'loopx doctor',
+    'loopx migrate',
+    'loopx repair-install',
+    'node scripts/verify-skills.mjs',
+  ];
+  for (const command of commands) {
+    assertContains(readme, command, 'README.md');
+    assertContains(readmeZh, command, 'README.zh-CN.md');
+  }
+
+  const releaseNotesRoot = join(repoRoot, 'docs', 'release-notes');
+  const releaseNotes = existsSync(releaseNotesRoot)
+    ? (await readdir(releaseNotesRoot)).filter((name) => name.endsWith('.md'))
+    : [];
+  assert.ok(releaseNotes.includes(`${packageJson.version}.md`), `docs/release-notes/${packageJson.version}.md missing`);
+  for (const name of releaseNotes) {
+    await assertMarkdownStructure(`docs/release-notes/${name}`);
+  }
+}
+
+async function assertSkill(skillName, resolverText) {
+  const rootPath = join(repoRoot, 'skills', skillName, 'SKILL.md');
+  const pluginPath = join(repoRoot, 'plugins', 'loopx', 'skills', skillName, 'SKILL.md');
+  assert.equal(existsSync(rootPath), true, `${skillName} root SKILL.md missing`);
+  assert.equal(existsSync(pluginPath), true, `${skillName} plugin SKILL.md missing`);
+
+  const rootText = await readFile(rootPath, 'utf8');
+  const pluginText = await readFile(pluginPath, 'utf8');
+  assert.equal(pluginText, rootText, `${skillName} plugin mirror drifted`);
+  assert.equal(personalPathPattern.test(rootText), false, `${skillName} contains a personal absolute path`);
+
+  const fields = parseFrontmatter(rootPath, rootText);
+  assert.equal(fields.name, skillName, `${skillName} frontmatter name mismatch`);
+  assert.equal(fields.version, packageJson.version, `${skillName} metadata.version must match package.json`);
+  assert.ok(fields.when_to_use && fields.when_to_use.length >= 20, `${skillName} missing useful when_to_use metadata`);
+  assertSkillDescription(skillName, fields.description);
+  assert.match(resolverText, new RegExp(`skills/${skillName}/SKILL\\.md`), `${skillName} missing from skills/RESOLVER.md`);
+
+  const refs = [...rootText.matchAll(localRefPattern)].map((match) => match[0]);
+  for (const ref of refs) {
+    const target = join(repoRoot, 'skills', skillName, ref);
+    assert.equal(existsSync(target), true, `${skillName} references missing local file: ${ref}`);
+  }
+}
+
+assert.equal(pluginManifest.version, packageJson.version, 'plugin manifest version must match package.json');
+assert.equal(existsSync(resolverPath), true, 'skills/RESOLVER.md missing');
+
+for (const relativePath of markdownPaths) {
+  await assertMarkdownStructure(relativePath);
+}
+await assertPublicDocsAligned();
+
+const resolverText = await readFile(resolverPath, 'utf8');
+for (const skillName of LOOPX_BUNDLED_SKILLS) {
+  await assertSkill(skillName, resolverText);
+}
+
+const staleRefs = [...resolverText.matchAll(/skills\/([a-z][a-z0-9-]*)\/SKILL\.md/g)]
+  .map((match) => match[1])
+  .filter((skillName) => !LOOPX_BUNDLED_SKILLS.includes(skillName));
+assert.deepEqual([...new Set(staleRefs)], [], 'skills/RESOLVER.md contains stale bundled-skill refs');
+
+console.log(`ok: verified ${LOOPX_BUNDLED_SKILLS.length} loopx bundled skills`);

package/skills/RESOLVER.md

@@ -0,0 +1,45 @@
+# loopx Skill Resolver
+
+Central routing map for loopx bundled skills. Keep this file in sync with every bundled `skills/<name>/SKILL.md` and `plugins/loopx/skills/<name>/SKILL.md`.
+
+Read the selected skill file before acting. If multiple skills match, read every likely candidate and use the disambiguation rules below.
+
+## Public Workflow Skills
+
+| Trigger | Skill |
+|---|---|
+| Ambiguous request, unclear scope, non-goals, decision boundaries, requirements interview | `skills/clarify/SKILL.md` |
+| Approved clarify spec, direct requirements artifact, PRD/test/architecture planning, consensus planning | `skills/plan/SKILL.md` |
+| Approved plan execution, implementation persistence, review-requested implementation fixes | `skills/build/SKILL.md` |
+| Independent acceptance, code review, architecture-smell review, go/no-go after build | `skills/review/SKILL.md` |
+| Completed workflow needs long-lived spec sync and ADR candidate | `skills/archive/SKILL.md` |
+| User wants one bounded end-to-end loopx run over clarify/plan/build/review | `skills/autopilot/SKILL.md` |
+
+## Support Skills
+
+| Trigger | Skill |
+|---|---|
+| Bug, test failure, build failure, regression, unexpected behavior, root-cause investigation | `skills/debug/SKILL.md` |
+| Feature or bugfix implementation where behavior should be covered by a failing test first | `skills/tdd/SKILL.md` |
+| Completion, fixed, passing, review-ready, commit, or handoff claims need fresh evidence | `skills/verify/SKILL.md` |
+| Editing `.go` files or reviewing Go style inside build/review | `skills/go-style/SKILL.md` |
+| Go-Kratos proto, service, biz, data, middleware, auth, config, or Kratos troubleshooting | `skills/kratos/SKILL.md` |
+
+## Disambiguation
+
+1. If intent, scope, non-goals, or decision boundaries are unresolved, use `clarify` before `plan`.
+2. If requirements are approved but execution has not started, use `plan` before `build`.
+3. If implementation is broken or tests fail during build, use `debug` as the diagnostic lens before patching.
+4. If code is already implemented and needs acceptance, use `review`; do not run new build work from review.
+5. If review requests implementation-only fixes, route to `build --from-review`; route to `plan` only when the plan itself is wrong.
+6. If the user asks for autonomous execution, use `autopilot` only when requirements are bounded enough to run without new human decisions.
+7. Treat `tdd`, `verify`, `go-style`, and `kratos` as support lenses unless the user explicitly invokes them directly.
+8. `archive` is only valid after `review -> done`.
+
+## Deterministic Guard
+
+Run this before release or when changing bundled skills:
+
+```bash
+node scripts/verify-skills.mjs
+```

package/skills/archive/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: archive
-description: Sync an approved loopx change delta into long-lived specs after review is done.
+description: "Archives an approved loopx change delta into long-lived specs and writes an ADR candidate after done approval. Not for active builds or unapproved reviews."
+when_to_use: "archive, done workflow, spec delta, long-lived specs, ADR candidate, review approved, 归档, 同步规格"
+metadata:
+  version: "0.1.5"
 argument-hint: "<workflow slug>"
 ---
 

package/skills/autopilot/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: autopilot
-description: Richer internal-phase loopx autonomous orchestration over the public clarify/plan/build/review flow.
+description: "Runs one bounded autonomous loopx orchestration over clarify, plan, build, and review while preserving canonical artifacts. Not for manual gate-by-gate control."
+when_to_use: "autopilot, autonomous loopx run, end-to-end workflow, run all stages, bounded orchestration, 自动执行, 全流程"
+metadata:
+  version: "0.1.5"
 argument-hint: "<workflow slug>"
 ---
 

package/skills/build/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: build
-description: Ralph-style loopx execution runtime under the public build stage.
+description: "Executes an approved loopx plan or review rework contract with evidence, verification, deslop, and regression gates. Not for unclear requirements or independent review."
+when_to_use: "build, implement approved plan, execute PRD, --from-review, review rework, implementation fixes, 执行, 实现, 修改"
+metadata:
+  version: "0.1.5"
 argument-hint: "[--no-deslop] <approved PRD path or workflow slug> | --from-review <review artifact path>"
 ---
 
@@ -30,6 +33,7 @@ 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.
+- `.loopx/config.json` is supporting context for existing project AI rules, existing spec sources, and discovered verification commands; use it to preserve local sources of truth, not to skip loopx stages.
 - 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.
@@ -72,6 +76,8 @@ Compatible skill / CLI input:
 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.
+
+Also load `.loopx/config.json` when present. Its `project_conventions` entries identify existing project rule/spec files that should be preserved, and its `verification_commands` entries are the first project-native commands to consider for fresh evidence.
 </Inputs>
 
 <Execution_Model>

package/skills/clarify/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: clarify
-description: Comprehensive loopx clarify skill for requirements, boundaries, and design-ready specs.
+description: "Clarifies ambiguous loopx work into requirements, non-goals, decision boundaries, and design-ready specs before planning. Not for already-approved plans or concrete implementation tasks."
+when_to_use: "clarify, requirements, ambiguous request, unclear scope, non-goals, decision boundaries, acceptance criteria, 需求澄清, 范围不清"
+metadata:
+  version: "0.1.5"
 ---
 
 # loopx Clarify

package/skills/debug/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: debug
-description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+description: "Finds root cause for bugs, failing tests, build failures, regressions, and unexpected behavior before fixes. Not for new feature planning or routine code review."
+when_to_use: "debug, bug, test failure, build failure, regression, unexpected behavior, root cause, 报错, 失败, 回归, 排查"
+metadata:
+  version: "0.1.5"
 ---
 
 # Systematic Debugging

package/skills/go-style/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: go-style
-description: Go language style support for loopx. Use before creating or editing Go (.go) files, especially inside build execution lanes.
+description: "Applies loopx Go coding style for .go edits, tests, errors, context, naming, and interface boundaries. Not for non-Go code or Kratos-specific architecture by itself."
+when_to_use: "go-style, Go, golang, .go files, go tests, gofmt, idiomatic Go, Go style, Go 代码"
+metadata:
+  version: "0.1.5"
 ---
 
 # Go Style

package/skills/kratos/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: kratos
-description: Go-Kratos framework support for loopx. Use for Kratos microservices, proto/buf API work, service/biz/data layering, Kratos middleware, auth, configuration, and troubleshooting.
+description: "Supports Go-Kratos microservices, proto/buf APIs, service/biz/data layers, middleware, auth, config, and troubleshooting. Not for generic Go style alone."
+when_to_use: "kratos, Go-Kratos, proto, buf, service layer, biz layer, data layer, middleware, auth, config, Kratos 微服务"
+metadata:
+  version: "0.1.5"
 ---
 
 # Kratos

package/skills/plan/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: plan
-description: Consensus-first loopx planning skill with Planner, Architect, and Critic review.
+description: "Creates a consensus-first loopx plan package with Planner, Architect, and Critic review from an approved spec. Not for unresolved requirements or direct implementation."
+when_to_use: "plan, planning, consensus planning, PRD, architecture plan, test plan, approved clarify spec, 规划, 方案, 架构评审"
+metadata:
+  version: "0.1.5"
 argument-hint: "[--interactive] [--deliberate] [--direct <spec-path>] <clarified task or spec path>"
 ---
 

package/skills/review/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: review
-description: Repo-local acceptance surface for loopx.
+description: "Reviews a loopx build execution record for acceptance, code risks, evidence quality, and architecture smells. Not for doing implementation work or replanning."
+when_to_use: "review, code review, acceptance, go no-go, execution-record, architecture smell, build complete, 审查, 验收"
+metadata:
+  version: "0.1.5"
 argument-hint: "<execution-record path or workflow slug>"
 ---
 
@@ -22,6 +25,8 @@ Compatible skill / CLI input:
 
 When invoked with an execution record path, derive `<slug>` from the workflow directory and evaluate the matching active run.
 
+When present, use `.loopx/config.json` as supporting context for project-native verification commands, existing AI rule files, and existing spec sources. Do not treat those external or pre-existing sources as replacements for the loopx execution record and review artifact.
+
 ## Expected Outputs
 
 - a review artifact tied to the run being evaluated
@@ -42,6 +47,7 @@ Use stable machine values only where they are commands, file paths, JSON/state f
 - Use this only after build has produced execution and verification evidence for a specific run.
 - Stop here if review evidence is incomplete. `review` remains an independent gate and does not auto-complete the workflow.
 - Review must include code review of the build-owned implementation diff. Do not limit review to artifact/schema checks.
+- Review should compare verification evidence against project-native commands recorded in `.loopx/config.json` when available, while still accepting stronger task-specific verification from the approved plan.
 - Review must include the architecture-smell lane as part of review evidence. This is not a new workflow stage and must not create extra user steps.
 - Review must compare the execution scope against the approved workflow scope. If `execution-record.md` declares non-empty `remaining_scope`, `completion_claim` other than `full`, or a mismatch between `planned_scope` and `implemented_scope`, review must return no-go and route to build or plan. A partial slice may be accepted as useful work, but it must not be approved as full workflow completion.
 - Code review findings should focus on real bugs, regressions, missing tests, broken contracts, security/data-integrity risks, and user-visible behavior gaps.

package/skills/tdd/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: tdd
-description: Use when implementing any feature or bugfix, before writing implementation code
+description: "Guides feature and bugfix implementation through a failing test before production code and red-green-refactor discipline. Not for generated files or throwaway prototypes."
+when_to_use: "tdd, failing test first, feature implementation, bugfix, regression test, red green refactor, 测试先行"
+metadata:
+  version: "0.1.5"
 ---
 
 # Test-Driven Development (TDD)

package/skills/verify/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: verify
-description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+description: "Requires fresh verification evidence before claiming work is complete, fixed, passing, review-ready, or ready to commit. Not for speculative confidence or stale results."
+when_to_use: "verify, completion claim, fixed claim, tests pass, review-ready, commit, fresh evidence, 验证, 完成前检查"
+metadata:
+  version: "0.1.5"
 ---
 
 # Verification Before Completion

package/src/context-manifest.mjs

@@ -138,6 +138,7 @@ export async function generateBuildContextManifest({ cwd, root, state, slug }) {
     row(cwd, { stage: 'build', kind: 'review-rework', path: reviewReworkPath, reason: 'review_requested_implementation_fixes', priority: 33, required: requiresReviewRework }),
     row(cwd, { stage: 'build', kind: 'domain-context', path: contextPaths.domainGlossary, reason: 'domain_vocabulary', priority: 34, required: contextSetup.status !== 'missing' }),
     row(cwd, { stage: 'build', kind: 'agent-domain', path: contextPaths.agentDomain, reason: 'agent_context_rules', priority: 35, required: false }),
+    row(cwd, { stage: 'build', kind: 'workspace-config', path: join(cwd, '.loopx', 'config.json'), reason: 'project_rules_spec_sources_and_verification_commands', priority: 36, required: false }),
   ];
   const manifestPath = buildContextManifestPath(root);
   await writeContextManifest(manifestPath, rows);
@@ -157,6 +158,7 @@ export async function generateReviewContextManifest({ cwd, root, state, slug })
     row(cwd, { stage: 'review', kind: 'residual-risks', path: join(root, 'execution-record.md'), reason: 'residual_risk_reference', priority: 26, required: false }),
     row(cwd, { stage: 'review', kind: 'build-support', path: join(root, 'build-support'), reason: 'build_gate_evidence', priority: 30, required: false }),
     row(cwd, { stage: 'review', kind: 'agent-domain', path: contextPaths.agentDomain, reason: 'agent_context_rules', priority: 31, required: false }),
+    row(cwd, { stage: 'review', kind: 'workspace-config', path: join(cwd, '.loopx', 'config.json'), reason: 'project_rules_spec_sources_and_verification_commands', priority: 32, required: false }),
     row(cwd, { stage: 'review', kind: 'state', path: join(root, 'state.json'), reason: 'workflow_state', priority: 40 }),
   ];
   const manifestPath = reviewContextManifestPath(root);

package/src/project-discovery.mjs

@@ -0,0 +1,163 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+async function readJsonIfExists(path) {
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    return JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function pathKind(path) {
+  if (!existsSync(path)) {
+    return null;
+  }
+  const info = await stat(path);
+  return info.isDirectory() ? 'directory' : 'file';
+}
+
+async function candidate(path, label) {
+  const kind = await pathKind(path);
+  if (!kind) {
+    return null;
+  }
+  return { path: label, kind };
+}
+
+async function directoryChildren(root, label) {
+  if (!existsSync(root)) {
+    return [];
+  }
+  const info = await stat(root);
+  if (!info.isDirectory()) {
+    return [];
+  }
+  const entries = await readdir(root);
+  return entries
+    .filter((entry) => /\.(md|mdc|txt)$/i.test(entry))
+    .sort()
+    .map((entry) => ({ path: `${label}/${entry}`, kind: 'file' }));
+}
+
+async function discoverAiRules(cwd) {
+  const direct = await Promise.all([
+    candidate(join(cwd, 'AGENTS.md'), 'AGENTS.md'),
+    candidate(join(cwd, 'CLAUDE.md'), 'CLAUDE.md'),
+    candidate(join(cwd, '.cursor', 'rules'), '.cursor/rules'),
+    candidate(join(cwd, '.github', 'copilot-instructions.md'), '.github/copilot-instructions.md'),
+  ]);
+  return [
+    ...direct.filter(Boolean),
+    ...await directoryChildren(join(cwd, '.cursor', 'rules'), '.cursor/rules'),
+  ].filter((item, index, items) => items.findIndex((other) => other.path === item.path) === index);
+}
+
+async function discoverSpecSources(cwd) {
+  const direct = await Promise.all([
+    candidate(join(cwd, 'openspec.yaml'), 'openspec.yaml'),
+    candidate(join(cwd, 'openspec.yml'), 'openspec.yml'),
+    candidate(join(cwd, 'openspec.json'), 'openspec.json'),
+    candidate(join(cwd, 'open-spec.yaml'), 'open-spec.yaml'),
+    candidate(join(cwd, '.specify'), '.specify'),
+    candidate(join(cwd, 'specs'), 'specs'),
+    candidate(join(cwd, 'docs', 'changes'), 'docs/changes'),
+    candidate(join(cwd, 'docs', 'specs'), 'docs/specs'),
+    candidate(join(cwd, 'docs', 'adr'), 'docs/adr'),
+    candidate(join(cwd, 'docs', 'rfcs'), 'docs/rfcs'),
+  ]);
+  return direct.filter(Boolean);
+}
+
+function packageRunner(cwd, packageJson) {
+  const packageManager = String(packageJson?.packageManager || '');
+  if (packageManager.startsWith('pnpm@') || existsSync(join(cwd, 'pnpm-lock.yaml'))) {
+    return 'pnpm';
+  }
+  if (packageManager.startsWith('yarn@') || existsSync(join(cwd, 'yarn.lock'))) {
+    return 'yarn';
+  }
+  if (packageManager.startsWith('bun@') || existsSync(join(cwd, 'bun.lock')) || existsSync(join(cwd, 'bun.lockb'))) {
+    return 'bun';
+  }
+  return 'npm';
+}
+
+function runScriptCommand(runner, scriptName) {
+  if (runner === 'npm') {
+    return scriptName === 'test' ? 'npm test' : `npm run ${scriptName}`;
+  }
+  return `${runner} ${scriptName}`;
+}
+
+function firstScript(scripts, names) {
+  return names.find((name) => Object.prototype.hasOwnProperty.call(scripts, name));
+}
+
+async function discoverPackageCommands(cwd) {
+  const packageJson = await readJsonIfExists(join(cwd, 'package.json'));
+  if (!packageJson) {
+    return {};
+  }
+  const runner = packageRunner(cwd, packageJson);
+  const scripts = packageJson.scripts || {};
+  const install = runner === 'npm' && existsSync(join(cwd, 'package-lock.json'))
+    ? 'npm ci'
+    : `${runner} install`;
+  return {
+    install,
+    test: scripts.test ? runScriptCommand(runner, 'test') : null,
+    lint: scripts.lint ? runScriptCommand(runner, 'lint') : null,
+    typecheck: scripts.typecheck ? runScriptCommand(runner, 'typecheck') : null,
+    build: scripts.build ? runScriptCommand(runner, 'build') : null,
+    e2e: (() => {
+      const script = firstScript(scripts, ['test:e2e', 'e2e', 'test:browser', 'playwright']);
+      return script ? runScriptCommand(runner, script) : null;
+    })(),
+  };
+}
+
+function compactCommands(commands) {
+  return Object.fromEntries(
+    ['install', 'test', 'lint', 'typecheck', 'build', 'e2e']
+      .map((key) => [key, commands[key] || null]),
+  );
+}
+
+export async function discoverVerificationCommands(cwd) {
+  const packageCommands = await discoverPackageCommands(cwd);
+  if (Object.keys(packageCommands).length > 0) {
+    return compactCommands(packageCommands);
+  }
+  if (existsSync(join(cwd, 'go.mod'))) {
+    return compactCommands({
+      test: 'go test ./...',
+      build: 'go build ./...',
+    });
+  }
+  if (existsSync(join(cwd, 'pyproject.toml'))) {
+    return compactCommands({
+      install: 'pip install -e .',
+      test: 'pytest',
+    });
+  }
+  return compactCommands({});
+}
+
+export async function inspectProjectConventions(cwd) {
+  const [existingAiRules, existingSpecSources, verificationCommands] = await Promise.all([
+    discoverAiRules(cwd),
+    discoverSpecSources(cwd),
+    discoverVerificationCommands(cwd),
+  ]);
+  return {
+    existing_ai_rules: existingAiRules,
+    existing_spec_sources: existingSpecSources,
+    verification_commands: verificationCommands,
+    source_of_truth_policy: 'preserve-existing-project-rules-and-use-loopx-artifacts-only-after-init',
+  };
+}

package/src/workflow.mjs

@@ -16,6 +16,7 @@ import {
 import { doctorRuntime, ensureLoopxRoot, resolveLoopxRoot } from './runtime-maintenance.mjs';
 import { DEFAULT_BUILD_MAX_ITERATIONS, createDefaultBuildAdapter } from './build-runtime.mjs';
 import { DEFAULT_MAX_ITERATIONS, createDefaultPlanAdapter } from './plan-runtime.mjs';
+import { inspectProjectConventions } from './project-discovery.mjs';
 import { createDefaultReviewAdapter } from './review-runtime.mjs';
 import { appendWorkspaceJournal } from './workspace-memory.mjs';
 import { inspectWorkspaceContext, setupWorkspaceContext } from './workspace-context.mjs';
@@ -2509,6 +2510,7 @@ async function refreshExecutionStatus(root, state) {
 
 export async function initWorkspace(cwd, { slug } = {}) {
   const workspaceRoot = resolveWorkspaceRoot(cwd);
+  const projectConventions = await inspectProjectConventions(cwd);
   await ensureLoopxRoot(cwd);
   await ensureDir(join(workspaceRoot, 'context'));
   await ensureDir(join(workspaceRoot, 'intake'));
@@ -2527,6 +2529,12 @@ export async function initWorkspace(cwd, { slug } = {}) {
     product_contract: 'skill-first-v1',
     default_flow: ['clarify', 'plan', 'build', 'review', 'done', 'archive'],
     preferred_surface: ['clarify', 'plan', 'build', 'review', 'archive', 'autopilot'],
+    source_of_truth_policy: projectConventions.source_of_truth_policy,
+    project_conventions: {
+      existing_ai_rules: projectConventions.existing_ai_rules,
+      existing_spec_sources: projectConventions.existing_spec_sources,
+    },
+    verification_commands: projectConventions.verification_commands,
   };
 
   if (!existsSync(workspaceConfigPath(workspaceRoot))) {