@handsupmin/gc-tree 0.8.12 → 0.8.14

package/dist/src/cli.js

@@ -532,13 +532,35 @@ async function main() {
                 usage();
             const explicitTarget = readArg('--target');
             const isGlobal = !explicitTarget || Object.values({ codex: gctreeGlobalRoot('codex'), claude: gctreeGlobalRoot('claude-code') }).some((r) => resolve(explicitTarget) === resolve(r));
-            const result = await ensureScaffold({
+            if (isGlobal) {
+                const result = await ensureScaffold({
+                    providerMode: host,
+                    scope: 'global',
+                    force: hasFlag('--force'),
+                    home,
+                });
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            const globalResult = await ensureScaffold({
                 providerMode: host,
-                ...(isGlobal ? { scope: 'global' } : { targetDir: explicitTarget, scope: 'local' }),
+                scope: 'global',
                 force: hasFlag('--force'),
                 home,
             });
-            console.log(JSON.stringify(result, null, 2));
+            const localResult = await ensureScaffold({
+                providerMode: host,
+                targetDir: explicitTarget,
+                scope: 'local',
+                force: hasFlag('--force'),
+                home,
+            });
+            console.log(JSON.stringify({
+                hosts: host,
+                target_dir: explicitTarget,
+                written: [...globalResult.written, ...localResult.written],
+                skipped_existing: [...globalResult.skipped_existing, ...localResult.skipped_existing],
+            }, null, 2));
             return;
         }
         case 'update': {

package/dist/src/hook.js

@@ -1,8 +1,8 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, open, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { dirname } from 'node:path';
 import { DEFAULT_BRANCH } from './paths.js';
-import { hookCachePath, } from './paths.js';
+import { hookCachePath, hookCacheDir, } from './paths.js';
 import { branchScopeStatus, readBranchRepoMap, resolveBranchForRepo } from './repo-map.js';
 import { resolveContext } from './resolve.js';
 import { readHead, statusForBranch } from './store.js';
@@ -27,9 +27,13 @@ function limitMatches(matches, max = 3) {
 function formatMatches(matches) {
     return limitMatches(matches)
         .map((match, index) => {
-        const summary = match.summary?.trim();
-        return summary
-            ? `${index + 1}. ${match.title} [${match.id}]\n   > ${summary}`
+        const summary = match.summary?.trim() ?? '';
+        const excerpt = match.excerpt?.trim() ?? '';
+        // Use summary if it looks actionable (long enough to contain patterns).
+        // Fall back to a trimmed excerpt when summary is a short description-only sentence.
+        const context = summary.length >= 60 ? summary : (excerpt.slice(0, 300) || summary);
+        return context
+            ? `${index + 1}. ${match.title} [${match.id}]\n   > ${context}`
             : `${index + 1}. ${match.title} [${match.id}]`;
     })
         .join('\n');
@@ -103,127 +107,166 @@ function readSessionId(payload) {
     const raw = normalizeText(payload.session_id || '');
     return raw || 'default-session';
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function acquireHookLock(home, sessionId) {
+    const lockPath = `${hookCachePath(home, sessionId)}.lock`;
+    await mkdir(hookCacheDir(home), { recursive: true });
+    for (let attempt = 0; attempt < 50; attempt += 1) {
+        try {
+            const handle = await open(lockPath, 'wx');
+            await handle.close();
+            return async () => {
+                await rm(lockPath, { force: true });
+            };
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'EEXIST')
+                throw error;
+            try {
+                const info = await stat(lockPath);
+                if (Date.now() - info.mtimeMs > 10_000) {
+                    await rm(lockPath, { force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            await sleep(25);
+        }
+    }
+    return async () => { };
+}
 export async function dispatchGcTreeHook({ event, home, payload, }) {
-    const cwd = payload.cwd || process.cwd();
-    const head = (await readHead(home)) || DEFAULT_BRANCH;
-    const resolved = await resolveBranchForRepo({ home, head, cwd });
-    const gcBranch = resolved.gc_branch;
-    const currentRepo = resolved.current_repo;
-    const mapping = await readBranchRepoMap(home);
-    const repoScopeStatus = branchScopeStatus(mapping, gcBranch, currentRepo);
     const sessionId = readSessionId(payload);
-    const now = new Date();
-    if (event === 'SessionStart') {
+    const releaseLock = await acquireHookLock(home, sessionId);
+    try {
+        const cwd = payload.cwd || process.cwd();
+        const head = (await readHead(home)) || DEFAULT_BRANCH;
+        const resolved = await resolveBranchForRepo({ home, head, cwd });
+        const gcBranch = resolved.gc_branch;
+        const currentRepo = resolved.current_repo;
+        const mapping = await readBranchRepoMap(home);
+        const repoScopeStatus = branchScopeStatus(mapping, gcBranch, currentRepo);
+        const now = new Date();
+        if (event === 'SessionStart') {
+            const previousCache = await readHookCache(home, sessionId);
+            const signature = hashQuery(`${event}:${gcBranch}:${currentRepo || ''}:${repoScopeStatus}`);
+            if (previousCache?.last_session_start_signature === signature &&
+                recentDuplicate(previousCache.last_session_start_at, now)) {
+                return null;
+            }
+            await writeHookCache(home, {
+                version: 1,
+                session_id: sessionId,
+                gc_branch: gcBranch,
+                current_repo: currentRepo,
+                repo_scope_status: repoScopeStatus,
+                branch_empty: previousCache?.branch_empty ?? false,
+                branch_excluded: previousCache?.branch_excluded ?? false,
+                no_match_signatures: previousCache?.no_match_signatures ?? [],
+                unmapped_shown_repos: previousCache?.unmapped_shown_repos ?? [],
+                prompt_count: previousCache?.prompt_count ?? 0,
+                last_session_start_signature: signature,
+                last_session_start_at: now.toISOString(),
+                last_prompt_signature: previousCache?.last_prompt_signature,
+                last_prompt_at: previousCache?.last_prompt_at,
+                updated_at: now.toISOString(),
+            });
+            return {
+                hookSpecificOutput: {
+                    hookEventName: event,
+                    additionalContext: buildSessionStartContext({
+                        gcBranch,
+                        currentRepo,
+                        repoScopeStatus,
+                    }),
+                },
+            };
+        }
+        const prompt = normalizeText(payload.user_prompt || payload.prompt || '');
+        if (!prompt)
+            return null;
+        const branchStatus = await statusForBranch(home, gcBranch);
         const previousCache = await readHookCache(home, sessionId);
-        const signature = hashQuery(`${event}:${gcBranch}:${currentRepo || ''}:${repoScopeStatus}`);
-        if (previousCache?.last_session_start_signature === signature &&
-            recentDuplicate(previousCache.last_session_start_at, now)) {
+        const promptSignature = hashQuery(`${event}:${gcBranch}:${currentRepo || ''}:${repoScopeStatus}:${prompt}`);
+        if (previousCache?.last_prompt_signature === promptSignature &&
+            recentDuplicate(previousCache.last_prompt_at, now)) {
             return null;
         }
-        await writeHookCache(home, {
-            version: 1,
-            session_id: sessionId,
-            gc_branch: gcBranch,
-            current_repo: currentRepo,
-            repo_scope_status: repoScopeStatus,
-            branch_empty: previousCache?.branch_empty ?? false,
-            branch_excluded: previousCache?.branch_excluded ?? false,
-            no_match_signatures: previousCache?.no_match_signatures ?? [],
-            unmapped_shown_repos: previousCache?.unmapped_shown_repos ?? [],
-            prompt_count: previousCache?.prompt_count ?? 0,
-            last_session_start_signature: signature,
-            last_session_start_at: now.toISOString(),
-            last_prompt_signature: previousCache?.last_prompt_signature,
-            last_prompt_at: previousCache?.last_prompt_at,
-            updated_at: now.toISOString(),
-        });
-        return {
-            hookSpecificOutput: {
-                hookEventName: event,
-                additionalContext: buildSessionStartContext({
-                    gcBranch,
-                    currentRepo,
-                    repoScopeStatus,
-                }),
-            },
-        };
-    }
-    const prompt = normalizeText(payload.user_prompt || payload.prompt || '');
-    if (!prompt)
-        return null;
-    const branchStatus = await statusForBranch(home, gcBranch);
-    const previousCache = await readHookCache(home, sessionId);
-    const promptSignature = hashQuery(`${event}:${gcBranch}:${currentRepo || ''}:${repoScopeStatus}:${prompt}`);
-    if (previousCache?.last_prompt_signature === promptSignature &&
-        recentDuplicate(previousCache.last_prompt_at, now)) {
-        return null;
-    }
-    const cache = nextCacheState(previousCache, {
-        sessionId,
-        gcBranch,
-        currentRepo,
-        repoScopeStatus,
-    });
-    cache.last_prompt_signature = promptSignature;
-    cache.last_prompt_at = now.toISOString();
-    let additionalContext;
-    if (repoScopeStatus === 'excluded') {
-        cache.branch_excluded = true;
-        additionalContext = buildExcludedContext({
+        const cache = nextCacheState(previousCache, {
+            sessionId,
             gcBranch,
             currentRepo,
-            cached: previousCache?.branch_excluded === true,
+            repoScopeStatus,
         });
-    }
-    else if (branchStatus.doc_count === 0) {
-        const wasCached = cache.branch_empty;
-        cache.branch_empty = true;
-        additionalContext = buildEmptyBranchContext({ gcBranch, currentRepo, cached: wasCached });
-    }
-    else if (repoScopeStatus === 'unmapped' && currentRepo && cache.unmapped_shown_repos.includes(currentRepo)) {
-        // Already showed context for this unmapped repo this session — skip silently.
-        cache.updated_at = now.toISOString();
-        await writeHookCache(home, cache);
-        return null;
-    }
-    else {
-        // For unmapped repos: use prompt only (no repo prefix) to avoid bias; apply higher score threshold.
-        const isUnmapped = repoScopeStatus === 'unmapped';
-        const query = !isUnmapped && currentRepo ? `${currentRepo} ${prompt}` : prompt;
-        const signature = hashQuery(query);
-        if (!isUnmapped && cache.no_match_signatures.includes(signature)) {
-            additionalContext = buildNoMatchContext({ gcBranch, currentRepo, cached: true });
+        cache.last_prompt_signature = promptSignature;
+        cache.last_prompt_at = now.toISOString();
+        let additionalContext;
+        if (repoScopeStatus === 'excluded') {
+            cache.branch_excluded = true;
+            additionalContext = buildExcludedContext({
+                gcBranch,
+                currentRepo,
+                cached: previousCache?.branch_excluded === true,
+            });
+        }
+        else if (branchStatus.doc_count === 0) {
+            const wasCached = cache.branch_empty;
+            cache.branch_empty = true;
+            additionalContext = buildEmptyBranchContext({ gcBranch, currentRepo, cached: wasCached });
+        }
+        else if (repoScopeStatus === 'unmapped' && currentRepo && cache.unmapped_shown_repos.includes(currentRepo)) {
+            // Already showed context for this unmapped repo this session — skip silently.
+            cache.updated_at = now.toISOString();
+            await writeHookCache(home, cache);
+            return null;
         }
         else {
-            const result = await resolveContext({ home, branch: gcBranch, query });
-            const effectiveMatches = result.matches;
-            if (effectiveMatches.length === 0) {
-                if (isUnmapped) {
-                    // Unmapped + no strong match: skip silently, no noise.
-                    cache.updated_at = now.toISOString();
-                    await writeHookCache(home, cache);
-                    return null;
-                }
-                cache.no_match_signatures = [...new Set([...cache.no_match_signatures, signature])];
-                additionalContext = buildNoMatchContext({ gcBranch, currentRepo, cached: false });
+            // For unmapped repos: use prompt only (no repo prefix) to avoid bias; apply higher score threshold.
+            const isUnmapped = repoScopeStatus === 'unmapped';
+            const query = !isUnmapped && currentRepo ? `${currentRepo} ${prompt}` : prompt;
+            const signature = hashQuery(query);
+            if (!isUnmapped && cache.no_match_signatures.includes(signature)) {
+                additionalContext = buildNoMatchContext({ gcBranch, currentRepo, cached: true });
             }
             else {
-                if (!isUnmapped) {
-                    cache.no_match_signatures = cache.no_match_signatures.filter((entry) => entry !== signature);
+                const result = await resolveContext({ home, branch: gcBranch, query });
+                const effectiveMatches = result.matches;
+                if (effectiveMatches.length === 0) {
+                    if (isUnmapped) {
+                        // Unmapped + no strong match: skip silently, no noise.
+                        cache.updated_at = now.toISOString();
+                        await writeHookCache(home, cache);
+                        return null;
+                    }
+                    cache.no_match_signatures = [...new Set([...cache.no_match_signatures, signature])];
+                    additionalContext = buildNoMatchContext({ gcBranch, currentRepo, cached: false });
                 }
-                else if (currentRepo) {
-                    // Mark this unmapped repo as shown so we don't repeat next prompt.
-                    cache.unmapped_shown_repos = [...new Set([...cache.unmapped_shown_repos, currentRepo])];
+                else {
+                    if (!isUnmapped) {
+                        cache.no_match_signatures = cache.no_match_signatures.filter((entry) => entry !== signature);
+                    }
+                    else if (currentRepo) {
+                        // Mark this unmapped repo as shown so we don't repeat next prompt.
+                        cache.unmapped_shown_repos = [...new Set([...cache.unmapped_shown_repos, currentRepo])];
+                    }
+                    additionalContext = buildMatchContext({ gcBranch, currentRepo, repoScopeStatus, matches: effectiveMatches });
                 }
-                additionalContext = buildMatchContext({ gcBranch, currentRepo, repoScopeStatus, matches: effectiveMatches });
+            }
+            if (cache.prompt_count > 0 && cache.prompt_count % SELF_REVIEW_INTERVAL === 0) {
+                additionalContext += buildSelfReviewAppend(cache.prompt_count);
+                cache.prompt_count = 0;
             }
         }
-        if (cache.prompt_count > 0 && cache.prompt_count % SELF_REVIEW_INTERVAL === 0) {
-            additionalContext += buildSelfReviewAppend(cache.prompt_count);
-            cache.prompt_count = 0;
-        }
+        cache.updated_at = now.toISOString();
+        await writeHookCache(home, cache);
+        return { hookSpecificOutput: { hookEventName: event, additionalContext } };
+    }
+    finally {
+        await releaseLock();
     }
-    cache.updated_at = now.toISOString();
-    await writeHookCache(home, cache);
-    return { hookSpecificOutput: { hookEventName: event, additionalContext } };
 }

package/dist/src/onboarding-protocol.js

@@ -36,7 +36,7 @@ export function onboardingProtocolLines() {
         'Treat `index.md` as concept-first: show the keywords a user or AI would search for, not just broad document titles.',
         'Generate index entries automatically from primary concept names, aliases, repository nicknames, and workflow labels when those are clear.',
         'Split glossary docs when a concept is likely to be searched directly, needs more than a short definition, or carries workflow/constraint details; keep only low-value leftover terms in a shared glossary.',
-        'Keep each doc summary-first so the top section gives the gist before deeper details.',
+        'The `## Summary` section of every doc must be actionable, not descriptive — write the actual patterns, commands, or constraints a developer needs, not a sentence about what the doc covers. Bad: "이 문서는 updateCollection 패턴을 설명합니다." Good: "updateCollection: { ...dto } spread 필수. return plainToInstance(Res, result satisfies Res). 새 필드 추가 = DTO → 서비스 → 컨트롤러 순서." The summary is injected into the AI context before every task — if it reads like a table of contents entry, it is useless.',
         'Treat `index.md` as a human-readable dictionary-style table of contents grouped by category headings and `label -> path` entries.',
     ];
 }

package/dist/src/scaffold.js

@@ -301,11 +301,19 @@ export async function scaffoldHostIntegration({ host, targetDir, force = false,
             await unmergeGcTreeHooksJson(oldHooksPath);
         }
     }
-    await mergeGcTreeHooksJson({
-        filePath: hookPath,
-        target: isCodex ? 'codex' : 'claude-code',
-    });
-    written.push(hookPath);
+    if (scope === 'local') {
+        const status = await unmergeGcTreeHooksJson(hookPath);
+        if (status !== 'missing') {
+            written.push(hookPath);
+        }
+    }
+    else {
+        await mergeGcTreeHooksJson({
+            filePath: hookPath,
+            target: isCodex ? 'codex' : 'claude-code',
+        });
+        written.push(hookPath);
+    }
     const targets = files.map((file) => ({
         ...file,
         fullPath: join(resolvedTargetDir, file.path),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handsupmin/gc-tree",
-  "version": "0.8.12",
+  "version": "0.8.14",
   "description": "Global Context Tree, a lightweight branch-aware global context orchestrator for AI coding tools",
   "type": "module",
   "private": false,

package/skills/onboard/SKILL.md

@@ -39,7 +39,7 @@ Use this when a user wants to create global context for a product, company, or w
 - when the inspected evidence already covers a repository well enough, ask only for missing deltas instead of re-asking role, paths, and workflow from scratch
 - only ask open-ended repository questions when the needed detail cannot be recovered responsibly from local evidence
 - ask about glossary terms and default verification commands before you finish
-- write compact source docs with a required `## Summary` section near the top
+- write compact source docs with a required `## Summary` section near the top; the `## Summary` must be actionable — write the actual patterns, commands, or constraints a developer needs, not a sentence about what the doc covers (bad: "이 문서는 X를 설명합니다"; good: "updateX: { ...dto } spread 필수. return plainToInstance(Res, result satisfies Res). 새 필드 추가 = DTO → 서비스 → 컨트롤러 순서."); the summary is injected into AI context before every task — if it reads like a table of contents entry, it is useless
 - prefer an encyclopedia-style context set with many small docs instead of a few broad docs
 - prefer category directories like `docs/role/`, `docs/repos/`, `docs/domain/`, `docs/workflows/`, `docs/conventions/`, and `docs/infra/`
 - prefer one concept, one repository, one workflow, or one convention per file when possible