@nebutra/next-unicorn-skill 1.0.7 → 1.0.8

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.8] - 2026-02-09
+
+### Added
+
+- **Human-in-the-loop Gate Protocol** — 4 explicit decision gates at irreversible, preference-driven, or costly decision points:
+  - Gate 1: Triage detections before Context7 verification (saves quota)
+  - Gate 2: Code organization preferences with SWOT analysis (team preferences)
+  - Gate 3: Accept/reject/defer recommendations (migration cost decisions)
+  - Gate 4: Confirm before PR creation and file migration (irreversible actions)
+- New `references/code-organization-workflow.md` — progressive disclosure reference with Gate examples, Phase A/B decision tree, and worked examples
+
+### Changed
+
+- SKILL.md refactored from 400 to 188 lines — verbose Gate/code-org examples extracted to references/ per progressive disclosure spec
+- Removed stale `org-mixed-export-style` reference from Phase A (pattern was moved to structural analyzer)
+- Gate Protocol compressed from 35 lines to 8 lines (meta-info)
+- All instructions converted to imperative voice per skill spec
+
 ## [1.0.7] - 2026-02-09
 
 ### Added

package/SKILL.md

@@ -25,6 +25,17 @@ Scanner (deterministic)          →  AI Agent (generative)           →  Pipel
 **Design constraints**:
 - No hardcoded library recommendations — evaluate project context dynamically
 - Two analysis modes: **replacement** (hand-rolled code found) and **gap** (capability missing entirely)
+- **Human-in-the-loop**: 4 gates at irreversible, preference-driven, or costly decision points
+
+## Gate Protocol
+
+Present structured choices at gates. NEVER skip or proceed without user response.
+
+**Format** — table of findings/options + lettered choices + your recommendation with 1-sentence rationale. For high-impact gates, add a SWOT table. See `references/code-organization-workflow.md` for full Gate examples.
+
+**Rules**:
+- If user says "do it all automatically", ask "confirm skip ALL gates?" first
+- After user decides, execute automatically and report results with rollback instructions
 
 ## Standard Operating Procedure
 
@@ -39,138 +50,81 @@ Run `scanCodebase(input)`. The scanner:
 1. Detect workspace roots for monorepo support
 2. Match code against 30+ domain patterns (i18n, auth, state-management, code-organization, etc.)
 3. Run structural analysis: design system layers (monorepo), code organization (all projects)
-4. Record each detection with: file path, line range, pattern category, confidence score, domain
-5. Return `ScanResult` with:
+4. Return `ScanResult` with:
    - `detections` — hand-rolled code patterns found
    - `structuralFindings` — architectural + code organization issues
    - `codeOrganizationStats` — project-wide metrics (file counts, naming conventions, circular dep count)
    - `workspaces` — monorepo workspace info
 
-Detections and findings contain no recommendations — only facts. The AI agent interprets them.
-
-### Step 2.5: Gap Analysis (AI Agent)
-
-Beyond scanner detections, analyze what the project is **missing entirely**. Inspect:
+Detections and findings contain no recommendations — only facts.
 
-1. **Installed dependencies** — identify low-level tools that should be upgraded to platform-level solutions
-2. **Monorepo structure** — identify missing architectural layers (e.g., shared token package, shared config preset)
-3. **Cross-cutting concerns** — identify absent capabilities: structured logging, error monitoring, rate limiting, event-driven workflows, transactional email, type-safe API layer
-4. **Architecture patterns** — identify opportunities for multi-package solutions (e.g., design-tokens → tailwind-config → ui three-layer architecture for design systems)
+### GATE 1: Triage Detections
 
-Analyze at three levels of depth:
-- **Single library gap**: missing one tool (e.g., no form validation library)
-- **Ecosystem gap**: missing a coordinated set of tools (e.g., no observability stack)
-- **Architecture gap**: missing an entire structural layer (e.g., no design system, no shared config)
+**Why**: Each accepted detection costs a Context7 verification call. False positives waste quota.
 
-Provide each gap as a `GapRecommendation`. Read `src/index.ts` for the interface. Pass gaps via the `gaps` option in `analyze()`.
+Present scan results as a triage table with columns: #, Domain, Pattern, File, Confidence, Action. Offer options: (A) accept all, (B) skip specific numbers, (C) high-confidence only. See `references/code-organization-workflow.md#gate-1-triage-example` for format.
 
-**Design system gaps** — Two paths depending on project maturity:
-- **No existing frontend**: Scaffold from reference repos. Read `references/design-system-sources.md` for curated sources and sparse-checkout workflow.
-- **Existing frontend without formal design system**: First extract the spec (audit → tokens → classify → document) via `references/design-system-extraction.md`, then implement the architecture via `references/design-system-sources.md`.
+Wait for user response. Proceed with accepted detections only.
 
-### Step 2.7: Code Organization Analysis
-
-#### Phase A — Deterministic: Collect facts (MUST use tools, DO NOT estimate)
+### Step 2.5: Gap Analysis (AI Agent)
 
-You cannot infer file counts, naming conventions, or import cycles from knowledge. You MUST read the filesystem.
+Analyze what the project is **missing entirely**:
 
-**If using the npm library** — `scanResult.structuralFindings` and `scanResult.codeOrganizationStats` already contain all findings. Skip to Phase B.
+1. **Installed dependencies** — low-level tools that should be upgraded to platform-level solutions
+2. **Monorepo structure** — missing architectural layers (e.g., shared token package, shared config preset)
+3. **Cross-cutting concerns** — absent capabilities: structured logging, error monitoring, rate limiting, transactional email, type-safe API layer
+4. **Architecture patterns** — opportunities for multi-package solutions (e.g., design-tokens → tailwind-config → ui)
 
-**If not using the npm library** — run these shell commands to collect facts:
+Analyze at three levels: **single library gap**, **ecosystem gap**, **architecture gap**.
 
-```bash
-# 1. God directories: find directories with >15 source files
-find src -type d -exec sh -c 'count=$(find "$1" -maxdepth 1 -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) | wc -l); [ "$count" -gt 15 ] && echo "$1: $count files"' _ {} \;
+Provide each gap as a `GapRecommendation`. Read `src/index.ts` for the interface.
 
-# 2. Mixed naming: list filenames per directory for manual inspection
-ls -1 src/components/  # check if kebab-case and camelCase are mixed
+**Design system gaps** — two paths:
+- **No existing frontend**: Read `references/design-system-sources.md` for curated repos and sparse-checkout workflow.
+- **Existing frontend**: Read `references/design-system-extraction.md` for extraction workflow, then `references/design-system-sources.md` for implementation.
 
-# 3. Deep nesting: find directories >5 levels deep from src/
-find src -mindepth 6 -type d
+### Step 2.7: Code Organization Analysis
 
-# 4. Barrel bloat: count re-exports in index files
-grep -c "export.*from" src/**/index.ts
+#### Phase A — Collect facts (MUST use tools, DO NOT estimate)
 
-# 5. Catch-all directories: count files in utils/helpers/shared
-find src/utils src/helpers src/shared src/common src/lib -maxdepth 1 -type f 2>/dev/null | wc -l
+You cannot infer file counts, naming conventions, or import cycles from knowledge. You MUST read the filesystem.
 
-# 6. Circular dependencies: use npx if madge is not installed
-npx madge --circular --extensions ts,tsx src/
+**If using the npm library** — `scanResult.structuralFindings` and `scanResult.codeOrganizationStats` already contain all findings. Skip to Phase B.
 
-# 7. Deep relative imports: find ../../../ patterns
-grep -rn "from ['\"]\.\.\/\.\.\/\.\.\/" src/ --include="*.ts" --include="*.tsx"
-```
+**If not** — run the shell commands in `references/code-organization-workflow.md#phase-a-shell-commands-for-collecting-facts`.
 
 Record each finding with: **directory/file path, count, type**. These are facts.
 
-#### Phase B — Generative: Recommend solutions (use your knowledge + Context7)
-
-For each finding from Phase A, apply the decision tree below. **Do NOT recommend tools without Context7 verification.**
-
-| Finding type | You MUST do | You MUST NOT do |
-|---|---|---|
-| `god-directory` | Read the files in that dir, group by domain, recommend split. Reference: Next.js App Router colocation, Linear feature-packages. | Guess file count. Say "probably too many files." |
-| `mixed-naming-convention` | Check project framework → pick ONE convention. Next.js pages=kebab, React components=PascalCase, utils=camelCase. | Recommend "both are fine." Must pick one. |
-| `deep-nesting` | Recommend `@/` path aliases. Read `tsconfig.json` to check if paths already exist. Generate the config change. | Say "consider flattening" without generating the actual config. |
-| `barrel-bloat` | Recommend direct imports or namespace imports. Context7 verify `knip` for dead export detection. | Ignore it. Barrel bloat causes tree-shaking failures. |
-| `catch-all-directory` | Read the actual files, group by domain (date, string, validation, etc.), recommend specific directory structure. | Say "split by concern" without reading what's actually in the files. |
-| `circular-dependency` | Read the files in the cycle, understand WHY they import each other, recommend dependency inversion or extract shared module. Context7 verify `eslint-plugin-import`. | Just say "remove circular deps." Must explain the refactoring. |
-| `org-deep-relative-import` | Same as `deep-nesting` — recommend path aliases. | Skip it. |
-| `org-barrel-reexport-wildcard` | Recommend named re-exports `export { X } from` instead of `export *`. Explain namespace pollution risk. | Ignore it. |
-| `org-catch-all-utils-import` | Same as `catch-all-directory` — recommend domain-specific modules. | Skip it. |
-
-#### Phase B examples
-
-**Example 1 — god-directory finding**:
-```
-Fact: src/components/ has 23 source files
-```
-Read those 23 files. You find: Button, Card, Modal, Table, Form, Input, Select, Checkbox...
+#### Phase B — Recommend solutions (use your knowledge + Context7)
 
-Recommend:
-```
-src/components/
-├── ui/          ← primitives (Button, Input, Select, Checkbox)
-├── data/        ← data display (Table, Card, DataGrid)
-├── overlay/     ← overlays (Modal, Dialog, Drawer, Tooltip)
-└── form/        ← form elements (Form, FormField, FormError)
-```
-Reference: shadcn/ui organizes by interaction type. Radix UI uses similar grouping.
+For each finding, apply the MUST do / MUST NOT do decision tree in `references/code-organization-workflow.md#phase-b-decision-tree`. Do NOT recommend tools without Context7 verification.
 
-**Example 2 — circular-dependency finding**:
-```
-Fact: src/auth/session.ts → src/db/user.ts → src/auth/session.ts
-```
-Read both files. You find: `session.ts` imports `getUserById`, `user.ts` imports `getSession` for auth checks.
+For worked examples showing the full Fact → Read → Recommend flow, see `references/code-organization-workflow.md#phase-b-worked-examples`.
 
-Recommend: Extract `src/auth/types.ts` with shared interfaces. Both files import from types instead of each other. Context7 verify `eslint-plugin-import/no-cycle`.
+**Skip rules** — skip a finding if:
+- Directory is in `tests/`, `__tests__/`, `__mocks__/`, `fixtures/`, `generated/`, `.storybook/`
+- File is auto-generated (has `// @generated` or `/* eslint-disable */` at top)
+- Directory has <3 files (too few to judge)
 
-**Example 3 — mixed-naming finding**:
-```
-Fact: src/utils/ has kebab-case (5 files) + camelCase (3 files)
-```
-Check package.json → framework is Next.js → convention is kebab-case for files.
+### GATE 2: Code Organization Preferences
 
-Recommend: Rename the 3 camelCase files. Context7 verify `eslint-plugin-unicorn/filename-case` for CI enforcement.
+**Why**: Organization pattern and naming convention are team preferences, not technical correctness.
 
-#### Skip rules
+Present only if structural findings exist. For each preference, present a SWOT comparison with lettered options. See `references/code-organization-workflow.md#gate-2-swot-examples` for format.
 
-Skip a code organization finding if:
-- Directory is in `tests/`, `__tests__/`, `__mocks__/`, `fixtures/`, `generated/`, `.storybook/`
-- File is auto-generated (has `// @generated` or `/* eslint-disable */` at top)
-- Directory has <3 files (too few to judge naming convention)
+Wait for user response on each preference. Proceed to Step 3 with confirmed choices.
 
 ### Step 3: Recommend Solutions (AI Agent)
 
-For each scanner detection, recommend a **solution**. Consider:
+For each accepted detection, recommend a **solution**:
 
-1. **Stack coherence** — don't recommend libraries in isolation; consider how they fit the project's overall stack (e.g., recommending Stripe should trigger consideration of Resend for transactional email and PostHog for payment funnel analytics)
+1. **Stack coherence** — consider how libraries fit the project's overall stack
 2. **Ecosystem composition** — recommend companion libraries that work together
 3. **Rationale** — explain WHY this choice fits this project's framework, runtime, and scale
 4. **Anti-patterns** — what NOT to use and why
 5. **Alternatives** — different solutions for different architectural contexts
-6. **Migration snippet** — for each recommendation, read the detected code (file path + line range from scanner) and generate a concrete before/after code example showing the migration
-7. **Context7 verification** — call `resolve-library-id` + `query-docs` to confirm the library exists and get latest version/docs
+6. **Migration snippet** — read the detected code (file path + line range) and generate before/after examples
+7. **Context7 verification** — call `resolve-library-id` + `query-docs` to confirm existence and get latest docs
 
 Read `src/index.ts` for the `LibraryRecommendation` interface. Return `null` to skip a detection.
 
@@ -180,12 +134,20 @@ Read `src/index.ts` for the `LibraryRecommendation` interface. Return `null` to
 - Library is already in project dependencies (suggest version update instead)
 - Hand-rolled code is simpler than the library (3-line utility vs 50KB dep)
 
+### GATE 3: Accept/Reject Recommendations
+
+**Why**: Each recommendation has real migration cost. User may have business, timeline, or architectural reasons to defer or reject.
+
+Present ALL recommendations (replacements + gaps + code org tooling) as a decision table with columns: #, Domain, Replace what, With what, Risk, Effort, Context7, Decision. Offer options: (A) accept all, (B) accept specific, (C) low-risk only, (D) defer all. See `references/code-organization-workflow.md#gate-3-recommendation-table-example` for format.
+
+Wait for user response. Rejected items are excluded from migration plan, scoring, and PRs.
+
 ### Step 4–7: Score, Plan, Audit, Serialize
 
 The pipeline handles these automatically:
-- **Scoring**: confidence-based dimension scores (overridable by AI agent via `dimensionHints`)
+- **Scoring**: confidence-based dimension scores (overridable via `dimensionHints`)
 - **Migration plan**: auto-grouped by risk (low/medium/high), sorted by file co-location
-- **UX audit**: provide via `uxAudit` option in `analyze()`. Evaluate 8 categories: accessibility, error/empty/loading states, form validation, performance feel, copy consistency, design system alignment. For each, assess status (present/partial/missing) based on project code and `currentLibraries`.
+- **UX audit**: provide via `uxAudit` option. Evaluate 8 categories (accessibility, error/empty/loading states, form validation, performance feel, copy consistency, design system alignment)
 - **Constraints**: license allowlist filtering, dependency conflict detection, JSON serialization
 
 ### Optional Steps
@@ -194,6 +156,14 @@ The pipeline handles these automatically:
 - **Step 9**: Auto-update existing dependencies (`registryClient`)
 - **Step 10**: PR auto-creation via GitHub/GitLab (`platformClient` + `gitOps`)
 
+### GATE 4: Before Irreversible Actions
+
+**Why**: Creating PRs pushes branches to remote and notifies team members. File migrations modify the codebase. Both are irreversible.
+
+Present only if Step 10 or file migration is about to execute. Show PR table and file migration table with rollback commands. Offer options: (A) execute all, (B) PRs only, (C) migration only, (D) dry run, (E) abort. See `references/code-organization-workflow.md#gate-4-execution-confirmation-example` for format.
+
+Wait for user response. After execution, report results with rollback instructions.
+
 ## MCP Integration
 
 Prefer MCP tools when available; fall back to shell commands if not.

package/dist/index.d.ts

@@ -23,7 +23,7 @@ import type { VulnerabilityClient } from './security/osv-client.js';
 import type { RegistryClient } from './updater/registry-client.js';
 import type { PlatformClient } from './pr-creator/platform-client.js';
 import type { GitOperations } from './pr-creator/git-operations.js';
-export declare const VERSION = "1.0.7";
+export declare const VERSION = "1.0.8";
 /**
  * A library recommendation provided by the AI agent (or caller).
  */

package/dist/index.js

@@ -27,7 +27,7 @@ import { executePRPlans } from './pr-creator/pr-executor.js';
 // ---------------------------------------------------------------------------
 // Version
 // ---------------------------------------------------------------------------
-export const VERSION = '1.0.7';
+export const VERSION = '1.0.8';
 export { scanCodebase } from './analyzer/scanner.js';
 export { analyzeStructure } from './analyzer/structure-analyzer.js';
 export { analyzeCodeOrganization } from './analyzer/code-organization-analyzer.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebutra/next-unicorn-skill",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Stop Vibe Coding debt: audit your codebase, replace reinvented wheels with unicorn-grade libraries, scan vulnerabilities, auto-update deps, and auto-create PRs — all verified via Context7 MCP.",
   "type": "module",
   "main": "dist/index.js",