@handsupmin/gc-tree 0.7.1 → 0.7.3

package/dist/src/cli.js

@@ -139,6 +139,11 @@ async function launchGuidedFlow({ provider, providerMode, preferredLanguage, tar
         return plan;
     return maybeLaunchProvider(plan);
 }
+function printJsonUnlessLaunched(payload, launch) {
+    if (launch?.launched)
+        return;
+    console.log(JSON.stringify(payload, null, 2));
+}
 async function main() {
     if (hasFlag('--version') || hasFlag('-v')) {
         stdout.write(`${await readPackageVersion()}\n`);
@@ -189,7 +194,7 @@ async function main() {
                     noLaunch: hasFlag('--no-launch'),
                 })
                 : null;
-            console.log(JSON.stringify({
+            printJsonUnlessLaunched({
                 ...result,
                 provider_mode: settings.provider_mode,
                 preferred_provider: settings.preferred_provider,
@@ -197,7 +202,7 @@ async function main() {
                 global_scaffold: globalScaffold,
                 scaffold,
                 launch,
-            }, null, 2));
+            }, launch);
             return;
         }
         case 'checkout': {
@@ -289,7 +294,7 @@ async function main() {
                 command: 'gc-onboard',
                 noLaunch: hasFlag('--no-launch'),
             });
-            console.log(JSON.stringify({ mode: 'guided_onboarding', gc_branch: gcBranch, preferred_provider: provider, scaffold, launch }, null, 2));
+            printJsonUnlessLaunched({ mode: 'guided_onboarding', gc_branch: gcBranch, preferred_provider: provider, scaffold, launch }, launch);
             return;
         }
         case 'verify-onboarding': {
@@ -486,7 +491,7 @@ async function main() {
                 command: 'gc-update-global-context',
                 noLaunch: hasFlag('--no-launch'),
             });
-            console.log(JSON.stringify({ mode: 'guided_update', gc_branch: gcBranch, preferred_provider: provider, scaffold, launch }, null, 2));
+            printJsonUnlessLaunched({ mode: 'guided_update', gc_branch: gcBranch, preferred_provider: provider, scaffold, launch }, launch);
             return;
         }
         case '__apply-update': {

package/dist/src/markdown.js

@@ -30,6 +30,40 @@ function parseDocReference(value) {
     }
     return null;
 }
+function parseTitlePlacement(value) {
+    const trimmed = String(value || '').trim();
+    if (!trimmed)
+        return null;
+    if (/^index$/i.test(trimmed))
+        return { category: 'index', slug: 'index', label: 'Index' };
+    const match = trimmed.match(/^(role|repo|repos|repository|repositories|domain|workflow|workflows|convention|conventions|infra|verification)\s*:\s*(.+)$/i);
+    if (!match)
+        return null;
+    const rawCategory = match[1].toLowerCase();
+    const categoryMap = {
+        role: 'role',
+        repo: 'repos',
+        repos: 'repos',
+        repository: 'repos',
+        repositories: 'repos',
+        domain: 'domain',
+        workflow: 'workflows',
+        workflows: 'workflows',
+        convention: 'conventions',
+        conventions: 'conventions',
+        infra: 'infra',
+        verification: 'verification',
+    };
+    const label = match[2].trim();
+    const category = categoryMap[rawCategory];
+    if (!category || !label)
+        return null;
+    return {
+        category,
+        slug: slugify(label),
+        label,
+    };
+}
 export function ensureSummary(summary) {
     const trimmed = String(summary || '').trim();
     if (!trimmed) {
@@ -40,6 +74,10 @@ export function ensureSummary(summary) {
 export function renderDocMarkdown(doc) {
     const summary = ensureSummary(doc.summary);
     const body = String(doc.body || '').trim();
+    const normalizedIndexEntries = [...new Set([
+            ...(doc.indexLabel?.trim() ? [doc.indexLabel.trim()] : []),
+            ...(doc.indexEntries || []).map((entry) => String(entry || '').trim()).filter(Boolean),
+        ])];
     return [
         `# ${doc.title.trim()}`,
         '',
@@ -50,8 +88,8 @@ export function renderDocMarkdown(doc) {
         ...(doc.tags && doc.tags.length > 0
             ? ['## Tags', '', ...doc.tags.map((tag) => `- ${tag}`), '']
             : []),
-        ...(doc.indexEntries && doc.indexEntries.length > 0
-            ? ['## Index Entries', '', ...doc.indexEntries.map((entry) => `- ${entry}`), '']
+        ...(normalizedIndexEntries.length > 0
+            ? ['## Index Entries', '', ...normalizedIndexEntries.map((entry) => `- ${entry}`), '']
             : []),
         '## Details',
         '',
@@ -194,6 +232,15 @@ export function normalizeIndexEntry(value, fallback) {
         return null;
     if (/^docs\/index\.md$/i.test(trimmed) || /^index\.md$/i.test(trimmed))
         return null;
+    const titlePlacement = parseTitlePlacement(trimmed);
+    if (titlePlacement) {
+        if (titlePlacement.category === 'index')
+            return null;
+        return {
+            category: titlePlacement.category,
+            label: titlePlacement.label,
+        };
+    }
     return {
         category: fallback.category,
         label: trimmed,
@@ -203,12 +250,28 @@ export function inferDocPlacement(input) {
     for (const candidate of [input.slug, input.indexLabel]) {
         const reference = parseDocReference(candidate || '');
         if (reference) {
-            return { category: reference.category, slug: reference.slug };
+            return { category: reference.category, slug: reference.slug, label: reference.label, isIndexDoc: false };
         }
     }
+    const titlePlacement = parseTitlePlacement(input.title);
+    const explicitLabel = String(input.indexLabel || '').trim();
+    const preferredLabel = explicitLabel && !parseDocReference(explicitLabel) ? explicitLabel : input.title.trim();
+    if (titlePlacement) {
+        return {
+            category: titlePlacement.category === 'index' ? null : titlePlacement.category,
+            slug: titlePlacement.slug,
+            label: explicitLabel && !parseDocReference(explicitLabel) ? explicitLabel : titlePlacement.label,
+            isIndexDoc: titlePlacement.category === 'index',
+        };
+    }
     const explicitCategory = input.category ? slugify(input.category) : null;
     const slug = slugify(input.slug || input.indexLabel || input.title);
-    return { category: explicitCategory, slug };
+    return {
+        category: explicitCategory,
+        slug,
+        label: preferredLabel,
+        isIndexDoc: slug === 'index' && explicitCategory === null,
+    };
 }
 export function extractSummary(markdown) {
     const match = String(markdown || '').match(/## Summary\s+([\s\S]*?)(?:\n## |$)/);

package/dist/src/onboard.js

@@ -17,6 +17,9 @@ export async function onboardBranch({ home, input, branch, }) {
     await mkdir(branchDocsDir(home, targetBranch), { recursive: true });
     const written = [];
     for (const doc of input.docs) {
+        const inferred = inferDocPlacement(doc);
+        if (inferred.isIndexDoc)
+            continue;
         const fullPath = join(branchDocsDir(home, targetBranch), docRelativePath(doc));
         await mkdir(dirname(fullPath), { recursive: true });
         await writeFile(fullPath, renderDocMarkdown(doc), 'utf8');

package/dist/src/onboarding-protocol.js

@@ -41,6 +41,7 @@ export function onboardingCompletionLines() {
     return [
         '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"`.',
+        'If verification returns anything other than `status: "complete"`, 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.',
         '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.',
@@ -49,6 +50,7 @@ export function onboardingCompletionLines() {
         'After docs are confirmed correct, do not ask the user to recall repo-scope mappings from scratch; propose the concrete repository candidates that appear materially tied to this gc-branch, then ask the user to choose only one structured confirmation: 1. Map these candidates. 2. Map these, but with corrections. 3. Skip repo mapping for now.',
         'If the user picks 2 for repo mapping, ask only for the repo delta to add or remove. If the user picks 1 or gives corrected candidates, navigate to each confirmed repository and run `gctree set-repo-scope --branch <current-gc-branch> --include`. Skip mapping only if the user picks 3 or explicitly says mapping is not needed.',
         'Do not finish onboarding while material related repos, workflows, or domain terms remain uninspected when recoverable local evidence is still available.',
-        'Only after the related repos, workflows, glossary, default verification commands, and repo-scope mapping are either captured or explicitly skipped should you wrap up, then remind the user that future changes belong in `gctree update-global-context`.',
+        'Only after the related repos, workflows, glossary, default verification commands, repo-scope mapping, and verification gate are all complete should you wrap up.',
+        'When you do wrap up, explicitly tell the user three things in plain language: onboarding is finished; future durable changes can be made with `gctree update-global-context`, or directly through the provider command surface as Codex `$gc-update-global-context {prompt}` and Claude Code `/gc-update-global-context {prompt}`; and they can close this session and start fresh in a new one.',
     ];
 }

package/dist/src/store.js

@@ -109,18 +109,19 @@ export async function writeIndexFromDocs(home, branch) {
     const docsDir = branchDocsDir(home, branch);
     await mkdir(docsDir, { recursive: true });
     const files = await listDocRelativePaths(docsDir);
-    const docs = await Promise.all(files.map(async (file) => {
+    const docs = await Promise.all(files.filter((file) => !/(^|\/)index\.md$/i.test(file)).map(async (file) => {
         const raw = await readFile(join(docsDir, file), 'utf8');
         const title = raw.match(/^#\s+(.+)$/m)?.[1]?.trim() || file.replace(/\.md$/i, '').replace(/-/g, ' ');
         const parts = file.replace(/\.md$/i, '').split('/').filter(Boolean);
         const fallbackCategory = parts.length > 1 ? parts[0] : 'general';
         const fallbackLabel = parts.length > 1 ? parts[parts.length - 1] : title;
-        const inferred = inferDocPlacement({ title, indexLabel: title });
+        const inferred = inferDocPlacement({ title });
         const docCategory = inferred.category || fallbackCategory;
+        const docLabel = inferred.label || fallbackLabel;
         const indexEntries = extractIndexEntries(raw)
-            .map((entry) => normalizeIndexEntry(entry, { category: docCategory, label: fallbackLabel }))
+            .map((entry) => normalizeIndexEntry(entry, { category: docCategory, label: docLabel }))
             .filter((entry) => Boolean(entry));
-        const entryLabels = indexEntries.length > 0 ? indexEntries : [{ category: docCategory, label: fallbackLabel }];
+        const entryLabels = indexEntries.length > 0 ? indexEntries : [{ category: docCategory, label: docLabel }];
         const uniqueEntries = [...new Map(entryLabels.map((entry) => [`${entry.category}::${entry.label}`, entry])).values()];
         return uniqueEntries.map((entry) => ({
             title,

package/package.json

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

package/skills/onboard/SKILL.md

@@ -81,19 +81,21 @@ Use this when a user wants to create global context for a product, company, or w
 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"`.
-29. After the onboarding docs are written, explicitly list which durable docs were saved.
-30. Summarize what you now understand from the saved docs instead of ending at the filenames alone.
-31. For that final summary, do not ask an open-ended validation question first. Present the summary and ask the user to choose only one:
+29. If verification returns anything other than `status: "complete"`, 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.
+30. After the onboarding docs are written, explicitly list which durable docs were saved.
+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.
    - 2. Some parts are wrong. I will give the delta.
    - 3. The frame is wrong. I will restate it.
-32. 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.
-33. Ask whether anything else should be saved while the context is still fresh.
-34. After docs are confirmed correct, do not ask the user to recall repo-scope mappings from scratch. Propose the concrete repository candidates that appear materially tied to this gc-branch, then ask the user to choose only one:
+33. 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.
+34. Ask whether anything else should be saved while the context is still fresh.
+35. After docs are confirmed correct, do not ask the user to recall repo-scope mappings from scratch. Propose the concrete repository candidates that appear materially tied to this gc-branch, then ask the user to choose only one:
    - 1. Map these candidates.
    - 2. Map these, but with corrections.
    - 3. Skip repo mapping for now.
-35. If the user picks 2 for repo mapping, ask only for the repo delta to add or remove. If the user picks 1 or gives corrected candidates, navigate to each confirmed repo and run `gctree set-repo-scope --branch <gc-branch> --include`. Skip mapping only if the user picks 3 or explicitly says mapping is not needed.
-36. Do not finish onboarding while material related repos, workflows, or domain terms remain uninspected when recoverable local evidence is still available.
-37. Only after the related repos, workflows, glossary, default verification commands, and repo-scope mapping are either captured or explicitly skipped should you wrap up, then remind the user that future changes belong in `gctree update-global-context`.
-38. Keep the current gc-branch explicit while gathering context.
+36. If the user picks 2 for repo mapping, ask only for the repo delta to add or remove. If the user picks 1 or gives corrected candidates, navigate to each confirmed repo and run `gctree set-repo-scope --branch <gc-branch> --include`. Skip mapping only if the user picks 3 or explicitly says mapping is not needed.
+37. Do not finish onboarding while material related repos, workflows, or domain terms remain uninspected when recoverable local evidence is still available.
+38. Only after the related repos, workflows, glossary, default verification commands, repo-scope mapping, and verification gate are all complete should you wrap up.
+39. When you wrap up, explicitly tell the user three things in plain language: onboarding is finished; future durable changes can be made with `gctree update-global-context`, or directly through the provider command surface as Codex `$gc-update-global-context {prompt}` and Claude Code `/gc-update-global-context {prompt}`; and they can close this session and start fresh in a new one.
+40. Keep the current gc-branch explicit while gathering context.