@handsupmin/gc-tree 0.8.2 → 0.8.4

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.
+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>`.
 
 - **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 をセッション中キャッシュします。
+その後は、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를 캐시합니다.
+이후 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.
+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>`.
 
 - **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。
+之后，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

@@ -18,7 +18,7 @@ function limitMatches(matches, max = 3) {
 }
 function formatMatches(matches) {
     return limitMatches(matches)
-        .map((match, index) => `${index + 1}. ${match.title} [id=${match.id}]\n   Summary: ${match.summary}\n   Excerpt: ${match.excerpt}`)
+        .map((match, index) => `${index + 1}. ${match.title} [id=${match.id}]: ${match.summary}`)
         .join('\n');
 }
 function buildSessionStartContext({ gcBranch, currentRepo, repoScopeStatus, }) {
@@ -31,33 +31,19 @@ function buildSessionStartContext({ gcBranch, currentRepo, repoScopeStatus, }) {
     ].join(' ');
 }
 function buildEmptyBranchContext({ gcBranch, currentRepo, cached, }) {
-    return [
-        `gc-tree auto-resolve ${cached ? 'used cached state' : 'checked the active gc-branch'} and found no reusable global context for this session because gc-branch "${gcBranch}" currently has 0 docs.`,
-        `Repo: ${currentRepo || 'unscoped'}.`,
-        `Treat this as "no reusable global context yet" until the gc-branch content changes or a different repo/gc-branch is active.`,
-    ].join(' ');
+    return `[gc-tree] no context docs in gc-branch "${gcBranch}" for repo "${currentRepo || 'unscoped'}"${cached ? ' (cached)' : ''}.`;
 }
 function buildExcludedContext({ gcBranch, currentRepo, cached, }) {
-    return [
-        `gc-tree auto-resolve ${cached ? 'used cached state' : 'checked the active gc-branch'} and found that repo "${currentRepo || 'unknown'}" is excluded from gc-branch "${gcBranch}".`,
-        `No reusable global context applies here unless the branch-repo mapping changes.`,
-    ].join(' ');
+    return `[gc-tree] repo "${currentRepo || 'unknown'}" is excluded from gc-branch "${gcBranch}"${cached ? ' (cached)' : ''}.`;
 }
-function buildNoMatchContext({ gcBranch, currentRepo, query, cached, }) {
-    return [
-        `gc-tree auto-resolve ${cached ? 'skipped a redundant lookup using cached no-match state' : 'checked the active gc-branch'} and found no reusable global context for this prompt in gc-branch "${gcBranch}".`,
-        `Repo: ${currentRepo || 'unscoped'}.`,
-        `Query: "${query}".`,
-        `Only re-run resolve if the repo, gc-branch, or task changes materially.`,
-    ].join(' ');
+function buildNoMatchContext({ gcBranch, currentRepo, cached, }) {
+    return `[gc-tree] no matching context in gc-branch "${gcBranch}" for repo "${currentRepo || 'unscoped'}"${cached ? ' (cached)' : ''}.`;
 }
-function buildMatchContext({ gcBranch, currentRepo, repoScopeStatus, query, matches, }) {
+function buildMatchContext({ gcBranch, currentRepo, repoScopeStatus, matches, }) {
     return [
-        `[gc-tree] PRE-TASK CONTEXT — read before any tool use or code exploration.`,
-        `gc-branch: "${gcBranch}" | repo: "${currentRepo || 'unscoped'}" (scope: ${repoScopeStatus}) | query: "${query}".`,
-        `If these 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 to confirm what the summaries already cover. Only use tools if the summaries are clearly insufficient.`,
+        `[gc-tree] found ${Math.min(matches.length, 3)} matching context doc(s) in gc-branch "${gcBranch}" for repo "${currentRepo || 'unscoped'}" (scope: ${repoScopeStatus}).`,
         formatMatches(matches),
-        `Read full docs (gctree resolve --id <id>) only if summaries are clearly insufficient — meaning the answer cannot be derived from them at all.`,
+        `Use these summaries first; read full docs with \`gctree resolve --id <id>\` only if needed.`,
     ].join('\n');
 }
 function buildSelfReviewAppend(promptCount) {
@@ -155,17 +141,17 @@ export async function dispatchGcTreeHook({ event, home, payload, }) {
         const query = currentRepo ? `${currentRepo} ${prompt}` : prompt;
         const signature = hashQuery(query);
         if (cache.no_match_signatures.includes(signature)) {
-            additionalContext = buildNoMatchContext({ gcBranch, currentRepo, query, cached: true });
+            additionalContext = buildNoMatchContext({ gcBranch, currentRepo, cached: true });
         }
         else {
             const result = await resolveContext({ home, branch: gcBranch, query });
             if (result.matches.length === 0) {
                 cache.no_match_signatures = [...new Set([...cache.no_match_signatures, signature])];
-                additionalContext = buildNoMatchContext({ gcBranch, currentRepo, query, cached: false });
+                additionalContext = buildNoMatchContext({ gcBranch, currentRepo, cached: false });
             }
             else {
                 cache.no_match_signatures = cache.no_match_signatures.filter((entry) => entry !== signature);
-                additionalContext = buildMatchContext({ gcBranch, currentRepo, repoScopeStatus, query, matches: result.matches });
+                additionalContext = buildMatchContext({ gcBranch, currentRepo, repoScopeStatus, matches: result.matches });
             }
         }
         if (cache.prompt_count > 0 && cache.prompt_count % SELF_REVIEW_INTERVAL === 0) {

package/dist/src/verify-onboarding.js

@@ -1,6 +1,9 @@
-import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
 import { parseIndexEntries } from './markdown.js';
-import { branchIndexPath, DEFAULT_BRANCH } from './paths.js';
+import { resolveContext } from './resolve.js';
+import { branchDocsDir, branchIndexPath, DEFAULT_BRANCH } from './paths.js';
 import { ensureBranchExists, statusForBranch } from './store.js';
 const VALID_CATEGORIES = new Set(['role', 'repos', 'domain', 'workflows', 'conventions', 'infra', 'verification']);
 export async function verifyOnboarding({ home, branch, }) {
@@ -12,6 +15,42 @@ export async function verifyOnboarding({ home, branch, }) {
     const indexedDocCount = docs.length;
     const hasDocs = status.doc_count > 0 && indexedDocCount > 0;
     const qualityIssues = [];
+    const docsDir = branchDocsDir(home, gcBranch);
+    const sourceDocs = await listSourceDocPaths(docsDir);
+    const nonIndexSourceDocs = sourceDocs.filter((path) => !/(^|\/)index\.md$/i.test(path));
+    if (sourceDocs.some((path) => /(^|\/)index\.md$/i.test(path))) {
+        qualityIssues.push('Source docs must not include docs/index.md. The branch-level index.md is the only dictionary.');
+    }
+    const indexedPaths = new Set(docs.map((doc) => doc.path));
+    for (const path of indexedPaths) {
+        if (!existsSync(join(branchDirForDoc(home, gcBranch), path))) {
+            qualityIssues.push(`Index points to a missing source doc: ${path}.`);
+        }
+    }
+    for (const path of nonIndexSourceDocs) {
+        const indexPath = `docs/${path}`;
+        if (!indexedPaths.has(indexPath)) {
+            qualityIssues.push(`Source doc is not reachable from index.md: ${indexPath}.`);
+        }
+    }
+    const pathLikeLabels = docs
+        .filter((doc) => /^\.?docs\//i.test(doc.label) || /\.md$/i.test(doc.label))
+        .map((doc) => doc.label);
+    if (pathLikeLabels.length > 0) {
+        qualityIssues.push(`Index labels must be search terms, not paths: ${dedupe(pathLikeLabels).join(', ')}.`);
+    }
+    const prefixedLabels = docs
+        .filter((doc) => /^(repo|repository|domain|workflow|convention|role|infra|verification)\s*:/i.test(doc.label))
+        .map((doc) => doc.label);
+    if (prefixedLabels.length > 0) {
+        qualityIssues.push(`Index labels must not keep category prefixes: ${dedupe(prefixedLabels).join(', ')}.`);
+    }
+    const invalidCategories = docs
+        .filter((doc) => doc.category !== 'general' && !VALID_CATEGORIES.has(doc.category))
+        .map((doc) => `${doc.label} (${doc.category})`);
+    if (invalidCategories.length > 0) {
+        qualityIssues.push(`Index contains invalid categories: ${dedupe(invalidCategories).join(', ')}.`);
+    }
     if (hasDocs && indexedDocCount >= 3) {
         const categoryCounts = new Map();
         for (const doc of docs) {
@@ -25,6 +64,25 @@ export async function verifyOnboarding({ home, branch, }) {
             const generalDocLabels = docs.filter((d) => d.category === 'general').map((d) => d.label);
             qualityIssues.push(`${generalCount} doc(s) still have category "general": ${generalDocLabels.join(', ')}. Move them to one of: ${[...VALID_CATEGORIES].join(', ')}.`);
         }
+        if (indexedDocCount >= 5) {
+            const presentCategories = new Set(docs.map((doc) => doc.category));
+            const missingCore = ['role', 'repos', 'domain', 'workflows'].filter((category) => !presentCategories.has(category));
+            if (missingCore.length > 0) {
+                qualityIssues.push(`Onboarding is missing core dictionary categories: ${missingCore.join(', ')}. Capture them or explicitly add small docs for unavailable categories.`);
+            }
+        }
+    }
+    if (status.warnings.length > 0) {
+        qualityIssues.push(...status.warnings);
+    }
+    const searchQuality = [];
+    for (const doc of docs.slice(0, 12)) {
+        const resolved = await resolveContext({ home, branch: gcBranch, query: doc.label });
+        const matched = resolved.matches.some((match) => match.path === doc.path);
+        searchQuality.push({ query: doc.label, expected_path: doc.path, matched });
+        if (!matched) {
+            qualityIssues.push(`Resolve smoke test failed: query "${doc.label}" did not return ${doc.path}.`);
+        }
     }
     const complete = hasDocs && qualityIssues.length === 0;
     return {
@@ -35,6 +93,7 @@ export async function verifyOnboarding({ home, branch, }) {
         docs,
         warnings: status.warnings,
         quality_issues: qualityIssues,
+        search_quality: searchQuality,
         message: complete
             ? `Onboarding is complete for gc-branch "${gcBranch}".`
             : hasDocs
@@ -42,3 +101,23 @@ export async function verifyOnboarding({ home, branch, }) {
                 : `Onboarding is incomplete for gc-branch "${gcBranch}". Docs or index entries are missing.`,
     };
 }
+async function listSourceDocPaths(dir, prefix = '') {
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+    const files = [];
+    for (const entry of entries) {
+        const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            files.push(...(await listSourceDocPaths(join(dir, entry.name), relative)));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md')) {
+            files.push(relative);
+        }
+    }
+    return files.sort();
+}
+function branchDirForDoc(home, branch) {
+    return join(home, 'branches', branch);
+}
+function dedupe(values) {
+    return [...new Set(values)];
+}

package/docs/usage.es.md

@@ -157,6 +157,8 @@ 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.
+
 ```bash
 gctree scaffold --host codex --target /path/to/repo
 gctree scaffold --host claude-code --target /path/to/repo

package/docs/usage.ja.md

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

package/docs/usage.ko.md

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

package/docs/usage.md

@@ -157,6 +157,8 @@ 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.
+
 ```bash
 gctree scaffold --host codex --target /path/to/repo
 gctree scaffold --host claude-code --target /path/to/repo

package/docs/usage.zh.md

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

package/package.json

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