@ai-content-space/loopx 0.2.4 → 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.4",
+  "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.4",
+  "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.4"
+  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.4"
+  version: "0.2.7"
 ---
 
 # Systematic Debugging

package/plugins/loopx/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.7"
 ---
 
 # Doc Readability

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.4"
+  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.4"
+  version: "0.2.7"
 ---
 
 # Final Review

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

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

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

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

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

@@ -3,7 +3,7 @@ name: go-style
 description: "Applies loopx Go coding style for .go edits, tests, errors, context, naming, and interface boundaries. Not for non-Go code or Kratos-specific architecture by itself."
 when_to_use: "go-style, Go, golang, .go files, go tests, gofmt, idiomatic Go, Go style, Go 代码"
 metadata:
-  version: "0.2.4"
+  version: "0.2.7"
 ---
 
 # Go Style

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

@@ -3,7 +3,7 @@ name: kratos
 description: "Supports Go-Kratos microservices, proto/buf APIs, service/biz/data layers, middleware, auth, config, and troubleshooting. Not for generic Go style alone."
 when_to_use: "kratos, Go-Kratos, proto, buf, service layer, biz layer, data layer, middleware, auth, config, Kratos 微服务"
 metadata:
-  version: "0.2.4"
+  version: "0.2.7"
 ---
 
 # Kratos

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

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

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

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

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

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

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

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

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

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

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

@@ -3,7 +3,7 @@ name: tdd
 description: "Guides feature and bugfix implementation through a failing test before production code and red-green-refactor discipline. Not for generated files or throwaway prototypes."
 when_to_use: "tdd, failing test first, feature implementation, bugfix, regression test, red green refactor, 测试先行"
 metadata:
-  version: "0.2.4"
+  version: "0.2.7"
 ---
 
 # Test-Driven Development (TDD)

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

@@ -3,7 +3,7 @@ name: verify
 description: "Requires fresh verification evidence before claiming work is complete, fixed, passing, review-ready, or ready to commit. Not for speculative confidence or stale results."
 when_to_use: "verify, completion claim, fixed claim, tests pass, review-ready, commit, fresh evidence, 验证, 完成前检查"
 metadata:
-  version: "0.2.4"
+  version: "0.2.7"
 ---
 
 # Verification Before Completion

package/scripts/claude-workflow-hook.mjs

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

package/scripts/codex-workflow-hook.mjs

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

package/scripts/install-skills.mjs

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