@handsupmin/gc-tree 0.8.4 → 0.8.6

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,44 @@ 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}).`,
+        `[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.`,
+        `Rule: apply these docs before tools; if insufficient, open full doc: gctree resolve --id <id>`,
     ].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) {
@@ -84,6 +82,10 @@ function nextCacheState(previous, { sessionId, gcBranch, currentRepo, repoScopeS
         branch_excluded: changed ? false : previous.branch_excluded,
         no_match_signatures: changed ? [] : previous.no_match_signatures,
         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 +102,30 @@ 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 ?? [],
+            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 +142,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;
@@ -159,7 +191,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/repo-map.js

@@ -132,7 +132,8 @@ export async function resolveBranchForRepo({ home, head, explicitBranch, cwd = p
 }
 export async function promptResolveScopeDecision(branch, repo, preferredLanguage = 'English') {
     if (!stdin.isTTY && process.env.GCTREE_ALLOW_STDIN_PROMPT !== '1') {
-        throw new Error(`current repo \"${repo}\" is not mapped to gc-branch \"${branch}\". Run interactively to choose whether to continue, include this repo, or ignore this gc-branch here.`);
+        process.stderr.write(`gc-tree: repo "${repo}" is not mapped to gc-branch "${branch}" — continuing without scope decision.\n`);
+        return 'continue-once';
     }
     const rl = createInterface({ input: stdin, output: stderr });
     try {

package/dist/src/scaffold.js

@@ -8,14 +8,15 @@ function renderCodexAgentsSnippet() {
         '',
         '- Treat the active gctree branch as a **gc-branch** when you describe it to users.',
         '- gctree init installs SessionStart and UserPromptSubmit hooks that auto-check gc-tree before work.',
-        '- When you encounter an unfamiliar term, acronym, concept, or domain word, follow this protocol **before** grepping or reading code files:',
-        '  1. Run `gctree resolve --query "<term>"` — if matched, use the result directly.',
-        '  2. If no match, try broader related queries to check if the concept lives in any doc.',
-        '  3. If the concept exists in a doc but was not indexed → propose adding it as an Index Entry to that doc (so future resolves find it).',
+        '- When you encounter an unfamiliar term, acronym, concept, or domain word, follow this scope-aware protocol **before** grepping or reading code files:',
+        '  1. Always run `gctree resolve --query "<term>"` first. If matched, use the result directly.',
+        '  2. Only if the current repo scope is **included** (not unmapped/excluded): if step 1 found nothing, try broader related queries to check if the concept exists in any doc.',
+        '  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.',
-        '- 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.',
+        '  — 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] 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.',
@@ -32,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.',
         '',
@@ -123,14 +124,15 @@ function renderClaudeSnippet() {
         '',
         '- Treat the active gctree branch as a **gc-branch** in user-facing language.',
         '- gctree init installs SessionStart and UserPromptSubmit hooks that auto-inject gc-tree context before every prompt.',
-        '- When you encounter an unfamiliar term, acronym, concept, or domain word, follow this protocol **before** grepping or reading code files:',
-        '  1. Run `gctree resolve --query "<term>"` — if matched, use the result directly.',
-        '  2. If no match, try broader related queries to check if the concept lives in any doc.',
-        '  3. If the concept exists in a doc but was not indexed → propose adding it as an Index Entry to that doc (so future resolves find it).',
+        '- When you encounter an unfamiliar term, acronym, concept, or domain word, follow this scope-aware protocol **before** grepping or reading code files:',
+        '  1. Always run `gctree resolve --query "<term>"` first. If matched, use the result directly.',
+        '  2. Only if the current repo scope is **included** (not unmapped/excluded): if step 1 found nothing, try broader related queries to check if the concept exists in any doc.',
+        '  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.',
-        '- 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.',
+        '  — 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] 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.4",
+  "version": "0.8.6",
   "description": "Global Context Tree, a lightweight branch-aware global context orchestrator for AI coding tools",
   "type": "module",
   "private": false,