peaks-loop 4.0.4 → 4.0.5

package/dist/services/standards/project-context.js

@@ -54,7 +54,7 @@ function majorOf(version) {
     const major = cleaned.split('.')[0];
     return major !== undefined && /^\d+$/.test(major) ? major : undefined;
 }
-function detectComponentLibrary(deps) {
+export function detectComponentLibrary(projectRoot, deps) {
     if ('antd' in deps) {
         const major = majorOf(deps['antd']);
         const hasProSuite = '@ant-design/pro-components' in deps || Object.keys(deps).some((d) => d.startsWith('@ant-design/pro-'));
@@ -80,6 +80,19 @@ function detectComponentLibrary(deps) {
         return { name: 'chakra' };
     if ('vant' in deps)
         return { name: 'vant' };
+    // shadcn / ui is a Tailwind-based component primitive set shipped as
+    // copyable source files under `components/ui/`. It has no top-level
+    // package of its own, so the signal we use is: Tailwind is present
+    // AND at least one of its peer utilities is also present.
+    if (('class-variance-authority' in deps
+        || 'clsx' in deps
+        || 'tailwind-merge' in deps
+        || 'lucide-react' in deps)
+        && ('tailwindcss' in deps
+            || existsSync(join(projectRoot, 'components', 'ui'))
+            || existsSync(join(projectRoot, 'src', 'components', 'ui')))) {
+        return { name: 'shadcn' };
+    }
     return { name: 'none' };
 }
 function detectCssFrameworks(projectRoot, deps) {
@@ -235,7 +248,7 @@ function notableDepsList(deps) {
 export function detectProjectContext(projectRoot) {
     const { exists, deps } = readPackageJson(projectRoot);
     const { tool, path } = detectBuildTool(projectRoot);
-    const componentLibrary = detectComponentLibrary(deps);
+    const componentLibrary = detectComponentLibrary(projectRoot, deps);
     const cssFrameworks = detectCssFrameworks(projectRoot, deps);
     return {
         hasPackageJson: exists,
@@ -291,6 +304,8 @@ export function componentLibraryLabel(lib) {
                 return 'NextUI';
             case 'chakra':
                 return 'Chakra UI';
+            case 'shadcn':
+                return 'shadcn / ui';
             case 'vant':
                 return 'Vant (mobile)';
             case 'none':

package/dist/services/standards/project-standards-service.d.ts

@@ -1,3 +1,4 @@
+import { type ProjectContext } from './project-context.js';
 /**
  * Typed error raised when a planned `peaks standards` write target would
  * land outside `projectRoot` (or collide with the user-level baseline
@@ -106,6 +107,14 @@ export type ProjectStandardsInitOptions = {
  * the file-probe logic.
  */
 export declare function detectLanguage(projectRoot: string): StandardsLanguage;
+/**
+ * UI library priority rule (effective 2026-08-01). Public so unit tests
+ * can pin the contract without reaching through the plan builder.
+ *
+ * Returns the rule line, or `null` when the project has no detected
+ * component library (in which case the rule is intentionally silent).
+ */
+export declare function renderUiLibraryPriorityRule(ctx: ProjectContext): string | null;
 export declare function createProjectStandardsInitPlan(options: ProjectStandardsInitOptions): ProjectStandardsInitPlan;
 export declare function createProjectStandardsUpdatePlan(options: ProjectStandardsInitOptions): ProjectStandardsUpdatePlan;
 export declare function executeProjectStandardsInit(options: ProjectStandardsInitOptions): ProjectStandardsInitResult;

package/dist/services/standards/project-standards-service.js

@@ -245,6 +245,25 @@ function renderSecurity(ctx) {
     const rules = extra.length > 0 ? [...baseRules, '', '## Project-specific security focus', ...extra] : baseRules;
     return `${renderHeader('Security Review Standards')}${rules.join('\n')}\n`;
 }
+/**
+ * UI library priority rule (effective 2026-08-01). Public so unit tests
+ * can pin the contract without reaching through the plan builder.
+ *
+ * Returns the rule line, or `null` when the project has no detected
+ * component library (in which case the rule is intentionally silent).
+ */
+export function renderUiLibraryPriorityRule(ctx) {
+    const lib = ctx.componentLibrary.name;
+    const UI_LIB_NAMES = [
+        'antd', 'antd-pro', 'mui', 'shadcn',
+        'chakra', 'element-plus', 'element-ui',
+        'arco', 'tdesign', 'semi', 'nextui'
+    ];
+    if (!UI_LIB_NAMES.includes(lib)) {
+        return null;
+    }
+    return `- UI library priority (peaks-loop, effective 2026-08-01): this project uses \`${lib}\`. Prefer the library's exported components over hand-rolled native DOM / HTML primitives. Native DOM is acceptable only for primitives the library does not ship; leave a one-line comment naming the library primitive that was unavailable. Library themes and tokens are the source of truth; do NOT introduce a parallel CSS framework or inline styles that fight the library.`;
+}
 function renderLanguageCodingStyle(language, ctx) {
     const languageName = language === 'generic' ? 'Generic' : language[0].toUpperCase() + language.slice(1);
     const typeSafetyRule = language === 'typescript' || language === 'javascript'
@@ -267,6 +286,13 @@ function renderLanguageCodingStyle(language, ctx) {
     if ((language === 'typescript' || language === 'javascript') && ctx.buildTool === 'umi') {
         extra.push('- Use the project\'s existing service-layer pattern (`src/services/**`) for API calls; do not hand-roll `fetch` in components.');
     }
+    // UI library priority (effective 2026-08-01). Applies to any project whose
+    // scan identified one of the supported component libraries; the rule
+    // is generated by the standards update so it ships to every downstream
+    // project through `peaks standards init/update`.
+    const uiRule = renderUiLibraryPriorityRule(ctx);
+    if (uiRule !== null)
+        extra.push(uiRule);
     const rules = extra.length > 0 ? [...baseRules, '', '## Project-specific rules', ...extra] : baseRules;
     return `${renderHeader(`${languageName} Coding Standards`)}${rules.join('\n')}\n`;
 }

package/dist/services/worktree/dispatch-provenance.d.ts

@@ -0,0 +1,25 @@
+export declare const DISPATCH_PROVENANCE_ENV = "PEAKS_SUB_AGENT_DISPATCH_PROVENANCE";
+export type DispatchProvenance = {
+    readonly schemaVersion: 1;
+    readonly token: string;
+    readonly sessionId: string;
+    readonly requestId: string;
+    readonly leaseId: string;
+    readonly isolation: 'worktree';
+    readonly issuedAt: string;
+};
+export declare function createDispatchProvenanceToken(input: {
+    readonly sessionId: string;
+    readonly requestId: string;
+    readonly leaseId: string;
+}): string;
+export declare function dispatchProvenanceFilePath(projectRoot: string, sessionId: string, token: string): string;
+export declare function writeDispatchProvenance(input: {
+    readonly projectRoot: string;
+    readonly record: DispatchProvenance;
+}): void;
+export declare function readDispatchProvenance(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly token: string;
+}): DispatchProvenance | null;

package/dist/services/worktree/dispatch-provenance.js

@@ -0,0 +1,47 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export const DISPATCH_PROVENANCE_ENV = 'PEAKS_SUB_AGENT_DISPATCH_PROVENANCE';
+const PROVENANCE_DIR = 'dispatch-provenance';
+export function createDispatchProvenanceToken(input) {
+    return createHash('sha256')
+        .update(`${input.sessionId}|${input.requestId}|${input.leaseId}`)
+        .digest('hex')
+        .slice(0, 32);
+}
+export function dispatchProvenanceFilePath(projectRoot, sessionId, token) {
+    return join(projectRoot, '.peaks', '_runtime', sessionId, PROVENANCE_DIR, `${token}.json`);
+}
+export function writeDispatchProvenance(input) {
+    const path = dispatchProvenanceFilePath(input.projectRoot, input.record.sessionId, input.record.token);
+    mkdirSync(dirname(path), { recursive: true });
+    const tempPath = `${path}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tempPath, `${JSON.stringify(input.record, null, 2)}\n`, 'utf8');
+    renameSync(tempPath, path);
+}
+export function readDispatchProvenance(input) {
+    if (!/^[a-f0-9]{32}$/.test(input.token))
+        return null;
+    const path = dispatchProvenanceFilePath(input.projectRoot, input.sessionId, input.token);
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (parsed === null || typeof parsed !== 'object')
+            return null;
+        const value = parsed;
+        if (value.schemaVersion !== 1 ||
+            value.token !== input.token ||
+            value.sessionId !== input.sessionId ||
+            typeof value.requestId !== 'string' ||
+            typeof value.leaseId !== 'string' ||
+            value.isolation !== 'worktree' ||
+            typeof value.issuedAt !== 'string') {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/services/worktree/git-worktree-parser.d.ts

@@ -0,0 +1,8 @@
+export type GitWorktreeRecord = {
+    readonly path: string;
+    readonly head: string | null;
+    readonly branch: string | null;
+    readonly prunable: boolean;
+};
+export declare function parseGitWorktreePorcelain(raw: string): ReadonlyArray<GitWorktreeRecord>;
+export declare function isPathInside(parent: string, candidate: string): boolean;

package/dist/services/worktree/git-worktree-parser.js

@@ -0,0 +1,45 @@
+import { relative, resolve, sep } from 'node:path';
+export function parseGitWorktreePorcelain(raw) {
+    const records = [];
+    let current = null;
+    const flush = () => {
+        if (current !== null) {
+            records.push({
+                path: current.path,
+                head: current.head,
+                branch: current.branch,
+                prunable: current.prunable,
+            });
+        }
+        current = null;
+    };
+    for (const line of raw.split(/\r?\n/)) {
+        if (line.length === 0) {
+            flush();
+            continue;
+        }
+        const space = line.indexOf(' ');
+        const key = space === -1 ? line : line.slice(0, space);
+        const value = space === -1 ? '' : line.slice(space + 1);
+        if (key === 'worktree') {
+            flush();
+            const next = { path: value, head: null, branch: null, prunable: false };
+            current = next;
+        }
+        else if (current !== null && key === 'HEAD') {
+            current = { path: current.path, head: value, branch: current.branch, prunable: current.prunable };
+        }
+        else if (current !== null && key === 'branch') {
+            current = { path: current.path, head: current.head, branch: value.replace(/^refs\/heads\//, ''), prunable: current.prunable };
+        }
+        else if (current !== null && key === 'prunable') {
+            current = { path: current.path, head: current.head, branch: current.branch, prunable: true };
+        }
+    }
+    flush();
+    return records;
+}
+export function isPathInside(parent, candidate) {
+    const rel = relative(resolve(parent), resolve(candidate));
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !rel.startsWith(sep));
+}

package/dist/services/worktree/host-worktree-reconciler.d.ts

@@ -0,0 +1,15 @@
+import { type GitWorktreeRecord } from './git-worktree-parser.js';
+export type HostWorktreeFinding = GitWorktreeRecord & {
+    readonly managedLeaseId: string | null;
+    readonly state: 'managed' | 'unleased' | 'prunable';
+};
+export type HostWorktreeReconcileResult = {
+    readonly hostRoot: string;
+    readonly findings: ReadonlyArray<HostWorktreeFinding>;
+    readonly unmanaged: ReadonlyArray<HostWorktreeFinding>;
+};
+export declare function reconcileHostWorktrees(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly hostRoot?: string;
+}): HostWorktreeReconcileResult;

package/dist/services/worktree/host-worktree-reconciler.js

@@ -0,0 +1,39 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { leaseStoreDir, listLeasesSync } from './worktree-lease.js';
+import { isPathInside, parseGitWorktreePorcelain } from './git-worktree-parser.js';
+export function reconcileHostWorktrees(input) {
+    const hostRoot = resolve(input.hostRoot ?? join(input.projectRoot, '.claude', 'worktrees'));
+    let records = [];
+    try {
+        const raw = execFileSync('git', ['worktree', 'list', '--porcelain'], {
+            cwd: input.projectRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        records = parseGitWorktreePorcelain(raw);
+    }
+    catch {
+        records = [];
+    }
+    const storeDir = leaseStoreDir(join(input.projectRoot, '.peaks', '_runtime', input.sessionId));
+    const leaseResult = listLeasesSync(storeDir, {
+        existsSync,
+        readdir: (path) => readdirSync(path),
+        readFile: (path) => readFileSync(path, 'utf8'),
+    });
+    const leases = leaseResult.kind === 'ok' ? leaseResult.leases : [];
+    const leaseByPath = new Map(leases.map((lease) => [resolve(lease.path), lease.leaseId]));
+    const findings = records
+        .filter((record) => isPathInside(hostRoot, record.path) && basename(record.path).startsWith('agent-'))
+        .map((record) => {
+        const managedLeaseId = leaseByPath.get(resolve(record.path)) ?? null;
+        return {
+            ...record,
+            managedLeaseId,
+            state: record.prunable ? 'prunable' : managedLeaseId === null ? 'unleased' : 'managed',
+        };
+    });
+    return { hostRoot, findings, unmanaged: findings.filter((finding) => finding.state !== 'managed') };
+}

package/dist/services/worktree/long-path-cleanup.d.ts

@@ -0,0 +1,10 @@
+export type LongPathCleanupResult = {
+    readonly removed: boolean;
+    readonly strategy: 'git' | 'windows-long-path' | 'none';
+    readonly error?: string;
+};
+export declare function windowsLongPath(path: string): string;
+export declare function removeRegisteredWorktree(input: {
+    readonly projectRoot: string;
+    readonly worktreePath: string;
+}): LongPathCleanupResult;

package/dist/services/worktree/long-path-cleanup.js

@@ -0,0 +1,38 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, rmSync } from 'node:fs';
+import { resolve } from 'node:path';
+export function windowsLongPath(path) {
+    const absolute = resolve(path);
+    if (process.platform !== 'win32' || absolute.startsWith('\\\\?\\'))
+        return absolute;
+    if (absolute.startsWith('\\\\'))
+        return `\\\\?\\UNC\\${absolute.slice(2)}`;
+    return `\\\\?\\${absolute}`;
+}
+export function removeRegisteredWorktree(input) {
+    try {
+        execFileSync('git', ['worktree', 'remove', '--force', input.worktreePath], {
+            cwd: input.projectRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        execFileSync('git', ['worktree', 'prune'], { cwd: input.projectRoot, stdio: 'ignore' });
+        return { removed: !existsSync(input.worktreePath), strategy: 'git' };
+    }
+    catch (error) {
+        if (process.platform !== 'win32') {
+            return { removed: false, strategy: 'none', error: error instanceof Error ? error.message : String(error) };
+        }
+        try {
+            rmSync(windowsLongPath(input.worktreePath), { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+            execFileSync('git', ['worktree', 'prune'], { cwd: input.projectRoot, stdio: 'ignore' });
+            return { removed: !existsSync(input.worktreePath), strategy: 'windows-long-path' };
+        }
+        catch (fallbackError) {
+            return {
+                removed: false,
+                strategy: 'none',
+                error: fallbackError instanceof Error ? fallbackError.message : String(fallbackError),
+            };
+        }
+    }
+}

package/dist/services/worktree/playwright-profile.d.ts

@@ -0,0 +1,8 @@
+export declare function playwrightProfilePaths(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly dispatchId: string;
+}): {
+    readonly userDataDir: string;
+    readonly profileName: string;
+};

package/dist/services/worktree/playwright-profile.js

@@ -0,0 +1,23 @@
+/**
+ * playwright-profile — deterministic Chromium user-data-dir +
+ * profile-name pair generator for a (session, dispatch) tuple.
+ *
+ * Slice 2026-08-01-subagent-merge-and-e2e (Task 2). Each sub-agent
+ * dispatch with `--isolation worktree` MUST land its Playwright MCP
+ * browser session in a unique Chromium profile so concurrent
+ * dispatches do not share cookies / localStorage / IndexedDB. The
+ * pair is:
+ *
+ *   userDataDir = <projectRoot>/.peaks/_runtime/<sessionId>/pw-profiles/<dispatchId>
+ *   profileName = "dispatch-<dispatchId>"
+ *
+ * The userDataDir is gitignored (it lives under `.peaks/_runtime/`)
+ * so cookies do not leak across slices. The profileName is the
+ * Chromium `--profile-directory` flag the Playwright MCP server
+ * reads when it spawns the browser.
+ */
+import { join } from 'node:path';
+export function playwrightProfilePaths(input) {
+    const userDataDir = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'pw-profiles', input.dispatchId);
+    return { userDataDir, profileName: `dispatch-${input.dispatchId}` };
+}

package/dist/services/worktree/worktree-gc-guard.d.ts

@@ -0,0 +1,8 @@
+export type SkillJunctionReference = {
+    readonly junctionPath: string;
+    readonly target: string;
+};
+export declare function findManagedSkillJunctionReferences(input: {
+    readonly worktreePath: string;
+    readonly skillRoots: ReadonlyArray<string>;
+}): ReadonlyArray<SkillJunctionReference>;

package/dist/services/worktree/worktree-gc-guard.js

@@ -0,0 +1,38 @@
+import { existsSync, lstatSync, readFileSync, readdirSync, readlinkSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+export function findManagedSkillJunctionReferences(input) {
+    const targetRoot = resolve(input.worktreePath);
+    const refs = [];
+    for (const skillRoot of input.skillRoots) {
+        if (!existsSync(skillRoot))
+            continue;
+        for (const name of readdirSync(skillRoot)) {
+            if (!name.startsWith('peaks-') || name.endsWith('.peaks-managed'))
+                continue;
+            const junctionPath = resolve(skillRoot, name);
+            const markerPath = `${junctionPath}.peaks-managed`;
+            if (!existsSync(markerPath))
+                continue;
+            try {
+                if (!lstatSync(junctionPath).isSymbolicLink())
+                    continue;
+                const link = readlinkSync(junctionPath);
+                const resolvedTarget = resolve(dirname(junctionPath), link);
+                if (isInside(targetRoot, resolvedTarget))
+                    refs.push({ junctionPath, target: resolvedTarget });
+            }
+            catch {
+                const managedTarget = readFileSync(markerPath, 'utf8').trim();
+                if (managedTarget.length > 0 && isInside(targetRoot, managedTarget)) {
+                    refs.push({ junctionPath, target: managedTarget });
+                }
+            }
+        }
+    }
+    return refs;
+}
+function isInside(parent, candidate) {
+    const normalizedParent = resolve(parent).toLowerCase();
+    const normalizedCandidate = resolve(candidate).toLowerCase();
+    return normalizedCandidate === normalizedParent || normalizedCandidate.startsWith(`${normalizedParent}\\`) || normalizedCandidate.startsWith(`${normalizedParent}/`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.4",
+  "version": "4.0.5",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -98,9 +98,9 @@
     "headroom-ai": "0.22.4",
     "yaml": "^2.9.0",
     "zod": "^3.25.76",
-    "peaks-loop-mut": "0.1.7",
-    "peaks-loop-shared": "0.0.33",
-    "peaks-loop-shared-channel": "0.0.12"
+    "peaks-loop-mut": "0.1.9",
+    "peaks-loop-shared": "0.0.35",
+    "peaks-loop-shared-channel": "0.0.14"
   },
   "peerDependencies": {
     "@alibaba-group/open-code-review": "1.3.1"

package/scripts/install-skills.mjs

@@ -641,11 +641,20 @@ export function installBundledSkills(options = {}) {
     if (current) {
       const managedTarget = getManagedTarget(targetPath);
       const linkTarget = current.isSymbolicLink() ? readlinkSync(targetPath) : null;
-      if (linkTarget === sourcePath) {
+      const linkTargetExists = typeof linkTarget === 'string' && existsSync(linkTarget);
+      if (linkTarget === sourcePath && linkTargetExists) {
         installed.push(skillName);
         continue;
       }
-      if ((current.isSymbolicLink() || isBrokenSymlink(current, targetPath)) && managedTarget === linkTarget) {
+      // Managed Junctions may point into an ephemeral host worktree. If that
+      // worktree was removed, Windows keeps the Junction entry but its target
+      // no longer resolves. Repair only when reconciliation was explicitly
+      // requested; normal postinstall keeps its existing ownership behavior.
+      if (
+        (current.isSymbolicLink() || isBrokenSymlink(current, targetPath)) &&
+        (managedTarget === linkTarget ||
+          (options.reconcileJunctions === true && managedTarget !== null && !linkTargetExists))
+      ) {
         validateSkillsRoot();
         unlinkSync(targetPath);
         validateSkillsRoot();