@ai-content-space/loopx 0.2.3 → 0.2.7

package/docs/loopx/specs/installation.md

@@ -0,0 +1,33 @@
+# Installation And CLI Onboarding Spec
+
+This file records stable loopx product-surface rules for first-use CLI output, installer behavior, hook guidance, and packaged skill scope.
+
+## Human And JSON Output
+
+- `loopx --help` must start with a short quickstart path: install skills, init, clarify, status.
+- `loopx init`, `loopx doctor`, and `loopx install-skills` default to concise human output.
+- Full runtime payloads require explicit `--json`.
+- Commands in `--json` mode must not print interactive prompt text into stdout.
+
+## Archive Compatibility
+
+- `archive` is hidden compatibility, not part of the public v1 product flow.
+- Default help, README public command lists, next-step helpers, and workflow hooks must not recommend `loopx archive` or `$archive`.
+- If old persisted runtime state contains archive recommendations, hooks must replace them:
+  - done/archive/completed state -> `$finish`
+  - approved review state -> `loopx approve <slug> --from review --to done`
+
+## Installer Behavior
+
+- `loopx install-skills --dry-run` is read-only. It must not write skills, hooks, lock files, settings, or template hashes.
+- All-target dry-run summaries must render the follow-up command as `loopx install-skills --target all --yes`.
+- `--dir` is valid only with a single target. `--target all --dir <path>` must fail before writing files.
+- `loopx install-skills` must exit nonzero whenever its final payload has `ok: false`, in both human and JSON modes.
+- Postinstall opt-outs are `LOOPX_SKIP_POSTINSTALL=1` and `LOOPX_POSTINSTALL=0`.
+- Postinstall opt-out with `--json` must preserve JSON stdout.
+
+## Published Skill Surface
+
+- The package root `skills/` surface is exactly `skills/RESOLVER.md` plus the directories in `LOOPX_BUNDLED_SKILLS`.
+- Auxiliary root skill sources must not be published by explicit or broad `package.json.files` entries.
+- `scripts/verify-skills.mjs` and the package governance tests are the release gates for this surface.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-content-space/loopx",
   "type": "module",
-  "version": "0.2.3",
+  "version": "0.2.7",
   "description": "Skill-first workflow suite for agentic coding assistants",
   "repository": {
     "type": "git",
@@ -30,7 +30,23 @@
     "scripts/codex-workflow-hook.mjs",
     "assets/logo.svg",
     "src/",
-    "skills/",
+    "skills/RESOLVER.md",
+    "skills/clarify/",
+    "skills/debug/",
+    "skills/doc-readability/",
+    "skills/exec/",
+    "skills/final-review/",
+    "skills/finish/",
+    "skills/fix-review/",
+    "skills/go-style/",
+    "skills/kratos/",
+    "skills/plan/",
+    "skills/refactor-plan/",
+    "skills/review/",
+    "skills/spec/",
+    "skills/subagent-exec/",
+    "skills/tdd/",
+    "skills/verify/",
     "templates/",
     "plugins/loopx/",
     "!plugins/loopx/scripts/plugin-install.test.mjs"

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

@@ -1,6 +1,6 @@
 {
   "name": "loopx",
-  "version": "0.2.3",
+  "version": "0.2.7",
   "description": "Skill-first workflow suite for agentic coding assistants",
   "skills": "./skills/",
   "interface": {

package/plugins/loopx/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/plugins/loopx/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

package/plugins/loopx/skills/doc-readability/SKILL.md

@@ -0,0 +1,222 @@
+---
+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.7"
+---
+
+# Doc Readability
+
+## Principle
+
+Readable documents help a specific reader make a decision, execute work, or verify a claim with minimal reconstruction. Do not confuse readability with shortness or smooth prose. Preserve factual meaning, domain vocabulary, and useful specificity while removing noise.
+
+## First Move
+
+Read the actual document before judging it. If the document is a URL, cloud doc, wiki page, local file, PDF, or exported artifact, fetch or read the content with the appropriate available tool. If only an excerpt is provided, state that the assessment is based on the excerpt.
+
+Start by inferring:
+
+| Question | Why it matters |
+|---|---|
+| Who is the reader? | Reviewers, engineers, operators, executives, and future maintainers need different structures. |
+| What job must the document do? | PRDs, engineering specs, SOPs, decision memos, and general notes have different standards. |
+| What is the main claim? | If the claim is hard to state in one sentence, the document likely has a structure problem. |
+| What action should follow? | Readability is poor when the reader cannot tell what to do next. |
+
+If these are clear from the request and document, use them to make a recommendation. The document type still needs user confirmation unless the user explicitly asks for a quick assessment or says to use judgment.
+
+## Setup Flow
+
+User choices override inference. Support explicit inputs such as:
+
+```text
+Document type: engineering spec
+Reader: engineering reviewers
+Mode: assessment only
+Strictness: review-ready
+```
+
+Do not turn setup into a form. Use this order:
+
+1. Confirm document type first. If the user has not explicitly specified document type, ask Step 1 before evaluating. Do not proceed based only on inference.
+2. If the document appears to mix multiple types, ask which lens should be primary. Do not silently choose the primary type.
+3. After document type is chosen, read enough of the document to judge its actual condition: title, headings, first screen, conclusion, and key sections. For long documents, sample the main path and high-risk sections.
+4. Only after reading the document may the agent recommend an action mode. Do not recommend assessment-only, targeted suggestions, or rewrite before reading the document.
+5. Recommendations must be dynamic, based on the user request, chosen document type, document content, headings, visible structure, and previous user choices.
+6. Do not hard-code a default recommendation in the skill.
+7. If the user says "quick assessment", "use your judgment", "don't ask", or equivalent, proceed with inference and state assumptions.
+
+Ask setup questions sequentially:
+
+```text
+I want to confirm the document type. Based on the title and headings, I would treat this as "...", because ...
+
+Which document type should I use?
+1. Engineering spec / interface contract / rules document
+2. Requirements document / PRD
+3. Engineering design document
+4. SOP / operating procedure
+5. Decision memo
+6. Research / analysis document
+7. Meeting notes / discussion record
+8. Postmortem / RCA
+9. Project plan / roadmap
+10. General note / knowledge-base article
+```
+
+After the user chooses the type, read the document. Then decide whether action mode needs confirmation:
+
+```text
+I have read the document's main path. Given the chosen type and the document's actual condition, I recommend "...", because ...
+
+How should I handle it?
+1. Assessment only
+2. Assessment plus targeted improvement suggestions
+3. Assessment, then rewrite only if there are blocking issues
+4. Rewrite directly
+```
+
+Ask strictness only when it would change the result:
+
+```text
+Strictness will affect this assessment. I recommend "...", because ...
+
+Which strictness should I use?
+1. Usable for internal handoff
+2. Review-ready
+3. Publication-ready
+```
+
+If strictness is not worth asking, choose a sensible default and state it briefly.
+
+When the confirmed document type is `Requirements document / PRD`, read `references/prd.md` before assessment or rewrite. Use it to check requirement completeness and testability, not just prose clarity.
+
+## Document Types
+
+Use the document type to set the evaluation bar.
+
+| Type | Readability standard |
+|---|---|
+| Requirements / PRD | Reader can identify problem, users, goals, non-goals, scope, workflows, requirements, acceptance criteria, priorities, and open questions. Also read `references/prd.md` for PRD-specific completeness checks. |
+| Engineering design | Reader can identify context, proposed design, key decisions, rejected alternatives, contracts, data flow, failure modes, rollout, and boundaries. |
+| Engineering spec / interface contract / rules document | Reader can identify the first-screen conclusion, main decision path, canonical rules, field/status definitions, and where details live. Long tables, enum lists, field contracts, state tables, and long sections are acceptable when they are locatable and support implementation. Judge clarity of path and lookup, not shortness. |
+| SOP / operating procedure | Reader can identify trigger, owner, prerequisites, step order, checks, exceptions, and escalation path. |
+| Decision memo | Reader can identify recommendation, rationale, tradeoffs, risks, decision owner, and next action. |
+| Research / analysis | Reader can identify question, method, evidence, conclusion, confidence, limitations, and implications. |
+| Meeting notes / discussion record | Reader can identify decisions, unresolved questions, owners, due dates, and context needed later. |
+| Postmortem / RCA | Reader can identify impact, timeline, root cause, contributing factors, fixes, owners, and prevention checks. |
+| Project plan / roadmap | Reader can identify objective, milestones, dependencies, owners, risks, dates, and decision points. |
+| General note / knowledge-base article | Reader can identify topic, takeaway, section map, and why each section exists. |
+
+If a document mixes types, name the primary and secondary type. Judge the primary reading path first; suggest moving secondary material to an appendix or companion doc only when it interferes with the main job.
+
+## Diagnostic Rubric
+
+Evaluate across these dimensions:
+
+| Dimension | Good | Poor |
+|---|---|---|
+| Viewpoint | The document makes defensible claims and repeats them consistently. | It lists related facts without choosing what matters. |
+| Reader path | The reader can predict where conclusions, rules, examples, and details live. | Background, rules, fields, cases, and tasks are mixed together. |
+| Information hierarchy | Important decisions appear first; details support them. | Long tables and sections force the reader to synthesize conclusions manually. |
+| Actionability | Owners, timing, inputs, outputs, states, and exceptions are concrete. | Sentences say "support", "process", "handle", or "optimize" without operational meaning. |
+| Density | Each paragraph changes what the reader knows or can do. | Repeated sentence frames and generic transitions create drag. |
+| Boundary clarity | Scope, non-goals, risks, blockers, and "not automatic" rules are explicit. | Boundaries are scattered, softened, or buried after implementation detail. |
+| Human voice | The prose shows judgment, tradeoffs, and emphasis. | The prose is neutral, padded, symmetric, and unwilling to choose. |
+
+Lead with a practical verdict in the user's language: `Readable`, `Partly readable`, or `Hard to read`.
+
+Separate findings by severity:
+
+| Severity | Meaning |
+|---|---|
+| Blocking | The target reader cannot understand the conclusion, decision path, required action, or authoritative rule. This usually requires restructuring or rewriting. |
+| Important | The document is usable, but readers will waste time or may implement inconsistently. Recommend focused changes. |
+| Optional | The document can be improved, but the issue does not block review or execution. Do not present optional polish as readability failure. |
+
+For an already rewritten or structured document, use this severity split instead of listing every possible flaw as a main obstacle.
+
+## AI-Like Smells
+
+Treat these as signals to tighten or restructure:
+
+- Broad openings like "This document is used to..." without a decision.
+- Repeated section patterns that say the same thing for every case.
+- Tables whose cells are long paragraphs.
+- Grammatically parallel bullets that are not intellectually prioritized.
+- Generic terms like `support`, `process`, `optimize`, `capability`, `workflow`, `closed loop`, `improve`, `ensure`.
+- Every section ending with "notes" that restate prior content.
+- Long chains of "need to / can / generate / receive / process" without owner, timing, or output.
+- Balanced summaries that avoid saying "do this", "do not do this", or "this is the rule".
+
+Do not remove domain terms merely because they are technical. Remove vagueness, not expertise.
+
+## Rewrite Strategy
+
+Choose structure by document job:
+
+| Job | Preferred shape |
+|---|---|
+| Requirements / PRD | Problem -> users -> goals/non-goals -> scope -> workflows -> requirements -> acceptance criteria -> open questions |
+| Engineering design | Context -> decision -> architecture -> alternatives -> contracts -> data flow -> failure modes -> rollout |
+| Engineering spec / contract / rules | Conclusion -> hard rules -> decision path -> canonical definitions -> field/status contracts -> examples -> appendix |
+| SOP | Trigger -> owner -> prerequisites -> steps -> checks -> exceptions -> escalation |
+| Decision memo | Verdict -> decisions -> tradeoffs -> risks -> next action -> appendix |
+| Research / analysis | Question -> method -> evidence -> findings -> confidence -> limitations -> implications |
+| Meeting notes | Context -> decisions -> action items -> open questions -> reference notes |
+| Postmortem / RCA | Impact -> timeline -> root cause -> contributing factors -> fixes -> prevention |
+| General note / KB | Orientation -> key takeaway -> section map -> details |
+
+For long documents, do not polish in place first. Extract the spine:
+
+1. One-sentence main claim.
+2. Three to seven decisions or rules.
+3. Who owns each action.
+4. Which details belong in appendix/reference.
+5. Which repeated sections can share one template.
+
+Then rewrite only within the user-approved action mode.
+
+## Output Rules
+
+Match the user's requested mode. Use natural headings in the user's language. Do not expose rigid labels like `Main claim I extracted`, `Main reading obstacles`, or `Rewritten version` unless the user asks for a machine-readable template.
+
+For assessment, cover:
+
+- Chosen or inferred setup.
+- Readability verdict.
+- Core viewpoint extracted from the document.
+- Blocking issues, important improvements, and optional polish.
+- Whether rewrite is recommended.
+
+Rewrite control:
+
+- If mode is `assessment only`, do not output a rewritten version. State whether rewrite is recommended.
+- If mode is `assessment plus targeted suggestions`, provide focused changes, not a full rewrite.
+- If mode is `rewrite only if blocking`, provide a rewritten version only when blocking issues exist.
+- If mode is `rewrite directly`, rewrite directly with a short diagnosis first.
+- For long documents, rewrite the most important section first unless the user explicitly asks for the full document.
+
+## Editing Rules
+
+- Lead with conclusions and rules before explanation.
+- Prefer prose over a table when table cells become paragraphs.
+- Split source-of-truth rules from implementation details.
+- Make negative rules explicit: "do not auto-post cash", "do not rewrite historical trades", "do not send Plan before confirmation".
+- Replace repeated prose with one shared rule plus event-specific exceptions.
+- Keep strong domain nouns, exact dates, fields, statuses, and enumerations.
+- Preserve real uncertainty, but name what is unknown and who resolves it.
+- Remove performative transitions unless they add structure.
+- Do not make formal documents chatty. Human writing means judgment and economy, not casual tone.
+
+## Final Check
+
+Before claiming the document is improved, verify:
+
+- The main claim is visible in the first screen or first section.
+- A new reader can state the next action after reading the conclusion.
+- Repeated content has been collapsed or justified.
+- Boundaries and non-goals are not buried.
+- Any removed text was redundant, not a lost requirement.

package/plugins/loopx/skills/doc-readability/references/prd.md

@@ -0,0 +1,269 @@
+# PRD Readability and Completeness
+
+Use this reference only when the confirmed document type is `Requirements document / PRD`, or when the user explicitly asks to evaluate a document as a PRD.
+
+## Core Standard
+
+A PRD is readable only if it lets reviewers decide whether the product should be built and lets designers, engineers, QA, operations, and stakeholders understand what must be delivered. For PRDs, readability includes requirement completeness, not just prose clarity.
+
+## Required Checks
+
+Check the PRD across these areas:
+
+| Area | What must be clear |
+|---|---|
+| Problem | What problem exists, who has it, why it matters now, and what current workaround or failure it replaces. |
+| Goal | What outcome this release must achieve, and how success will be judged. |
+| Non-goals | What is explicitly out of scope, deferred, or intentionally unsupported. |
+| Users / roles | Which user roles exist, what each role can see or do, and which role owns each decision or operation. |
+| Scope and priority | What is MVP / phase-one / required, what is optional, and what is future work. |
+| Workflow | Trigger, preconditions, main path, branch paths, exception paths, and terminal states. |
+| Functional requirements | Inputs, outputs, state changes, permissions, validation, dependencies, and failure handling. |
+| Business rules | Who evaluates the rule, using which fields, at what time, and what happens when the rule fails. |
+| Page / operation behavior | Entry point, displayed fields, action buttons, enable/disable conditions, submit validation, success/failure feedback, and audit logs. |
+| Data / integration | Source systems, target systems, required fields, idempotency, versioning, retries, and consistency expectations. |
+| Acceptance criteria | Testable Given/When/Then-style outcomes or equivalent concrete verification criteria. |
+| Open questions | Unknowns, decision owners, deadlines, and whether they block delivery. |
+
+## Detail Gap Patterns
+
+Flag these as PRD detail gaps, even if the prose is readable:
+
+- A feature says `support`, `process`, `identify`, `generate`, `sync`, `notify`, `confirm`, or `handle`, but does not define input, output, owner, timing, or terminal state.
+- A workflow lists stages but omits trigger, precondition, branch conditions, exception handling, or completion criteria.
+- A status is named but its transitions, allowed actions, owner, or exit condition are missing.
+- A page lists fields but omits action behavior, button availability, validation, empty states, errors, permissions, or logs.
+- A rule describes intent but not the exact field, calculation, priority, source of truth, or conflict handling.
+- A Plan / task / event is generated, but the recipient, payload, idempotency, retry, cancellation, and failure handling are unclear.
+- A dependency is mentioned but its contract, SLA, missing-data behavior, or fallback is undefined.
+- A requirement cannot be tested because it lacks concrete examples or acceptance criteria.
+
+## Ambiguity Probes
+
+Use these probes to expose unclear requirements. Do not ask all of them to the user; use them to inspect the document and report the gaps that matter.
+
+### Feature Scope
+
+- What exactly does `support X` include and exclude?
+- What is the minimum acceptable behavior for phase one?
+- Is this automatic, manual, or semi-automatic?
+- Who can trigger it, and from where?
+- What happens if the user starts but does not finish?
+- What behavior is intentionally not supported?
+- What is the smallest shippable version of the feature?
+- Which users, accounts, markets, regions, products, channels, or data types are included?
+- Which cases are explicitly excluded even if they look similar?
+- Does "support" mean display only, calculate, persist, send, execute, reconcile, notify, or audit?
+- Does the requirement apply to historical data, only new data, or both?
+- Is there a migration, backfill, or cleanup requirement?
+
+### Actors and Ownership
+
+- Which role owns each decision, confirmation, correction, and exception?
+- Which actions are system actions, user actions, operator actions, or downstream-system actions?
+- Who is allowed to override system output?
+- Who reviews or approves high-risk actions?
+- Who is notified when something is blocked, failed, revised, or completed?
+- Who owns manual follow-up when automation cannot continue?
+
+### Workflow and State
+
+- What triggers the workflow?
+- What preconditions must be true?
+- What is the happy path?
+- What branches exist and what condition selects each branch?
+- What are the terminal states?
+- Which states allow edit, retry, cancel, ignore, approve, reject, archive, or rollback?
+- Who owns each state transition?
+- What happens when two events, tasks, or users act on the same object concurrently?
+- What is the first state after creation?
+- What is the difference between draft, pending, confirmed, sent, failed, completed, archived, ignored, or cancelled?
+- Which transitions are automatic and which require user action?
+- Are any transitions irreversible?
+- What events reopen or revise a completed item?
+- What stale states require timeout handling or escalation?
+- What should the system do if a workflow is interrupted mid-step?
+
+### Timing and Snapshot
+
+- Which date or time controls eligibility, calculation, display, execution, and notification?
+- Is the date in user timezone, market timezone, system timezone, or source-system timezone?
+- What snapshot is used for positions, balances, orders, customers, permissions, or source data?
+- Can the snapshot be regenerated? If yes, does it replace or version prior results?
+- What happens if source data arrives late, is revised, or is cancelled?
+- What is the cutoff time for each action?
+- What is allowed before cutoff, after cutoff, and after execution?
+
+### Data and Rules
+
+- What is the source of truth for each important field?
+- Which field is required, optional, calculated, derived, or manually entered?
+- What is the rule priority when multiple rules match?
+- What happens when source systems disagree?
+- What happens when required data is missing, stale, duplicated, revised, or cancelled?
+- Are historical values preserved when current effective values change?
+- Is there versioning, and which version is current?
+- What is the unique key for deduplication?
+- Which fields are immutable after creation?
+- Which fields can be manually corrected, and how are original/system/manual/effective values preserved?
+- What validation prevents invalid combinations?
+- What precision, rounding, currency, unit, or formatting rule applies?
+- What happens when two rules produce different outputs?
+- What is the conflict priority between source data, manual confirmation, downstream return, and recalculation?
+- Is the rule evaluated per user, per account, per task, per event, per order, or per item?
+
+### Page and Operation Behavior
+
+- Where is the entry point?
+- What fields are visible by default, and what is hidden behind details?
+- Which actions are available in each status?
+- What disables an action button?
+- What validation runs before submit?
+- What confirmation, warning, or preview is shown before an irreversible operation?
+- What success, failure, partial-success, retry, and timeout feedback does the user see?
+- What audit log is written?
+- What filters, sorting, grouping, search, export, or bulk actions are required?
+- What empty, loading, error, no-permission, and no-data states are shown?
+- What fields are editable, read-only, calculated, or drill-down only?
+- What happens when a user edits data that has already changed in the background?
+- What is the behavior for batch selection, partial selection, and disabled rows?
+- What is the exact result of save, submit, approve, reject, retry, ignore, archive, cancel, rollback, or resend?
+- Does the user need a preview of generated output before sending?
+
+### Integration and Execution
+
+- Who receives generated tasks, events, Plans, notifications, or files?
+- What payload is sent?
+- What idempotency key or duplicate-prevention rule exists?
+- What is retryable and what requires manual intervention?
+- What happens on partial success?
+- What happens if the downstream system accepts the request but later reports failure?
+- What cancellation, correction, reversal, or compensation path exists?
+- Is execution synchronous, asynchronous, scheduled, or manual?
+- What acknowledgement does the upstream system need?
+- What return payload is expected?
+- What retry policy applies: count, interval, backoff, manual retry, or no retry?
+- What makes a request idempotent?
+- How are duplicate sends, duplicate callbacks, or out-of-order callbacks handled?
+- What monitoring, alerting, or reconciliation is required?
+- What should happen when integration is unavailable but users continue operating?
+
+### Permissions and Risk
+
+- Who can view, create, edit, approve, send, retry, cancel, or archive?
+- Which operations require dual review or elevated permission?
+- What is the blast radius of a wrong operation?
+- What guardrails prevent sending incomplete, stale, or unconfirmed data?
+- What must be recoverable from logs?
+- Which fields or actions are sensitive?
+- Which roles can see customer-level, account-level, financial, or operational details?
+- Is approval required before customer-facing or financially impactful actions?
+- What is the rollback or compensation path for wrong execution?
+- What operational dashboard or report proves the feature is healthy?
+- What audit evidence must be retained for compliance or customer support?
+
+### Notifications and External Visibility
+
+- Who receives notifications: internal operators, downstream teams, customers, support, or all?
+- What triggers notification creation?
+- What template, channel, language, and timing are required?
+- What fields are shown to customers versus internal users?
+- What happens if notification delivery fails?
+- Can notifications be resent, corrected, suppressed, or cancelled?
+- What customer support or audit view is needed after notification?
+
+## Acceptance Criteria Patterns
+
+When a requirement is vague, propose a testable acceptance shape. Use domain language from the document.
+
+```text
+Given [precondition / status / role / data]
+When [user action / system trigger / external event]
+Then [observable result / state change / generated output]
+And [audit / notification / error / retry behavior]
+```
+
+Include acceptance coverage for:
+
+- Happy path.
+- Missing or invalid input.
+- Permission denied.
+- Duplicate submission or duplicate event.
+- External dependency failure.
+- Partial success.
+- Revised or cancelled source data.
+- No impacted users / empty result.
+- Manual override.
+- Audit and traceability.
+
+For page requirements, check:
+
+```text
+Given [task status and user role]
+When [page opens or action is clicked]
+Then [fields/actions visible]
+And [disabled/enabled conditions]
+And [validation / feedback / log behavior]
+```
+
+For rules, check:
+
+```text
+Given [source data and priority conditions]
+When [rule evaluation runs]
+Then [selected result]
+And [fallback or conflict result]
+```
+
+## PRD Severity
+
+Use this severity model in addition to the main skill's severity model:
+
+| Severity | Meaning |
+|---|---|
+| Blocking requirement gap | A builder or reviewer cannot know what to implement, test, approve, or operate. |
+| Important requirement gap | The requirement is implementable only with assumptions; different readers may implement it differently. |
+| Optional refinement | The requirement is understandable, but examples, wording, or organization could reduce review effort. |
+
+Do not label every missing detail as blocking. A missing detail is blocking only if implementation, testing, or review would require guessing.
+
+## PRD Output Requirement
+
+When assessing a PRD, include a section for requirement detail gaps. Use natural headings in the user's language. Cover:
+
+- The gap.
+- Why it affects delivery or review.
+- What question must be answered or what detail must be added.
+- A suggested acceptance or clarification shape when useful.
+
+Example shape:
+
+```text
+Requirement detail gaps:
+- [Gap]: ...
+  Impact: ...
+  Need to clarify: ...
+  Suggested acceptance shape: ...
+```
+
+## Rewrite Guidance for PRDs
+
+When rewriting a PRD, prefer this structure:
+
+```text
+1. Summary
+2. Background / problem
+3. Goals and non-goals
+4. Users and roles
+5. Scope and priorities
+6. Core workflows
+7. Functional requirements
+8. Rules and edge cases
+9. Page / operation requirements
+10. Data and integration requirements
+11. Acceptance criteria
+12. Open questions
+13. Appendix
+```
+
+Keep implementation contracts in the PRD only when they are needed for product review. Move exhaustive field tables, enum lists, API payloads, and state-machine details to appendices or companion engineering specs when they interrupt the product decision path.

package/plugins/loopx/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.3"
+  version: "0.2.7"
 ---
 
 # 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:

package/plugins/loopx/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.3"
+  version: "0.2.7"
 ---
 
 # Final Review