@ai-content-space/loopx 0.2.3 → 0.2.7

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

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.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/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/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/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/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>"
 ---