@ai-content-space/loopx 0.1.3 → 0.1.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-content-space/loopx",
   "type": "module",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Skill-first loopx workflow product for Codex",
   "repository": {
     "type": "git",
@@ -22,8 +22,10 @@
     "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/",
     "templates/",
@@ -34,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/scripts/plugin-install.test.mjs

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

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

@@ -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>"
 ---
 
@@ -10,6 +13,15 @@ argument-hint: "<workflow slug>"
 
 Use `archive` after a loopx workflow has reached `done`. It syncs the accepted change delta into long-lived `.loopx/specs/` files, archives the change staging directory, and writes an advisory ADR candidate.
 
+The accepted delta is requirement-based, not a changelog block. Archive applies:
+
+- `## ADDED Requirements`
+- `## MODIFIED Requirements`
+- `## REMOVED Requirements`
+- `## RENAMED Requirements`
+
+into the current long-lived `## Requirements` state for each target domain.
+
 ## Inputs
 
 - `<workflow slug>` for a completed loopx workflow
@@ -33,6 +45,7 @@ Then report in Chinese:
 ## Boundaries
 
 - Do not run archive before `review -> done` has been approved.
+- Do not archive malformed requirement deltas. ADDED and MODIFIED entries must use `### Requirement:`, SHALL/MUST language, and at least one `#### Scenario:`.
 - Do not archive when `execution-record.md` declares non-empty `remaining_scope`, `completion_claim` other than `full`, or a mismatch between `planned_scope` and `implemented_scope`; route back to build/plan instead.
 - Do not edit implementation code.
 - Do not promote ADR candidates into `docs/adr/` automatically; report the candidate path for human follow-up.

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
@@ -23,7 +26,7 @@ Its job is not just to ask questions. Its job is to turn a vague or overloaded r
 - The request is broad, ambiguous, or mixes problem, solution, and implementation detail.
 - The user needs help defining scope, non-goals, acceptance criteria, or tradeoffs before planning.
 - A design direction exists only implicitly and would otherwise be invented during implementation.
-- The task will later be handed to `plan`, `build`, or `autopilot`, and you want a high-signal spec first.
+- The task will later be handed to `plan`, and you want a high-signal spec first.
 </Use_When>
 
 <Do_Not_Use_When>
@@ -33,7 +36,7 @@ Its job is not just to ask questions. Its job is to turn a vague or overloaded r
 </Do_Not_Use_When>
 
 <Why_This_Exists>
-Most implementation drift happens before coding begins. Teams often think they need “more planning,” when the real problem is weaker intent clarity, hidden assumptions, fuzzy boundaries, or a design shape that was never made explicit. `clarify` exists to solve those upstream failures before `plan` or `build` magnifies them.
+Most implementation drift happens before coding begins. Teams often think they need “more planning,” when the real problem is weaker intent clarity, hidden assumptions, fuzzy boundaries, or a design shape that was never made explicit. `clarify` exists to solve those upstream failures before `plan` turns the clarified intent into an execution contract.
 </Why_This_Exists>
 
 <Core_Principles>
@@ -268,7 +271,7 @@ Before marking a clarify spec handoff-ready, perform a self-review pass:
 
 Write the output to the loopx runtime namespace:
 
-- `.loopx/specs/clarify-<slug>-<timestamp>.md`
+- `.loopx/intake/clarify-<slug>-<timestamp>.md`
 
 The clarify spec should include:
 
@@ -299,17 +302,17 @@ The clarify spec should include:
 
 After the clarify spec is ready:
 
-- hand off to `plan` by default
-- hand off to `build` only if the user explicitly wants direct execution and the task is already concrete enough
-- hand off to `autopilot` only when the scope is sufficiently tight for a bounded end-to-end run
+- hand off to `plan`; do not start implementation, TDD, `build`, or `autopilot` from `clarify`
+- if the user asks to execute immediately, explain that loopx requires the `plan` gate first and provide the plan invocation
+- if a task is too small to justify planning, do not use `clarify`; handle that request outside the clarify workflow from the start
 
 Preferred explicit handoff contract:
 
 - Recommended invocation: `$plan <slug>`
-- Artifact-pinned invocation when needed: `$plan --direct .loopx/specs/clarify-<slug>-<timestamp>.md`
+- Artifact-pinned invocation when needed: `$plan --direct .loopx/intake/clarify-<slug>-<timestamp>.md`
 - Consumer behavior: treat the clarify spec as the source of truth for intent, non-goals, decision boundaries, constraints, and design direction; do not reopen clarification by default
 
-`clarify` itself does not implement the feature.
+`clarify` itself does not implement the feature. The handoff recommendation must name `plan` as the next workflow step.
 
 </Process>
 
@@ -328,6 +331,7 @@ Preferred explicit handoff contract:
 
 <Must_Not_Decide_Automatically>
 - approval to move from clarify into plan
+- skipping `plan` after producing a clarify spec
 - implementation details that were never clarified or grounded
 - widening the task because a broader redesign sounds cleaner
 </Must_Not_Decide_Automatically>

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>"
 ---
 
@@ -40,7 +43,7 @@ By default, `plan` includes the full consensus review loop formerly documented u
 Accepted inputs:
 
 - an approved loopx clarify workflow slug
-- `.loopx/specs/clarify-*.md`
+- `.loopx/intake/clarify-*.md`
 - `.omx/specs/deep-interview-*.md`
 - a direct task description when enough context is already present
 - `--direct <spec-path>` to force a specific requirements artifact
@@ -174,7 +177,7 @@ The final plan must include:
 
 - ADR: Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups
 - concrete implementation steps sized to the actual task
-- target long-lived spec domains and the requirements delta for archive
+- target long-lived spec domains and an OpenSpec-style requirements delta for archive
 - vertical slices sized as independently verifiable tracer bullets, not horizontal layer-only task groups
 - execution inputs mapped to concrete sources before build starts
 - available execution lanes and recommended lane
@@ -220,7 +223,8 @@ The plan gate is blocked until:
 
 - plan package artifacts exist
 - change proposal, spec delta, design, tasks, vertical slices, and artifact graph exist
-- spec delta declares target domains and added or modified requirements
+- spec delta declares target domains and `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` blocks
+- every ADDED or MODIFIED requirement uses `### Requirement:`, contains SHALL or MUST text, and includes at least one `#### Scenario:`
 - vertical slices contain at least one `AFK` or `HITL` end-to-end slice with acceptance criteria and verification signal
 - Architect review is complete
 - Critic verdict is `approve`

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/codex-workflow-hook.mjs

@@ -3,7 +3,6 @@
 import { existsSync, readdirSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
-import { nextSkillCommand } from '../src/next-skill.mjs';
 
 function readStdin() {
   return new Promise((resolveValue) => {
@@ -29,9 +28,61 @@ function readStdin() {
 }
 
 function nextSkill(state) {
-  const command = nextSkillCommand(state);
-  if (command) {
-    return command;
+  if (!state || !state.slug) {
+    return null;
+  }
+  const reviewBuildCommand = `$build --from-review .loopx/workflows/${state.slug}/review-report.md`;
+  if (isClarifyReadyForPlan(state)) {
+    return `$plan ${state.slug}`;
+  }
+  if (state.current_stage === 'done'
+    && state.completion_confirmed === true
+    && state.archive_status !== 'archived') {
+    return `$archive ${state.slug}`;
+  }
+  if (state.stage_status === 'awaiting-approval'
+    && state.current_stage === 'plan'
+    && Array.isArray(state.plan_blockers)
+    && state.plan_blockers.length === 0) {
+    return `$build .loopx/plans/prd-${state.slug}.md`;
+  }
+  if (state.current_stage === 'build'
+    && state.stage_status === 'awaiting-approval'
+    && state.pending_user_decision === 'build->review'
+    && state.review_status === 'ready-for-review'
+    && state.execution_record_status === 'complete'
+    && Array.isArray(state.build_blockers)
+    && state.build_blockers.length === 0) {
+    return `$review .loopx/workflows/${state.slug}/execution-record.md`;
+  }
+  if (state.current_stage === 'review'
+    && state.review_verdict === 'request-changes'
+    && state.rollback_target === 'build'
+    && (
+      state.pending_user_decision === 'review->build'
+      || state.requested_transition === 'review->build'
+      || state.approval?.build === 'requested'
+      || state.approval?.build === 'approved'
+    )) {
+    return reviewBuildCommand;
+  }
+  if (state.current_stage === 'review'
+    && state.review_verdict === 'request-changes'
+    && state.requested_transition === 'review->build'
+    && state.approval?.build === 'approved') {
+    return reviewBuildCommand;
+  }
+  if (state.current_stage === 'review'
+    && state.review_verdict === 'request-changes'
+    && state.requested_transition === 'review->plan'
+    && state.approval?.rollback === 'approved') {
+    return `$plan ${state.slug}`;
+  }
+  if (state.current_stage === 'review'
+    && state.review_verdict === 'request-changes'
+    && state.requested_transition === 'review->clarify'
+    && state.approval?.rollback === 'approved') {
+    return `$clarify ${state.slug}`;
   }
   if (state.current_stage === 'review' && state.review_verdict === 'approve' && state.pending_user_decision === 'review->done') {
     return `loopx approve ${state.slug} --from review --to done`;
@@ -59,6 +110,49 @@ function stateLine(key, value) {
   return `${key}: ${value ?? 'unknown'}`;
 }
 
+function isClarifyReadyForPlan(state) {
+  return (state.current_stage === 'clarify' || (!state.current_stage && typeof state.clarify_current_round === 'number'))
+    && state.clarify_current_round > 0
+    && state.unresolved_ambiguity_count === 0
+    && state.clarify_non_goals_resolved === true
+    && state.clarify_decision_boundaries_resolved === true
+    && state.clarify_pressure_pass_complete === true
+    && typeof state.clarify_ambiguity_score === 'number'
+    && typeof state.clarify_target_ambiguity_threshold === 'number'
+    && state.clarify_ambiguity_score <= state.clarify_target_ambiguity_threshold;
+}
+
+function isLegacyClarifyState(state) {
+  return !state.current_stage && typeof state.clarify_current_round === 'number';
+}
+
+function nextActionLine(state, workflow) {
+  if (isLegacyClarifyState(state) && isClarifyReadyForPlan(state)) {
+    return `loopx migrate, then $plan ${state.slug || workflow}`;
+  }
+  if (isClarifyReadyForPlan(state) && state.approval?.plan !== 'approved') {
+    return `approve clarify -> plan, then $plan ${state.slug || workflow}`;
+  }
+  return nextSkill(state) || state.recommended_next_action || 'none';
+}
+
+function implementationGateLines(state) {
+  if (isClarifyReadyForPlan(state) && state.approval?.build !== 'approved') {
+    return [
+      'implementation gate: blocked until plan is approved',
+      'do not start build, TDD, or code edits from clarify',
+    ];
+  }
+  return [];
+}
+
+function stageText(state) {
+  if (isLegacyClarifyState(state)) {
+    return `legacy-clarify (${isClarifyReadyForPlan(state) ? 'blocked' : 'incomplete'})`;
+  }
+  return `${state.current_stage || 'unknown'} (${state.stage_status || 'unknown'})`;
+}
+
 function evidenceLines(state) {
   const evidence = Array.isArray(state.current_evidence_chain) ? state.current_evidence_chain : [];
   if (evidence.length === 0) {
@@ -131,9 +225,10 @@ try {
     '</loopx_instructions>',
     '<loopx_state>',
     `loopx workflow: ${state.slug || workflow}`,
-    `stage: ${state.current_stage || 'unknown'} (${state.stage_status || 'unknown'})`,
-    `next: ${nextSkill(state) || state.recommended_next_action || 'none'}`,
+    `stage: ${stageText(state)}`,
+    `next: ${nextActionLine(state, workflow)}`,
     `blockers: ${blockers(state)}`,
+    ...implementationGateLines(state),
     `approval: ${JSON.stringify(state.approval || {})}`,
     stateLine('readiness.plan.ready', boolText(state.readiness?.plan?.ready)),
     stateLine('readiness.build.ready', boolText(state.readiness?.build?.ready)),

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`);