@handsupmin/gc-tree 0.8.5 → 0.8.7

package/README.es.md

@@ -74,7 +74,7 @@ gctree init
 2. Instalar los archivos de integración en el repositorio actual
 3. Completar el onboarding guiado para el gc-branch `main`
 
-Después, tu herramienta de IA instala integración real de hooks SessionStart/UserPromptSubmit: revisa gc-tree automáticamente antes de trabajar y cachea resultados vacíos/no-match durante la sesión. La salida del hook se mantiene compacta: muestra el estado found/no-match junto con IDs y resúmenes, y deja el documento completo detrás de `gctree resolve --id <id>`.
+Después, tu herramienta de IA instala integración real de hooks SessionStart/UserPromptSubmit: revisa gc-tree automáticamente antes de trabajar y cachea resultados vacíos/no-match durante la sesión. La salida del hook se mantiene compacta: muestra el estado found/no-match junto con títulos e IDs de documentos coincidentes, y deja el documento completo detrás de `gctree resolve --id <id>`.
 
 - **CLI:** `gctree`
 - **Requisito:** Node.js 20+

package/README.ja.md

@@ -74,7 +74,7 @@ gctree init
 2. 現在のリポジトリへの統合ファイルのインストール
 3. `main` gc-branch のガイド付きオンボーディング実行
 
-その後は、AI ツールに実際の SessionStart / UserPromptSubmit フック統合が入り、作業前に gc-tree を自動確認し、空結果や no-match をセッション中キャッシュします。フック出力はコンパクトに保たれ、found/no-match 状態、ドキュメント ID、要約だけを示し、全文は必要なときに `gctree resolve --id <id>` で開きます。
+その後は、AI ツールに実際の SessionStart / UserPromptSubmit フック統合が入り、作業前に gc-tree を自動確認し、空結果や no-match をセッション中キャッシュします。フック出力はコンパクトに保たれ、found/no-match 状態、マッチしたドキュメントのタイトルと ID だけを示し、全文は必要なときに `gctree resolve --id <id>` で開きます。
 
 - **CLI：** `gctree`
 - **動作条件：** Node.js 20+

package/README.ko.md

@@ -74,7 +74,7 @@ gctree init
 2. 현재 레포에 통합 파일 스캐폴딩
 3. `main` gc-branch 가이드형 온보딩 실행
 
-이후 AI 도구에 실제 SessionStart/UserPromptSubmit 훅 통합이 설치되어, 작업 전에 gc-tree를 자동 확인하고 세션 동안 빈 결과·no-match를 캐시합니다. 훅 출력은 짧게 유지됩니다: 찾음/no-match 상태와 문서 ID, 요약만 보여주고 전체 문서는 `gctree resolve --id <id>`로 필요할 때 엽니다.
+이후 AI 도구에 실제 SessionStart/UserPromptSubmit 훅 통합이 설치되어, 작업 전에 gc-tree를 자동 확인하고 세션 동안 빈 결과·no-match를 캐시합니다. 훅 출력은 짧게 유지됩니다: 찾음/no-match 상태와 매칭된 문서 제목/ID만 보여주고 전체 문서는 `gctree resolve --id <id>`로 필요할 때 엽니다.
 
 - **CLI:** `gctree`
 - **요구 사항:** Node.js 20+

package/README.md

@@ -74,7 +74,7 @@ gctree init
 2. Scaffold the integration files into your current repo
 3. Run guided onboarding for the `main` gc-branch
 
-After that, your AI tool gets real SessionStart/UserPromptSubmit hook integration, so it auto-checks gc-tree before work and caches empty/no-match results for the session. Hook output stays compact: it reports found/no-match state plus document IDs and summaries, and full docs stay behind `gctree resolve --id <id>`.
+After that, your AI tool gets real SessionStart/UserPromptSubmit hook integration, so it auto-checks gc-tree before work and caches empty/no-match results for the session. Hook output stays compact: it reports found/no-match state plus matching document titles and IDs, and full docs stay behind `gctree resolve --id <id>`.
 
 - **CLI:** `gctree`
 - **Requires:** Node.js 20+

package/README.zh.md

@@ -61,7 +61,7 @@ gctree init
 2. 在当前仓库安装集成文件
 3. 为 `main` gc-branch 完成引导式 onboarding
 
-之后，AI 工具会安装真正的 SessionStart / UserPromptSubmit hook 集成：在开始工作前自动检查 gc-tree，并在整个会话内缓存空结果和 no-match。Hook 输出保持紧凑：只显示 found/no-match 状态、文档 ID 和摘要，完整文档需要时再通过 `gctree resolve --id <id>` 打开。
+之后，AI 工具会安装真正的 SessionStart / UserPromptSubmit hook 集成：在开始工作前自动检查 gc-tree，并在整个会话内缓存空结果和 no-match。Hook 输出保持紧凑：只显示 found/no-match 状态以及匹配文档的标题和 ID，完整文档需要时再通过 `gctree resolve --id <id>` 打开。
 
 - **CLI：** `gctree`
 - **要求：** Node.js 20+

package/dist/src/hook.js

@@ -13,46 +13,48 @@ function normalizeText(value) {
 function hashQuery(query) {
     return createHash('sha1').update(normalizeText(query).toLowerCase()).digest('hex');
 }
+function recentDuplicate(previousAt, now, windowMs = 5000) {
+    if (!previousAt)
+        return false;
+    const previousMs = Date.parse(previousAt);
+    if (!Number.isFinite(previousMs))
+        return false;
+    return now.getTime() - previousMs <= windowMs;
+}
 function limitMatches(matches, max = 3) {
     return matches.slice(0, max);
 }
 function formatMatches(matches) {
     return limitMatches(matches)
-        .map((match, index) => `${index + 1}. ${match.title} [id=${match.id}]: ${match.summary}`)
+        .map((match, index) => `${index + 1}. ${match.title} [${match.id}]`)
         .join('\n');
 }
 function buildSessionStartContext({ gcBranch, currentRepo, repoScopeStatus, }) {
-    return [
-        `gc-tree auto-resolve is active for this session.`,
-        `Active gc-branch: "${gcBranch}".`,
-        `Current repo: ${currentRepo || 'unscoped'}.`,
-        `Repo scope status: ${repoScopeStatus}.`,
-        `Before acting on new user prompts, use gc-tree hook context first. If the hook reports no reusable global context, avoid redundant resolve calls for the same session state unless the repo, gc-branch, or task changes materially.`,
-    ].join(' ');
+    return `[gc-tree] active gc-branch="${gcBranch}" repo="${currentRepo || 'unscoped'}" scope=${repoScopeStatus}.`;
 }
 function buildEmptyBranchContext({ gcBranch, currentRepo, cached, }) {
-    return `[gc-tree] no context docs in gc-branch "${gcBranch}" for repo "${currentRepo || 'unscoped'}"${cached ? ' (cached)' : ''}.`;
+    return `[gc-tree] no docs: gc-branch="${gcBranch}" repo="${currentRepo || 'unscoped'}"${cached ? ' cached=true' : ''}.`;
 }
 function buildExcludedContext({ gcBranch, currentRepo, cached, }) {
-    return `[gc-tree] repo "${currentRepo || 'unknown'}" is excluded from gc-branch "${gcBranch}"${cached ? ' (cached)' : ''}.`;
+    return `[gc-tree] excluded: gc-branch="${gcBranch}" repo="${currentRepo || 'unknown'}"${cached ? ' cached=true' : ''}.`;
 }
 function buildNoMatchContext({ gcBranch, currentRepo, cached, }) {
-    return `[gc-tree] no matching context in gc-branch "${gcBranch}" for repo "${currentRepo || 'unscoped'}"${cached ? ' (cached)' : ''}.`;
+    return `[gc-tree] no match: gc-branch="${gcBranch}" repo="${currentRepo || 'unscoped'}"${cached ? ' cached=true' : ''}.`;
 }
 function buildMatchContext({ gcBranch, currentRepo, repoScopeStatus, matches, }) {
-    return [
-        `[gc-tree] found ${Math.min(matches.length, 3)} matching context doc(s) in gc-branch "${gcBranch}" for repo "${currentRepo || 'unscoped'}" (scope: ${repoScopeStatus}).`,
+    const lines = [
+        `[gc-tree] USE FIRST: ${Math.min(matches.length, 3)} docs gc-branch="${gcBranch}" repo="${currentRepo || 'unscoped'}" scope=${repoScopeStatus}.`,
         formatMatches(matches),
-        `Use these summaries first; read full docs with \`gctree resolve --id <id>\` only if needed.`,
-    ].join('\n');
+        `Rule: apply these docs before tools; if insufficient, open full doc: gctree resolve --id <id>`,
+    ];
+    if (repoScopeStatus === 'unmapped' && currentRepo) {
+        lines.push(`Note: repo "${currentRepo}" is unmapped. If it belongs here, offer to run: gctree set-repo-scope --branch ${gcBranch} --include`);
+    }
+    return lines.join('\n');
 }
 function buildSelfReviewAppend(promptCount) {
     return [
-        `\n[gc-tree] CONTEXT SELF-REVIEW (every ${SELF_REVIEW_INTERVAL} prompts — this is prompt #${promptCount}):`,
-        `At the END of your response to this task, review the current gc-tree global context and compare it against what you have observed or changed in this session.`,
-        `If any docs need updating (new conventions discovered, corrected info, new repos or workflows, outdated content), propose the specific changes to the user and ask whether to apply them.`,
-        `Use \`/gc-update-global-context\` (Claude Code), \`$gc-update-global-context\` (Codex), or \`gctree update-global-context\` (CLI) to apply.`,
-        `If nothing meaningful changed, skip silently — do not mention this review to the user.`,
+        `\n[gc-tree] self-review #${promptCount}: silently check whether durable context should change. If yes, propose a targeted gc-tree update; otherwise say nothing.`,
     ].join('\n');
 }
 async function readHookCache(home, sessionId) {
@@ -83,7 +85,12 @@ function nextCacheState(previous, { sessionId, gcBranch, currentRepo, repoScopeS
         branch_empty: changed ? false : previous.branch_empty,
         branch_excluded: changed ? false : previous.branch_excluded,
         no_match_signatures: changed ? [] : previous.no_match_signatures,
+        unmapped_shown_repos: previous?.unmapped_shown_repos ?? [],
         prompt_count: (previous?.prompt_count ?? 0) + 1,
+        last_session_start_signature: previous?.last_session_start_signature,
+        last_session_start_at: previous?.last_session_start_at,
+        last_prompt_signature: previous?.last_prompt_signature,
+        last_prompt_at: previous?.last_prompt_at,
         updated_at: new Date().toISOString(),
     };
 }
@@ -100,7 +107,31 @@ export async function dispatchGcTreeHook({ event, home, payload, }) {
     const mapping = await readBranchRepoMap(home);
     const repoScopeStatus = branchScopeStatus(mapping, gcBranch, currentRepo);
     const sessionId = readSessionId(payload);
+    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,
@@ -117,12 +148,19 @@ export async function dispatchGcTreeHook({ event, home, payload, }) {
         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;
@@ -137,21 +175,42 @@ export async function dispatchGcTreeHook({ event, home, payload, }) {
         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 query = currentRepo ? `${currentRepo} ${prompt}` : prompt;
+        // 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 (cache.no_match_signatures.includes(signature)) {
+        if (!isUnmapped && cache.no_match_signatures.includes(signature)) {
             additionalContext = buildNoMatchContext({ gcBranch, currentRepo, cached: true });
         }
         else {
             const result = await resolveContext({ home, branch: gcBranch, query });
-            if (result.matches.length === 0) {
+            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 {
-                cache.no_match_signatures = cache.no_match_signatures.filter((entry) => entry !== signature);
-                additionalContext = buildMatchContext({ gcBranch, currentRepo, repoScopeStatus, matches: result.matches });
+                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 });
             }
         }
         if (cache.prompt_count > 0 && cache.prompt_count % SELF_REVIEW_INTERVAL === 0) {
@@ -159,7 +218,7 @@ export async function dispatchGcTreeHook({ event, home, payload, }) {
             cache.prompt_count = 0;
         }
     }
-    cache.updated_at = new Date().toISOString();
+    cache.updated_at = now.toISOString();
     await writeHookCache(home, cache);
     return { hookSpecificOutput: { hookEventName: event, additionalContext } };
 }

package/dist/src/scaffold.js

@@ -14,9 +14,9 @@ function renderCodexAgentsSnippet() {
         '  3. If the concept exists in a doc but was not indexed → propose adding it as an Index Entry to that doc.',
         '  4. If it does not exist anywhere → decide whether a new doc is needed and propose it to the user.',
         '  — If the repo is **unmapped** or **excluded**: do step 1 only; if no match, skip and proceed normally.',
-        '- When a UserPromptSubmit hook provides `[gc-tree] PRE-TASK CONTEXT`, treat it as mandatory pre-reading before any tool use.',
-        '- If the injected summaries contain enough information to answer the question or complete the task, respond directly from them **without calling any tools**. Do not grep, explore, or read code files to confirm what the summaries already cover.',
-        '- Only use tools if the summaries are clearly insufficient — meaning the answer cannot be derived from them at all.',
+        '- When a UserPromptSubmit hook provides `[gc-tree] USE FIRST`, treat matched docs as mandatory grounding before any tool use.',
+        '- Do not ignore matched gc-tree docs and jump straight to grep/Explore. Use the listed docs directly, or open the full doc with `gctree resolve --id <id>` if the summary is not enough.',
+        '- Only use tools after the matched docs are clearly insufficient for the task.',
         '- If hooks are unavailable or clearly stale, run `gctree status` and `gctree resolve --query "<task>"` yourself before planning or implementation.',
         '- Use `$gc-onboard` only for an empty gc-branch.',
         '- Use `$gc-update-global-context` when durable context in the active gc-branch should change.',
@@ -33,8 +33,8 @@ function renderCodexBootstrapPrompt() {
         '  2. If that misses, run broader related `gctree resolve` queries.',
         '  3. If the concept is documented but not indexed, propose adding it as an Index Entry to the right doc.',
         '  4. Only if gc-tree still does not answer it should you search code or repo docs.',
-        '- When hook-injected PRE-TASK CONTEXT is present, read it first. If summaries already answer the question, respond directly without any tool calls.',
-        '- Only use tools (grep, file read, explore) if summaries are clearly insufficient — meaning the answer cannot be derived from them at all.',
+        '- When hook-injected gc-tree matches are present, treat them as mandatory grounding. Use them directly or open the full doc with `gctree resolve --id <id>` before grep/file reads/code exploration.',
+        '- Only use tools (grep, file read, explore) if matched docs are clearly insufficient — meaning the answer cannot be derived from them at all.',
         '- If hook context is missing, resolve reusable global context before planning or implementation.',
         '- Treat gctree docs as explicit source-of-truth markdown, not hidden memory.',
         '',
@@ -130,9 +130,9 @@ function renderClaudeSnippet() {
         '  3. If the concept exists in a doc but was not indexed → propose adding it as an Index Entry to that doc.',
         '  4. If it does not exist anywhere → decide whether a new doc is needed and propose it to the user.',
         '  — If the repo is **unmapped** or **excluded**: do step 1 only; if no match, skip and proceed normally.',
-        '- When a UserPromptSubmit hook provides `[gc-tree] PRE-TASK CONTEXT`, treat it as mandatory pre-reading before any tool use.',
-        '- If the injected summaries contain enough information to answer the question or complete the task, respond directly from them **without calling any tools**. Do not grep, explore, or read code files to confirm what the summaries already cover.',
-        '- Only use tools if the summaries are clearly insufficient — meaning the answer cannot be derived from them at all.',
+        '- When a UserPromptSubmit hook provides `[gc-tree] USE FIRST`, treat matched docs as mandatory grounding before any tool use.',
+        '- Do not ignore matched gc-tree docs and jump straight to grep/Explore. Use the listed docs directly, or open the full doc with `gctree resolve --id <id>` if the summary is not enough.',
+        '- Only use tools after the matched docs are clearly insufficient for the task.',
         '- If hooks are unavailable or clearly stale, run `gctree status` and `gctree resolve --query "<task>"` yourself before planning or implementation.',
         '- Use `/gc-onboard` only for an empty gc-branch.',
         '- Use `/gc-update-global-context` when durable context in the active gc-branch should change.',

package/docs/usage.es.md

@@ -157,7 +157,7 @@ Si un repositorio recién relevante también debería pasar a formar parte del c
 
 `gctree init` instala la superficie global de hooks orientada al proveedor. `gctree scaffold` instala un override local en un directorio de destino cuando un repositorio concreto necesita sus propios snippets markdown o una superficie de comandos local.
 
-El hook UserPromptSubmit solo inyecta contexto previo compacto: estado found/no-match, IDs de documentos coincidentes y resúmenes. No incluye excerpts largos por defecto; abre documentos completos con `gctree resolve --id <id>` cuando el resumen no sea suficiente.
+El hook UserPromptSubmit solo inyecta contexto previo compacto: estado found/no-match más títulos e IDs de documentos coincidentes. No incluye resúmenes ni excerpts largos por defecto; abre documentos completos con `gctree resolve --id <id>` cuando sea necesario.
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo

package/docs/usage.ja.md

@@ -157,7 +157,7 @@ gctree ugc
 
 `gctree init` はグローバルなプロバイダーフック面をインストールします。`gctree scaffold` は特定のリポジトリに独自の markdown スニペットやローカルなコマンド面が必要なときに、ターゲットディレクトリへローカル override をインストールします。
 
-UserPromptSubmit フックが注入するのは compact な pre-task context だけです。found/no-match 状態、マッチしたドキュメント ID、要約を示し、長い excerpt はデフォルトではインラインしません。要約だけで足りない場合は `gctree resolve --id <id>` で全文を開きます。
+UserPromptSubmit フックが注入するのは compact な pre-task context だけです。found/no-match 状態と、マッチしたドキュメントのタイトル/ID を示します。要約や長い excerpt はデフォルトではインラインしません。必要な場合は `gctree resolve --id <id>` で全文を開きます。
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo

package/docs/usage.ko.md

@@ -157,7 +157,7 @@ gctree ugc
 
 `gctree init`은 전역 프로바이더 훅 표면을 설치합니다. `gctree scaffold`는 특정 저장소에 자체 markdown 스니펫이나 로컬 명령 표면이 필요할 때 대상 디렉토리에 로컬 override를 설치합니다.
 
-UserPromptSubmit 훅은 compact pre-task context만 주입합니다: 찾음/no-match 상태, 매칭된 문서 ID, 요약입니다. 기본적으로 긴 excerpt를 인라인하지 않으며, 요약만으로 부족할 때 `gctree resolve --id <id>`로 전체 문서를 엽니다.
+UserPromptSubmit 훅은 compact pre-task context만 주입합니다: 찾음/no-match 상태와 매칭된 문서 제목/ID입니다. 기본적으로 요약이나 긴 excerpt를 인라인하지 않으며, 필요할 때 `gctree resolve --id <id>`로 전체 문서를 엽니다.
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo

package/docs/usage.md

@@ -157,7 +157,7 @@ If a newly relevant repo should also become part of the durable context, the nat
 
 `gctree init` installs the provider-facing hook surface globally. `gctree scaffold` installs a local override into one target directory when a specific repository needs its own markdown snippets or local command surface.
 
-The UserPromptSubmit hook injects compact pre-task context only: found/no-match state, matched document IDs, and summaries. It does not inline long excerpts by default; open full documents with `gctree resolve --id <id>` when the summary is not enough.
+The UserPromptSubmit hook injects compact pre-task context only: found/no-match state plus matched document titles and IDs. It does not inline summaries or long excerpts by default; open full documents with `gctree resolve --id <id>` when needed.
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo

package/docs/usage.zh.md

@@ -157,7 +157,7 @@ gctree ugc
 
 `gctree init` 会安装全局 provider hook 表面。`gctree scaffold` 则在某个仓库需要自己的 markdown 片段或本地命令表面时，将本地 override 安装到目标目录中。
 
-UserPromptSubmit hook 只注入紧凑的 pre-task context：found/no-match 状态、匹配文档 ID 和摘要。默认不内联长 excerpt；当摘要不够时，用 `gctree resolve --id <id>` 打开完整文档。
+UserPromptSubmit hook 只注入紧凑的 pre-task context：found/no-match 状态以及匹配文档的标题/ID。默认不内联摘要或长 excerpt；需要时用 `gctree resolve --id <id>` 打开完整文档。
 
 ```bash
 gctree scaffold --host codex --target /path/to/repo

package/package.json

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