@handsupmin/gc-tree 0.8.16 → 0.8.18

package/dist/src/markdown.js

@@ -123,14 +123,21 @@ export function renderIndexMarkdown(input) {
     }
     else {
         const categoryOrder = ['role', 'repos', 'domain', 'workflows', 'conventions', 'infra', 'verification', 'general'];
-        const grouped = new Map();
+        // Group by category, then by path within category
+        const byCategory = new Map();
         for (const doc of input.docs) {
             const category = normalizeCategory(doc.category || deriveCategoryFromPath(doc.path));
-            if (!grouped.has(category))
-                grouped.set(category, []);
-            grouped.get(category).push(doc);
+            if (!byCategory.has(category))
+                byCategory.set(category, new Map());
+            const byPath = byCategory.get(category);
+            if (!byPath.has(doc.path))
+                byPath.set(doc.path, []);
+            const label = (doc.label || doc.title).trim();
+            if (label && !byPath.get(doc.path).includes(label)) {
+                byPath.get(doc.path).push(label);
+            }
         }
-        const categories = [...grouped.keys()].sort((a, b) => {
+        const categories = [...byCategory.keys()].sort((a, b) => {
             const ai = categoryOrder.indexOf(a);
             const bi = categoryOrder.indexOf(b);
             if (ai === -1 && bi === -1)
@@ -143,9 +150,12 @@ export function renderIndexMarkdown(input) {
         });
         for (const category of categories) {
             lines.push(`## ${displayCategory(category)}`, '');
-            for (const doc of grouped.get(category).sort((a, b) => (a.label || a.title).localeCompare(b.label || b.title))) {
-                lines.push(`- ${doc.label || doc.title}`);
-                lines.push(`  - ${doc.path}`);
+            const byPath = byCategory.get(category);
+            for (const [path, labels] of [...byPath.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+                lines.push(`- ${path}`);
+                for (const label of labels) {
+                    lines.push(`  - ${label}`);
+                }
             }
             lines.push('');
         }
@@ -182,41 +192,55 @@ export function displayCategory(category) {
 }
 export function parseIndexEntries(indexContent) {
     let currentCategory = 'general';
-    let pendingLabel = null;
+    let pendingLabel = null; // legacy: label before indented path
+    let currentPath = null; // new: path before indented labels
     const entries = [];
     for (const rawLine of String(indexContent || '').split(/\r?\n/)) {
         const line = rawLine.trimEnd();
         const trimmed = line.trim();
         if (!trimmed) {
             pendingLabel = null;
+            currentPath = null;
             continue;
         }
         const heading = trimmed.match(/^##\s+(.+)$/);
         if (heading) {
             currentCategory = normalizeCategory(heading[1] || 'general');
             pendingLabel = null;
+            currentPath = null;
             continue;
         }
         if (trimmed.startsWith('- gc-branch:') || trimmed.startsWith('- summary:') || trimmed === '- No source docs yet.') {
             pendingLabel = null;
+            currentPath = null;
             continue;
         }
-        const pathMatch = rawLine.match(/^\s{2,}-\s+(docs\/.+)$/);
-        if (pathMatch && pendingLabel) {
-            const path = pathMatch[1].trim();
-            const category = deriveCategoryFromPath(path) || currentCategory;
-            entries.push({
-                id: docIdFromPath(path),
-                title: pendingLabel,
-                label: pendingLabel,
-                category,
-                path,
-            });
+        const isIndented = /^\s{2,}/.test(rawLine);
+        const itemText = trimmed.replace(/^-\s*/, '');
+        if (!isIndented) {
+            // Top-level list item
+            if (itemText.startsWith('docs/')) {
+                // New format: path is top-level
+                currentPath = itemText;
+                pendingLabel = null;
+            }
+            else {
+                // Legacy format: label is top-level
+                pendingLabel = itemText;
+                currentPath = null;
+            }
             continue;
         }
-        const labelMatch = trimmed.match(/^-\s+(.+)$/);
-        if (labelMatch) {
-            pendingLabel = labelMatch[1].trim();
+        // Indented item
+        if (currentPath && !itemText.startsWith('docs/')) {
+            // New format: keyword under path
+            const category = deriveCategoryFromPath(currentPath) || currentCategory;
+            entries.push({ id: docIdFromPath(currentPath), title: itemText, label: itemText, category, path: currentPath });
+        }
+        else if (pendingLabel && itemText.startsWith('docs/')) {
+            // Legacy format: path under label
+            const category = deriveCategoryFromPath(itemText) || currentCategory;
+            entries.push({ id: docIdFromPath(itemText), title: pendingLabel, label: pendingLabel, category, path: itemText });
         }
     }
     return entries;

package/dist/src/onboarding-protocol.js

@@ -33,11 +33,10 @@ export function onboardingProtocolLines() {
         'Synthesize the interview into an encyclopedia-style context set with many small docs instead of a few broad docs.',
         'Prefer category directories such as `docs/role/`, `docs/repos/`, `docs/domain/`, `docs/workflows/`, `docs/conventions/`, and `docs/infra/` whenever that split fits the material.',
         'Prefer one concept, one repository, one workflow, or one convention per file when possible.',
-        '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.',
+        'Index entries are the search surface — maximize keyword density. For each doc, generate index entries from: primary concept names, aliases, repo nicknames, workflow names, field names, command names, acronyms, related terms a developer might search for, and any term that would make someone want to open this doc. Do NOT be conservative — more keywords means more chances of being found.',
+        'The index format groups keywords under their path: top-level `- docs/path.md` with indented `  - keyword` lines under it. This keeps the index compact while allowing many keywords per doc.',
         '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.',
         '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.',
     ];
 }
 export function onboardingCompletionLines() {
@@ -45,8 +44,12 @@ export function onboardingCompletionLines() {
         'Before you claim onboarding is complete, run `gctree verify-onboarding --branch <current-gc-branch>` and inspect the real gc-tree files.',
         'Do not claim onboarding is complete unless verification returns `status: "complete"` **and** `quality_issues` is an empty array.',
         'If `quality_issues` is non-empty, do **not** tell the user onboarding is done. Self-heal immediately without asking the user: (a) identify which docs have `category: "general"`, (b) assign each a correct category from `role | repos | domain | workflows | conventions | infra | verification` based on content, (c) rebuild the full onboarding JSON with every doc having an explicit `category` field set to one of those values, (d) run `gctree __apply-onboarding --input <temp-file>` again, (e) rerun `gctree verify-onboarding` and repeat until `quality_issues` is empty. Never use `"general"` as a category in the JSON — it is a fallback for missing data, not a valid category.',
+        'After quality_issues passes, perform a summary quality check: read the actual `## Summary` section of each written doc file. If any summary reads like a table of contents entry ("이 문서는 X를 설명합니다", "X에 대한 패턴 모음") rather than actionable content (real patterns, commands, constraints), rewrite it in-place before continuing.',
+        'After summary check, perform an index coverage check: for every written doc, read its `## Index Entries` section and verify that the entries cover a wide range of terms a developer would search for — not just the exact document title. If a doc has fewer than 5 index entries, it almost certainly needs more. Add aliases, related terms, command names, field names, and workflow names. Re-apply if entries were added.',
         'If verification returns `status: "incomplete"` for reasons other than quality_issues, do not tell the user onboarding is done; inspect the reported failures, heal what can be healed automatically, rerun verification, and repeat until it passes or a real blocker remains.',
         'After applying the onboarding docs, explicitly list which durable docs were saved.',
+        'Before the final summary, run a coverage checklist and ask the user to confirm each area: (a) workflows — are the key cross-repo action sequences documented? (b) conventions — are the code patterns for each repo documented? (c) repos — is each relevant repo covered with role, paths, and cross-repo deps? (d) domain terms / glossary — are important acronyms and terms indexed? Present this as a numbered checklist and ask the user: "이 중 빠진 것이 있으면 말씀해주세요. 없으면 완료하겠습니다." Do not skip this step.',
+        'If the user identifies missing areas, gather the information and add the docs before continuing.',
         'Then summarize what you now understand from the saved docs instead of stopping at the filenames alone.',
         'For that final summary, do not ask an open-ended validation question first; present the summary and ask the user to choose only one structured confirmation: 1. This matches well enough. 2. Some parts are wrong. I will give the delta. 3. The frame is wrong. I will restate it.',
         'If the user picks 2 or 3 for the final summary, ask only for the correction delta or replacement frame, then update the saved understanding instead of restarting the interview.',

package/dist/src/scaffold.js

@@ -104,18 +104,36 @@ function renderCodexOnboardSkill() {
         '',
     ].join('\n');
 }
+function renderUpdateProtocol() {
+    return [
+        '1. Run `gctree status` and state the active gc-branch.',
+        '2. Understand what changed — read the user\'s request, inspect relevant code or docs if needed, and determine the right content to capture.',
+        '3. Decide category and path automatically based on content — never ask the user about scope or placement:',
+        '   - `docs/workflows/<name>.md` — cross-repo action sequences, step-by-step procedures',
+        '   - `docs/conventions/<repo>.md` — code patterns, naming, validation, DTO/service conventions for a repo',
+        '   - `docs/repos/<repo>.md` — repo role, key paths, cross-repo dependencies',
+        '   - `docs/domain/<concept>.md` — domain terms, acronyms, business logic',
+        '   - `docs/infra/<topic>.md` — infra, deployment, environment config',
+        '   - `docs/role/<name>.md` — team member roles, responsibilities',
+        '4. Write a `## Summary` that is actionable: actual patterns/commands/constraints a developer needs — not a sentence about what the doc covers.',
+        '5. Include a `## Index Entries` section in each doc\'s content with many keywords: aliases, related terms, command names, field names, workflow names, acronyms. More entries = more chances of being found by `gctree resolve`. Fewer than 5 entries almost always means more are needed.',
+        '6. Create a temporary JSON file with the updated `docs[]` and run `gctree __apply-update --input <temp-file>`.',
+        '7. Run `gctree verify-onboarding --branch <gc-branch>` and inspect the output:',
+        '   - Check that every updated doc appears in the verified doc list.',
+        '   - Check that index entries for the new content exist and are searchable (not just generic titles).',
+        '   - Check that no doc has `category: "general"` — reassign to correct category if so.',
+        '   - Check that important concepts from the update are present as index labels — if missing, re-apply with added index entries.',
+        '   - Self-heal any issues without asking the user: fix category, add index entries, re-run `gctree __apply-update`, re-verify.',
+        '8. Show the user which docs were updated and confirm the index now covers the new content.',
+    ];
+}
 function renderCodexUpdateSkill() {
     return [
         '---',
         'description: Guided durable update for the active gc-branch in gctree.',
         '---',
         '',
-        '1. Run `gctree status` and explicitly state the active gc-branch to the user.',
-        '2. Ask what durable context should change, one question at a time.',
-        '3. If this repo clearly belongs to the current gc-branch but is not mapped yet, ask the user whether it should be added to the branch-repo map and run `gctree set-repo-scope --branch <current-gc-branch> --include` when they approve.',
-        '4. Create a temporary JSON file containing the updated `docs[]` and optional `branchSummary`.',
-        '5. Run `gctree __apply-update --input <temp-file>`.',
-        '6. Show the updated docs back to the user.',
+        ...renderUpdateProtocol(),
         '',
     ].join('\n');
 }
@@ -222,12 +240,7 @@ function renderClaudeUpdateCommand() {
         'description: Guided durable update for the active gc-branch in gctree.',
         '---',
         '',
-        '1. Run `gctree status` and explicitly state the active gc-branch to the user.',
-        '2. Ask what durable context should change, one question at a time.',
-        '3. If this repo clearly belongs to the current gc-branch but is not mapped yet, ask the user whether it should be added to the branch-repo map and run `gctree set-repo-scope --branch <current-gc-branch> --include` when they approve.',
-        '4. Create a temporary JSON file containing the updated `docs[]` and optional `branchSummary`.',
-        '5. Run `gctree __apply-update --input <temp-file>`.',
-        '6. Show the updated docs back to the user.',
+        ...renderUpdateProtocol(),
         '',
     ].join('\n');
 }

package/package.json

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

package/skills/onboard/SKILL.md

@@ -43,10 +43,10 @@ Use this when a user wants to create global context for a product, company, or w
 - 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
-- treat `index.md` as concept-first: surface the keywords a user or AI would search for, not just broad document titles
+- treat `index.md` as the search surface — maximize keyword density; for each doc generate entries from: primary names, aliases, nicknames, field names, command names, acronyms, related terms a developer might search for; do NOT be conservative — more keywords = more chances of being found; fewer than 5 index entries per doc almost certainly means more are needed
 - 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 `index.md` as a human-readable dictionary-style TOC grouped by category headings and `label -> path` entries
+- index format: top-level `- docs/path.md` with indented `  - keyword` lines under it — groups all keywords per doc, eliminates path duplication
 - every doc in the JSON **must** have an explicit `category` field set to one of: `role`, `repos`, `domain`, `workflows`, `conventions`, `infra`, `verification` — never use `"general"` as a category; it is a fallback for missing data, not a valid category choice
 - use onboarding only for an empty gc-branch
 
@@ -88,12 +88,14 @@ Use this when a user wants to create global context for a product, company, or w
 22. Ask for company/domain glossary terms and acronyms that should become durable context.
 23. Ask which verification commands should be treated as defaults for this gc-branch.
 24. Structure the durable docs as a small encyclopedia: split by category directory, keep one concept/repo/workflow/convention per file when possible, and keep a short `## Summary` at the top of each doc.
-25. Render `index.md` as a category-grouped dictionary-style table of contents with `label -> path` entries.
+25. Render `index.md` grouped by category; within each category list each doc path as a top-level item with all its keywords as indented children. Maximize keywords per doc — aliases, related terms, command names, field names, workflow names.
 26. Launch the guided onboarding flow with `gctree onboard [--branch <name>]`.
 27. Before you claim onboarding is complete, run `gctree verify-onboarding --branch <current-gc-branch>` and inspect the real gc-tree files.
 28. Do not claim onboarding is complete unless verification returns `status: "complete"` **and** `quality_issues` is an empty array.
 29. If `quality_issues` is non-empty, do **not** tell the user onboarding is done. Self-heal immediately without prompting the user: (a) identify which docs have `category: "general"`, (b) assign each a correct category from `role | repos | domain | workflows | conventions | infra | verification` based on content, (c) rebuild the full onboarding JSON with every doc having an explicit `category` field — never use `"general"` as a category, (d) rerun `gctree __apply-onboarding --input <temp-file>`, (e) rerun `gctree verify-onboarding`, repeat until `quality_issues` is empty. If `status` is `"incomplete"` for other reasons, inspect the failures, heal them autonomously, and repeat.
 30. After the onboarding docs are written, explicitly list which durable docs were saved.
+30a. Run a coverage checklist before the final summary. Ask the user to confirm each area: (a) workflows — are key cross-repo action sequences documented? (b) conventions — are code patterns for each repo documented with a `## Patterns` section? (c) repos — is each relevant repo covered with role, paths, and cross-repo deps? (d) domain/glossary — are important acronyms and terms indexed with enough keywords? Present as a numbered checklist: "이 중 빠진 것이 있으면 말씀해주세요. 없으면 완료하겠습니다." If the user identifies gaps, gather and add before continuing. Do not skip this step.
+30b. Check index keyword density: read the `## Index Entries` section of each written doc. If any doc has fewer than 5 entries, add more — aliases, related terms, command names, field names, workflow names. Re-apply if entries were added.
 31. Summarize what you now understand from the saved docs instead of ending at the filenames alone.
 32. For that final summary, do not ask an open-ended validation question first. Present the summary and ask the user to choose only one:
    - 1. This matches well enough.