@ai-content-space/loopx 0.2.4 → 0.2.8

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

@@ -10,7 +10,7 @@ Read the selected skill file before acting. If multiple skills match, read every
 |---|---|
 | Ambiguous request, unclear scope, non-goals, decision boundaries, requirements interview | `skills/clarify/SKILL.md` |
 | Design方案, technical design, API/data/state/security decisions, or architecture tradeoffs | `skills/spec/SKILL.md` |
-| Approved requirements or design need a bite-sized implementation plan | `skills/plan/SKILL.md` |
+| Approved requirements or design need a bite-sized implementation plan | `skills/plan-to-exec/SKILL.md` |
 | Approved plan has independent tasks and should run with subagents plus staged review | `skills/subagent-exec/SKILL.md` |
 | Approved plan should run inline or without subagent-first execution | `skills/exec/SKILL.md` |
 | Completed task, major feature, or pre-merge work needs independent code review | `skills/review/SKILL.md` |
@@ -34,8 +34,8 @@ Read the selected skill file before acting. If multiple skills match, read every
 
 1. If intent, scope, non-goals, or decision boundaries are unresolved, use `clarify`.
 2. If remaining questions are product behavior, API, state, data, permission, migration, compatibility, or architecture decisions, use `spec`.
-3. If remaining questions are local implementation choices, use `plan`.
-4. `plan` writes `docs/loopx/plans/*.md` and then offers `subagent-exec` or `exec`.
+3. If remaining questions are local implementation choices, use `plan-to-exec`.
+4. `plan-to-exec` writes `docs/loopx/plans/*.md` and then offers `subagent-exec` or `exec`.
 5. Use `subagent-exec` when subagents are available and the plan has independent tasks.
 6. Use `exec` when the user chooses inline execution or subagents are unavailable.
 7. Use `review` to request code review of completed task or checkpoint work.
@@ -43,7 +43,7 @@ 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. 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`.
+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-to-exec`.
 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.4"
+  version: "0.2.8"
 ---
 
 # loopx Clarify
@@ -63,10 +63,10 @@ For `needs_spec`, immediately use the `spec` skill with the clarification contex
 Then stop before implementation planning and report:
 
 ```text
-$plan docs/loopx/design/<需求名>需求设计文档.md
+$plan-to-exec docs/loopx/design/<需求名>需求设计文档.md
 ```
 
-For `direct_to_plan`, hand off to the `plan` skill with the clarification context bundle as the source. `plan` writes:
+For `direct_to_plan`, hand off to the `plan-to-exec` skill with the clarification context bundle as the source. `plan-to-exec` writes:
 
 - `docs/loopx/plans/YYYY-MM-DD-<feature-name>.md`
 

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.4"
+  version: "0.2.8"
 ---
 
 # Systematic Debugging

package/skills/doc-readability/SKILL.md

@@ -3,7 +3,7 @@ name: doc-readability
 description: "Use when evaluating, rewriting, or editing documents for human readability, unclear viewpoints, AI-like prose, bloated specs, PRDs, requirements docs, meeting notes, strategy docs, or internal knowledge-base articles. Not for code review, implementation planning, or file-format conversion."
 when_to_use: "document readability, PRD assessment, requirements gaps, AI-like prose, unclear viewpoint, rewrite docs, editing docs, 文档可读性, 去AI味, 需求文档评估"
 metadata:
-  version: "0.2.4"
+  version: "0.2.8"
 ---
 
 # Doc Readability

package/skills/exec/SKILL.md

@@ -3,7 +3,7 @@ name: exec
 description: "Executes a written loopx implementation plan sequentially with review checkpoints. Not for unclear plans, missing requirements, or subagent-first execution."
 when_to_use: "written implementation plan, inline execution, sequential plan execution, review checkpoints, no subagent lane"
 metadata:
-  version: "0.2.4"
+  version: "0.2.8"
 ---
 
 # Exec
@@ -24,6 +24,16 @@ Load plan, review critically, execute all tasks, report when complete.
 3. If concerns: Raise them with your human partner before starting
 4. If no concerns: create update_plan and proceed
 
+### Step 1.5: Record Finish Baseline
+
+Before editing files or running the first task, 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` for finish learning/spec audit after the execution commits code.
+
 ### Step 2: Execute Tasks
 
 For each task:
@@ -70,7 +80,7 @@ After all tasks complete and verified:
 ## Integration
 
 **Required workflow skills:**
-- **loopx:plan** - Creates the plan this skill executes
+- **loopx:plan-to-exec** - Creates the plan this skill executes
 - **loopx:final-review** - Final whole-feature runtime and integration risk review
 - **loopx:fix-review** - Handles final-review feedback before finish
 - **loopx:finish** - Complete development after all tasks

package/skills/final-review/SKILL.md

@@ -3,7 +3,7 @@ name: final-review
 description: "Performs whole-feature review after implementation and staged task review. Not for per-task review, unresolved scope, implementation, or pure documentation polish."
 when_to_use: "final-review, final code review, whole feature review, integration review, pre-finish review, after subagent-exec, runtime risk review, 最终评审"
 metadata:
-  version: "0.2.4"
+  version: "0.2.8"
 ---
 
 # Final Review

package/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.4"
+  version: "0.2.8"
 ---
 
 # 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/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.4"
+  version: "0.2.8"
 ---
 
 # Fix Review

package/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.4"
+  version: "0.2.8"
 ---
 
 # Go Style

package/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.4"
+  version: "0.2.8"
 ---
 
 # Kratos

package/skills/{plan → plan-to-exec}/SKILL.md

@@ -1,13 +1,13 @@
 ---
-name: plan
+name: plan-to-exec
 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, 实施计划, 执行计划, 任务拆分"
+when_to_use: "plan-to-exec, plan, implementation plan, execution plan, task breakdown, approved requirements, approved design spec, docs/loopx/design, 实施计划, 执行计划, 任务拆分"
 metadata:
-  version: "0.2.4"
+  version: "0.2.8"
 argument-hint: "<design spec path or feature name>"
 ---
 
-# loopx Plan
+# loopx Plan-To-Exec
 
 ## Overview
 
@@ -23,7 +23,7 @@ Use this skill after requirements are clear. The source may be:
 
 Do not re-decide product or architecture. If the source is incomplete, contradictory, or missing product behavior, API, data, state, permission, migration, compatibility, or architecture decisions, return to `clarify` or `spec` instead of filling those gaps inside `plan`.
 
-**Announce at start:** "I'm using the plan skill to create the implementation plan."
+**Announce at start:** "I'm using the plan-to-exec skill to create the implementation plan."
 
 **Save plans to:** `docs/loopx/plans/YYYY-MM-DD-<feature-name>.md`
 

package/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.4"
+  version: "0.2.8"
 ---
 
 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/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.4"
+  version: "0.2.8"
 ---
 
 # Review

package/skills/spec/DESIGN_SPEC_TEMPLATE.md

@@ -299,13 +299,13 @@
 
 ### 10.5 Planning Handoff
 
-- `plan` 可以决定：
+- `plan-to-exec` 可以决定：
 - 必须返回 `spec` 的事项：
 - 必须返回 `clarify` 的事项：
 - 推荐下一步：
 
 ```text
-$plan docs/loopx/design/<需求名>需求设计文档.md
+$plan-to-exec docs/loopx/design/<需求名>需求设计文档.md
 ```
 
 ## 十一、QA

package/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.4"
+  version: "0.2.8"
 ---
 
 # loopx Spec
@@ -63,14 +63,14 @@ The Markdown spec must include these sections:
 - `十、排期与规划`
 - `十一、QA`
 
-The `十、排期与规划` section must include a `Planning Handoff` subsection stating what `plan` may decide without re-opening design and what must return to `clarify` or `spec`.
+The `十、排期与规划` section must include a `Planning Handoff` subsection stating what `plan-to-exec` may decide without re-opening design and what must return to `clarify` or `spec`.
 
 ## Handoff
 
 After the spec is complete, recommend:
 
 ```text
-$plan docs/loopx/design/<需求名>需求设计文档.md
+$plan-to-exec docs/loopx/design/<需求名>需求设计文档.md
 ```
 
-Use `plan` only after the design document is internally consistent and all material requirements questions are resolved.
+Use `plan-to-exec` only after the design document is internally consistent and all material requirements questions are resolved.

package/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.4"
+  version: "0.2.8"
 ---
 
 # 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.
@@ -271,7 +283,7 @@ Done!
 
 **Required workflow skills:**
 
-- **loopx:plan** - Creates the plan this skill executes
+- **loopx:plan-to-exec** - Creates the plan this skill executes
 - **loopx:review** - Code review template for reviewer subagents
 - **loopx:final-review** - Final whole-feature runtime and integration risk review
 - **loopx:finish** - Complete development after all tasks

package/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.4"
+  version: "0.2.8"
 ---
 
 # Test-Driven Development (TDD)

package/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.4"
+  version: "0.2.8"
 ---
 
 # Verification Before Completion