@ai-content-space/loopx 0.2.3 → 0.2.7

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

@@ -3,7 +3,7 @@ name: finish
 description: "Finishes completed loopx development work after tests pass by presenting merge, PR, keep, or discard options. Not for unfinished work or failing verification."
 when_to_use: "implementation complete, tests pass, finish branch, create pull request, merge locally, keep branch, discard work"
 metadata:
-  version: "0.2.3"
+  version: "0.2.7"
 ---
 
 # Finish
@@ -66,18 +66,33 @@ git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
 
 Or ask: "This branch split from main - is that correct?"
 
-### Step 4: Learning Extraction
+### Step 4: Audit-First Learning Extraction
 
-Run learning extraction before presenting merge, PR, keep, or discard options.
+Run `finish-audit` before presenting merge, PR, keep, or discard options.
+
+`loopx:exec` and `loopx:subagent-exec` should have run `finish-start` before implementation. `finish-audit` uses that baseline to preserve committed `baseline..HEAD` evidence after the working tree is clean. It may also generate `audit.extraction_candidates` as draft memory/spec review prompts. These drafts are not automatically written to memory or specs.
 
 Allowed inputs:
-- current git diff
+- `finish-state.json` `audit.change_window`, especially `baseline..HEAD` commits and changed files
+- `finish-state.json` `audit.extraction_candidates`
+- current uncommitted git diff and `git status --short`
 - executed verification output
 - plan, spec, and review artifacts used in this task
 - explicit user decisions in the current conversation
 - existing `.loopx/memory/MEMORY.md` and `.loopx/memory/index.jsonl`
+- existing `docs/loopx/memory/*.md`
 - existing `docs/loopx/specs/*.md`
 
+An empty git diff does not mean there is no learning candidate. When `audit.change_window.commit_count > 0`, inspect the committed range before deciding memory/spec candidates. "Already committed" is not a rejection reason; reject only when the committed change window contains no durable behavior, contract, invariant, pitfall, or user decision worth preserving.
+
+Read the audit state from `.loopx/finish/<audit-id>/finish-state.json` before deciding what to record.
+After learning extraction, update `finish-state.json` before any `done` record:
+- set `status` to `"audited"`
+- for every `audit.extraction_candidates[]` item, add either a matching `accepted_candidates` with evidence or a matching `rejected_candidates[]` item with `rejection_reason`
+- when no extraction candidates exist and no candidate is accepted, replace `no_candidates_reason` with a specific reason
+
+`finish-record --status done` will reject an audit while generated extraction candidates remain unreviewed.
+
 Learning extraction priority:
 1. Durable behavior, contracts, or constraints proven by the implementation
 2. State, file, CLI, API, install, migration, compatibility, or test invariants
@@ -87,11 +102,19 @@ Learning extraction priority:
 
 Do not infer durable rules from agent intuition alone. Do not promote unverified implementation details.
 
+When the audit has no candidates, record `none` with the scanned inputs and a reason in `no_candidates_reason`.
+Keep rejected candidates explicit when draft candidates are not accepted.
+Accepted candidates require evidence from the audit state. Rejected candidates require reasons.
+choice recording must persist the user's completion choice through `finish-record` before presenting the final completion outcome.
+
 #### Memory
 
-Memory is local, agent-queryable project context. It is not repo-tracked by default.
+Memory has two scopes:
+
+- local memory: agent-queryable project context for one machine; not repo-tracked
+- shared memory: lightweight project knowledge that should follow a user across machines; repo-tracked
 
-Use:
+Use local memory for machine-local facts, short-lived handoffs, and context that is useful only to the current agent environment:
 
 ```text
 .loopx/memory/MEMORY.md
@@ -104,7 +127,13 @@ Use:
 
 `index.jsonl` is a curated active index, not an append-only history. It should point only to active memory cards worth querying.
 
-Use memory only for facts that will help a future agent avoid rework, avoid mistakes, or preserve a decision. Do not record process negatives such as "no spec promotion".
+Use shared memory for concise, evidence-backed notes that are useful across machines but not stable enough for specs:
+
+```text
+docs/loopx/memory/
+```
+
+Use memory only for facts that will help a future agent avoid rework, avoid mistakes, or preserve a decision. Do not record process negatives such as "no spec promotion". Do not store secrets, raw conversation logs, or machine-local paths in shared memory.
 
 One finish run may write 0-3 active memory cards. If more learnings appear, consolidate, promote to spec, archive stale cards, or skip low-signal items.
 
@@ -123,6 +152,8 @@ Allowed memory `type` values:
 
 Finish may automatically update `.loopx/memory/MEMORY.md`, `.loopx/memory/index.jsonl`, and active memory cards. The final response must list the memory changes.
 
+When accepting an `audit.extraction_candidates[]` item with `kind: "memory"` and `scope: "shared"`, write the accepted note under `docs/loopx/memory/` so it is visible in the git diff. Promote shared memory to `docs/loopx/specs/` when it becomes a durable rule that planning or review should depend on.
+
 #### Spec Candidates
 
 Spec extraction is conditional. Run the audit every time, but write spec candidates only when the task produced stable, shared, reusable project rules.
@@ -295,6 +326,7 @@ Use this shape:
 ```text
 Memory:
 - updated: .loopx/memory/MEMORY.md
+- shared: docs/loopx/memory/<file>.md
 - entries: <N> added, <N> archived
 - summary:
   - <high-signal memory change>

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

@@ -3,7 +3,7 @@ name: fix-review
 description: "Handles received code review feedback with verification, technical evaluation, pushback, and one-item-at-a-time fixes. Not for requesting a new review or implementing unrelated changes."
 when_to_use: "fix-review, received code review feedback, review comments, reviewer suggestions, requested changes, 处理评审意见"
 metadata:
-  version: "0.2.3"
+  version: "0.2.7"
 ---
 
 # Fix Review

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

@@ -3,7 +3,7 @@ name: go-style
 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.2.3"
+  version: "0.2.7"
 ---
 
 # Go Style

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

@@ -3,7 +3,7 @@ name: kratos
 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.2.3"
+  version: "0.2.7"
 ---
 
 # Kratos

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

@@ -3,7 +3,7 @@ name: plan
 description: "Creates bite-sized implementation plans from approved requirements, clarify output, or design specs with exact files, tests, commands, expected output, and execution handoff. Not for unresolved requirements, design decisions, PRD generation, or code changes."
 when_to_use: "plan, implementation plan, execution plan, task breakdown, approved requirements, approved design spec, docs/loopx/design, 实施计划, 执行计划, 任务拆分"
 metadata:
-  version: "0.2.3"
+  version: "0.2.7"
 argument-hint: "<design spec path or feature name>"
 ---
 

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

@@ -3,7 +3,7 @@ name: refactor-plan
 description: "Creates a behavior-preserving refactor plan with user interview, repo evidence, tiny commits, scope boundaries, and testing decisions. Not for feature changes or immediate implementation."
 when_to_use: "refactor-plan, refactor request, refactoring RFC, tiny commits, behavior-preserving cleanup, architecture cleanup, 重构计划"
 metadata:
-  version: "0.2.3"
+  version: "0.2.7"
 ---
 
 This skill will be invoked when the user wants to create a refactor request. You should go through the steps below. You may skip steps if you don't consider them necessary.

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

@@ -3,7 +3,7 @@ name: review
 description: "Dispatches a loopx code reviewer subagent against a concrete git range and requirements. Not for implementation, planning, or unresolved review scope."
 when_to_use: "request code review, completed task review, major feature review, pre-merge review, subagent code quality check"
 metadata:
-  version: "0.2.3"
+  version: "0.2.7"
 ---
 
 # Review

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

@@ -3,7 +3,7 @@ name: spec
 description: "Writes software design specs from already-clarified requirements, including solution approach, architecture outline, detailed design, tradeoffs, verification design, and handoff context. Not for unresolved requirements, PRD generation, implementation task planning, or code changes."
 when_to_use: "spec, design spec, technical design, design proposal, detailed design, architecture design, 设计方案, 概要设计, 详细设计, 技术方案"
 metadata:
-  version: "0.2.3"
+  version: "0.2.7"
 ---
 
 # loopx Spec

package/plugins/loopx/skills/subagent-exec/SKILL.md

@@ -3,7 +3,7 @@ name: subagent-exec
 description: "Executes approved loopx implementation plans with fresh subagents per independent task and staged review. Not for planning, unclear requirements, or tightly coupled edits."
 when_to_use: "approved implementation plan, independent tasks, subagent execution, staged spec review, code quality review, parallel-capable execution"
 metadata:
-  version: "0.2.3"
+  version: "0.2.7"
 ---
 
 # Subagent Exec
@@ -63,11 +63,13 @@ digraph process {
         "Mark task complete in update_plan" [shape=box];
     }
 
+    "Record finish baseline with loopx finish-start <slug> --source <plan-path>" [shape=box];
     "Read plan, extract all tasks with full text, note context, create update_plan" [shape=box];
     "More tasks remain?" [shape=diamond];
     "Use loopx:final-review for entire implementation" [shape=box];
     "Use loopx:finish" [shape=box style=filled fillcolor=lightgreen];
 
+    "Record finish baseline with loopx finish-start <slug> --source <plan-path>" -> "Read plan, extract all tasks with full text, note context, create update_plan";
     "Read plan, extract all tasks with full text, note context, create update_plan" -> "Dispatch implementer subagent (./implementer-prompt.md)";
     "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
     "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
@@ -89,6 +91,16 @@ digraph process {
 }
 ```
 
+### Step 0: Record Finish Baseline
+
+Before dispatching the first implementer, run:
+
+```bash
+loopx finish-start <slug> --source <plan-path>
+```
+
+Use the plan filename slug when no workflow slug is available. This preserves the starting `HEAD` so `finish-audit` can inspect `baseline..HEAD` even after implementers commit their work and the current `git diff` is empty.
+
 ## Model Selection
 
 Use the least powerful model that can handle each role to conserve cost and increase speed.

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

@@ -3,7 +3,7 @@ name: tdd
 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.2.3"
+  version: "0.2.7"
 ---
 
 # Test-Driven Development (TDD)

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

@@ -3,7 +3,7 @@ name: verify
 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.2.3"
+  version: "0.2.7"
 ---
 
 # Verification Before Completion

package/scripts/claude-workflow-hook.mjs

@@ -52,10 +52,59 @@ function findNearestLoopxRuntimeRoot(startCwd) {
   }
 }
 
+function archiveNextActionReplacement(state) {
+  const approvedReviewAction = approvedReviewNextAction(state);
+  if (approvedReviewAction) {
+    return approvedReviewAction;
+  }
+  if (state.current_stage === 'done' || state.current_stage === 'archive' || state.completion_confirmed === true) {
+    return '$finish';
+  }
+  return null;
+}
+
+function approvedReviewNextAction(state) {
+  if (state.current_stage === 'review' && state.review_verdict === 'approve' && state.slug) {
+    return `loopx approve ${state.slug} --from review --to done`;
+  }
+  return null;
+}
+
+function persistedNextAction(state) {
+  const action = typeof state?.recommended_next_action === 'string'
+    ? state.recommended_next_action.trim()
+    : '';
+  if (!action) {
+    return null;
+  }
+  if (/\bloopx\s+archive\b|\$archive\b/i.test(action)) {
+    return archiveNextActionReplacement(state);
+  }
+  return action;
+}
+
+function staleArchiveNextAction(state) {
+  const action = typeof state?.recommended_next_action === 'string'
+    ? state.recommended_next_action.trim()
+    : '';
+  if (!action || !/\bloopx\s+archive\b|\$archive\b/i.test(action)) {
+    return null;
+  }
+  return archiveNextActionReplacement(state);
+}
+
 function nextSkill(state) {
   if (!state?.slug) {
     return null;
   }
+  const staleArchiveAction = staleArchiveNextAction(state);
+  if (staleArchiveAction) {
+    return staleArchiveAction;
+  }
+  const approvedReviewAction = approvedReviewNextAction(state);
+  if (approvedReviewAction) {
+    return approvedReviewAction;
+  }
   if (state.current_stage === 'clarify') {
     return 'Use loopx:clarify until material questions are resolved, then route to loopx:spec or loopx:plan.';
   }
@@ -68,7 +117,7 @@ function nextSkill(state) {
   if (state.current_stage === 'review') {
     return 'Legacy runtime review detected. New v1 code review should use loopx:review.';
   }
-  return state.recommended_next_action || null;
+  return persistedNextAction(state);
 }
 
 try {

package/scripts/codex-workflow-hook.mjs

@@ -35,16 +35,8 @@ function nextSkill(state) {
     return `$plan ${state.slug}`;
   }
   if (state.current_stage === 'done'
-    && state.completion_confirmed === true
-    && state.archive_status !== 'archived') {
-    return `$archive ${state.slug}`;
-  }
-  if (state.current_stage === 'review'
-    && state.review_verdict === 'approve'
-    && state.pending_user_decision === 'review->done'
-    && ['requested', 'approved'].includes(state.approval?.complete)
-    && state.archive_status !== 'archived') {
-    return `$archive ${state.slug}`;
+    && state.completion_confirmed === true) {
+    return '$finish';
   }
   if (state.stage_status === 'awaiting-approval'
     && state.current_stage === 'plan'
@@ -103,6 +95,12 @@ function nextCli(state) {
     && state.plan_blockers.length === 0) {
     return `loopx build .loopx/plans/requirements-snapshot-${state.slug}.md`;
   }
+  if (state.current_stage === 'review'
+    && state.review_verdict === 'approve'
+    && state.pending_user_decision === 'review->done'
+    && ['requested', 'approved'].includes(state.approval?.complete)) {
+    return `loopx approve ${state.slug} --from review --to done`;
+  }
   if (state.current_stage === 'review'
     && state.review_verdict === 'request-changes'
     && state.rollback_target === 'build'
@@ -123,6 +121,29 @@ function nextCli(state) {
   return null;
 }
 
+function archiveNextActionReplacement(state) {
+  if (state.current_stage === 'review' && state.review_verdict === 'approve' && state.slug) {
+    return `loopx approve ${state.slug} --from review --to done`;
+  }
+  if (state.current_stage === 'done' || state.current_stage === 'archive' || state.completion_confirmed === true) {
+    return '$finish';
+  }
+  return null;
+}
+
+function persistedNextAction(state) {
+  const action = typeof state?.recommended_next_action === 'string'
+    ? state.recommended_next_action.trim()
+    : '';
+  if (!action) {
+    return null;
+  }
+  if (/\bloopx\s+archive\b|\$archive\b/i.test(action)) {
+    return archiveNextActionReplacement(state);
+  }
+  return action;
+}
+
 function blockers(state) {
   const values = [
     ...(Array.isArray(state.plan_blockers) ? state.plan_blockers : []),
@@ -161,9 +182,9 @@ function nextActionLine(state, workflow) {
     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 `finish clarification, then $plan ${state.slug || workflow}`;
   }
-  return nextSkill(state) || nextCli(state) || state.recommended_next_action || 'none';
+  return nextSkill(state) || nextCli(state) || persistedNextAction(state) || 'none';
 }
 
 function implementationGateLines(state) {

package/scripts/install-skills.mjs

@@ -2,17 +2,72 @@
 
 import { installSkillsForTargets, verifyInstallTargets } from '../src/install-discovery.mjs';
 
+function shouldSkipPostinstall(env = process.env) {
+  return env.LOOPX_SKIP_POSTINSTALL === '1' || env.LOOPX_POSTINSTALL === '0';
+}
+
+function skipPostinstallEnv(env = process.env) {
+  if (env.LOOPX_SKIP_POSTINSTALL === '1') {
+    return 'LOOPX_SKIP_POSTINSTALL';
+  }
+  if (env.LOOPX_POSTINSTALL === '0') {
+    return 'LOOPX_POSTINSTALL';
+  }
+  return null;
+}
+
+function targetNames(result) {
+  return Array.isArray(result.targets) && result.targets.length > 0 ? result.targets : Object.keys(result.results || {});
+}
+
+function count(result, key) {
+  return Object.values(result.results || {})
+    .reduce((sum, target) => sum + (Array.isArray(target?.[key]) ? target[key].length : 0), 0);
+}
+
+function printSummary(result, { checkOnly = false } = {}) {
+  console.log(`loopx ${checkOnly ? 'install check' : 'postinstall'}: ${result.ok === false ? 'attention needed' : 'ok'}`);
+  console.log(`targets: ${targetNames(result).join(', ')}`);
+  if (!checkOnly) {
+    console.log(`installed skills: ${count(result, 'installed')}`);
+  }
+  console.log(`conflicts: ${count(result, 'conflicts')}`);
+  console.log(`skipped user-modified: ${count(result, 'skipped')}`);
+  console.log('repair: loopx repair-install');
+  console.log('opt out: LOOPX_SKIP_POSTINSTALL=1');
+  console.log('disable hooks for one process: LOOPX_HOOKS=0');
+  console.log('details: node scripts/install-skills.mjs --json');
+}
+
 async function main() {
+  const json = process.argv.includes('--json');
+  if (shouldSkipPostinstall()) {
+    if (json) {
+      console.log(JSON.stringify({
+        ok: true,
+        skipped: true,
+        reason: 'postinstall_disabled',
+        env: skipPostinstallEnv(),
+      }, null, 2));
+    } else {
+      console.log('loopx postinstall skipped: LOOPX_SKIP_POSTINSTALL=1 or LOOPX_POSTINSTALL=0');
+    }
+    return;
+  }
+
   const checkOnly = process.argv.includes('--check');
   const result = checkOnly ? await verifyInstallTargets(process.env) : await installSkillsForTargets(process.env);
   const ok = checkOnly ? result.ok : result.ok !== false;
   const payload = checkOnly ? result : { ok, targets: result.targets, results: result.results };
+  if (json) {
+    const stream = ok ? process.stdout : process.stderr;
+    stream.write(`${JSON.stringify(payload, null, 2)}\n`);
+  } else {
+    printSummary(payload, { checkOnly });
+  }
   if (!ok) {
-    console.error(JSON.stringify(payload, null, 2));
     process.exitCode = 1;
-    return;
   }
-  console.log(JSON.stringify(payload, null, 2));
 }
 
 await main();

package/scripts/verify-skills.mjs

@@ -103,6 +103,16 @@ function assertContains(text, value, label) {
   assert.match(text, new RegExp(value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')), `${label} missing ${value}`);
 }
 
+function publicArchiveCommandLines(text) {
+  return text
+    .split('\n')
+    .filter((line) => /^\s*(?:(?:[-*+]|\d+[.)])\s+)?`?loopx archive(?:\s|`|$)/.test(line));
+}
+
+function assertNoPublicArchiveCommandExposure(text, label) {
+  assert.deepEqual(publicArchiveCommandLines(text), [], `${label} should not expose archive runtime command`);
+}
+
 async function assertPublicDocsAligned() {
   const readme = await readFile(join(repoRoot, 'README.md'), 'utf8');
   const readmeZh = await readFile(join(repoRoot, 'README.zh-CN.md'), 'utf8');
@@ -110,13 +120,10 @@ async function assertPublicDocsAligned() {
     'loopx install-skills',
     'loopx init',
     'loopx clarify',
-    'loopx approve',
-    'loopx plan',
-    'loopx build',
-    'loopx review',
-    'loopx autopilot',
     'loopx render',
     'loopx status',
+    'loopx next',
+    'loopx help advanced',
     'loopx setup-context',
     'loopx doctor',
     'loopx migrate',
@@ -127,8 +134,67 @@ async function assertPublicDocsAligned() {
     assertContains(readme, command, 'README.md');
     assertContains(readmeZh, command, 'README.zh-CN.md');
   }
-  assert.doesNotMatch(readme, /loopx archive/, 'README.md should not expose archive runtime command');
-  assert.doesNotMatch(readmeZh, /loopx archive/, 'README.zh-CN.md should not expose archive runtime command');
+  assert.deepEqual(
+    publicArchiveCommandLines([
+      'loopx archive <slug>',
+      '- loopx archive <slug>',
+      '- `loopx archive <slug>`',
+      '1. loopx archive <slug>',
+      'archive is not part of the public v1 finish flow. Older runtime state may still contain archive fields or a hidden `loopx archive <slug>` compatibility command.',
+    ].join('\n')),
+    [
+      'loopx archive <slug>',
+      '- loopx archive <slug>',
+      '- `loopx archive <slug>`',
+      '1. loopx archive <slug>',
+    ],
+    'archive command exposure guard should catch public command lines without rejecting prose compatibility notes',
+  );
+  assertNoPublicArchiveCommandExposure(readme, 'README.md');
+  assertNoPublicArchiveCommandExposure(readmeZh, 'README.zh-CN.md');
+  assertContains(readme, 'local audit ledger', 'README.md');
+  assertContains(readme, '.loopx/finish/<audit-id>/', 'README.md');
+  assert.match(readme, /`none` means|none means/i, 'README.md missing none means');
+  assertContains(readme, 'docs/loopx/specs/', 'README.md');
+  assertContains(readme, 'Advanced runtime commands', 'README.md');
+  assertContains(readme, 'loopx help advanced', 'README.md');
+  assertContains(readme, 'Undo installed files', 'README.md');
+  assertContains(readme, 'Golden path', 'README.md');
+
+  assertContains(readmeZh, '本地 audit ledger', 'README.zh-CN.md');
+  assertContains(readmeZh, '.loopx/finish/<audit-id>/', 'README.zh-CN.md');
+  assertContains(readmeZh, '`none` 表示', 'README.zh-CN.md');
+  assertContains(readmeZh, 'docs/loopx/specs/', 'README.zh-CN.md');
+  assertContains(readmeZh, '高级 runtime 命令', 'README.zh-CN.md');
+  assertContains(readmeZh, 'loopx help advanced', 'README.zh-CN.md');
+  assertContains(readmeZh, '撤销已安装文件', 'README.zh-CN.md');
+  assertContains(readmeZh, '黄金路径', 'README.zh-CN.md');
+  for (const required of [
+    'Quick start',
+    'Human output is the default',
+    'loopx install-skills --target all --dry-run',
+    'LOOPX_SKIP_POSTINSTALL=1',
+    'LOOPX_POSTINSTALL=0',
+    'LOOPX_HOOKS=0',
+    'Archive compatibility',
+  ]) {
+    assertContains(readme, required, 'README.md');
+  }
+  for (const required of [
+    '快速开始',
+    '默认输出面向人类',
+    'loopx install-skills --target all --dry-run',
+    'LOOPX_SKIP_POSTINSTALL=1',
+    'LOOPX_POSTINSTALL=0',
+    'LOOPX_HOOKS=0',
+    'Archive 兼容性',
+  ]) {
+    assertContains(readmeZh, required, 'README.zh-CN.md');
+  }
+  assert.doesNotMatch(readme, /`loopx install-skills --dry-run`/, 'README.md should use explicit dry-run target');
+  assert.doesNotMatch(readmeZh, /`loopx install-skills --dry-run`/, 'README.zh-CN.md should use explicit dry-run target');
+  assert.doesNotMatch(readme, /Public finish audit commands:/, 'README.md should not promote finish runtime commands as public primary flow');
+  assert.doesNotMatch(readmeZh, /公开的 finish audit 命令：/, 'README.zh-CN.md should not promote finish runtime commands as public primary flow');
 
   const releaseNotesRoot = join(repoRoot, 'docs', 'release-notes');
   const releaseNotes = existsSync(releaseNotesRoot)
@@ -179,6 +245,16 @@ async function assertSkill(skillName, resolverText) {
 assert.equal(pluginManifest.version, packageJson.version, 'plugin manifest version must match package.json');
 assert.equal(existsSync(resolverPath), true, 'skills/RESOLVER.md missing');
 assert.equal(packageJson.files.includes('scripts/claude-workflow-hook.mjs'), true, 'npm package must include claude-workflow-hook.mjs');
+assert.equal(packageJson.files.includes('skills/'), false, 'npm package must not include broad skills/ surface');
+assert.equal(packageJson.files.includes('skills/RESOLVER.md'), true, 'npm package must include skills/RESOLVER.md');
+for (const skillName of LOOPX_BUNDLED_SKILLS) {
+  assert.equal(packageJson.files.includes(`skills/${skillName}/`), true, `npm package missing bundled skill ${skillName}`);
+}
+assert.deepEqual(
+  packageJson.files.filter((path) => path.startsWith('skills/')).sort(),
+  ['skills/RESOLVER.md', ...LOOPX_BUNDLED_SKILLS.map((skillName) => `skills/${skillName}/`)].sort(),
+  'npm package skills/ surface must exactly match bundled skills plus resolver',
+);
 
 for (const relativePath of markdownPaths) {
   await assertMarkdownStructure(relativePath);

package/skills/RESOLVER.md

@@ -26,6 +26,7 @@ Read the selected skill file before acting. If multiple skills match, read every
 | Feature or bugfix implementation should be covered by a failing test first | `skills/tdd/SKILL.md` |
 | Bug, test failure, build failure, regression, unexpected behavior, root-cause investigation | `skills/debug/SKILL.md` |
 | Completion, fixed, passing, review-ready, commit, or handoff claims need fresh evidence | `skills/verify/SKILL.md` |
+| Document readability, PRD assessment, requirements gaps, unclear viewpoint, AI-like prose, or document rewriting | `skills/doc-readability/SKILL.md` |
 | Editing `.go` files or reviewing Go style | `skills/go-style/SKILL.md` |
 | Go-Kratos proto, service, biz, data, middleware, auth, config, or troubleshooting | `skills/kratos/SKILL.md` |
 
@@ -42,7 +43,8 @@ Read the selected skill file before acting. If multiple skills match, read every
 9. Use `fix-review` only after feedback exists.
 10. Use `finish` only after implementation, final review, and verification are complete.
 11. Use `refactor-plan` for behavior-preserving refactor planning. If the refactor changes external behavior or contracts, route to `clarify` or `spec`.
-12. Treat `tdd`, `debug`, `verify`, `go-style`, and `kratos` as support lenses unless the user explicitly invokes them directly.
+12. Use `doc-readability` for document assessment or rewriting, especially PRDs, requirements docs, specs, meeting notes, and AI-like prose. If the document is a source artifact for implementation, assess or rewrite it first, then route clarified implementation work back through `clarify`, `spec`, or `plan`.
+13. Treat `tdd`, `debug`, `verify`, `doc-readability`, `go-style`, and `kratos` as support lenses unless the user explicitly invokes them directly.
 
 ## Deterministic Guard
 

package/skills/clarify/SKILL.md

@@ -3,7 +3,7 @@ name: clarify
 description: "Grills ambiguous loopx work until material questions are answered, then routes to spec or plan using a design gate. Not for clear implementation tasks, approved specs, or code changes."
 when_to_use: "clarify, requirements, ambiguous request, unclear scope, non-goals, decision boundaries, acceptance criteria, 需求澄清, 范围不清"
 metadata:
-  version: "0.2.3"
+  version: "0.2.7"
 ---
 
 # loopx Clarify

package/skills/debug/SKILL.md

@@ -3,7 +3,7 @@ name: debug
 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.2.3"
+  version: "0.2.7"
 ---
 
 # Systematic Debugging