@handsupmin/gc-tree 0.7.2 → 0.7.4

package/dist/src/onboarding-protocol.js

@@ -40,7 +40,9 @@ export function onboardingProtocolLines() {
 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"`.',
+        '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.',
+        '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.',
         '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 +51,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/verify-onboarding.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { parseIndexEntries } from './markdown.js';
 import { 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, }) {
     const gcBranch = branch || DEFAULT_BRANCH;
     await ensureBranchExists(home, gcBranch);
@@ -9,7 +10,23 @@ export async function verifyOnboarding({ home, branch, }) {
     const indexRaw = await readFile(branchIndexPath(home, gcBranch), 'utf8');
     const docs = parseIndexEntries(indexRaw);
     const indexedDocCount = docs.length;
-    const complete = status.doc_count > 0 && indexedDocCount > 0;
+    const hasDocs = status.doc_count > 0 && indexedDocCount > 0;
+    const qualityIssues = [];
+    if (hasDocs && indexedDocCount >= 3) {
+        const categoryCounts = new Map();
+        for (const doc of docs) {
+            categoryCounts.set(doc.category, (categoryCounts.get(doc.category) ?? 0) + 1);
+        }
+        const generalCount = categoryCounts.get('general') ?? 0;
+        if (generalCount === indexedDocCount) {
+            qualityIssues.push(`All ${indexedDocCount} docs have category "general". Valid categories are: ${[...VALID_CATEGORIES].join(', ')}. Re-apply onboarding with correct category fields in the JSON.`);
+        }
+        else if (generalCount > 0) {
+            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(', ')}.`);
+        }
+    }
+    const complete = hasDocs && qualityIssues.length === 0;
     return {
         status: complete ? 'complete' : 'incomplete',
         gc_branch: gcBranch,
@@ -17,8 +34,11 @@ export async function verifyOnboarding({ home, branch, }) {
         indexed_doc_count: indexedDocCount,
         docs,
         warnings: status.warnings,
+        quality_issues: qualityIssues,
         message: complete
             ? `Onboarding is complete for gc-branch "${gcBranch}".`
-            : `Onboarding is incomplete for gc-branch "${gcBranch}". Docs or index entries are missing.`,
+            : hasDocs
+                ? `Onboarding has quality issues for gc-branch "${gcBranch}". Fix quality_issues before finishing.`
+                : `Onboarding is incomplete for gc-branch "${gcBranch}". Docs or index entries are missing.`,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handsupmin/gc-tree",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "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,6 +43,7 @@ Use this when a user wants to create global context for a product, company, or w
 - 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
+- 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
 
 ## Procedure
@@ -80,20 +81,22 @@ Use this when a user wants to create global context for a product, company, or w
 25. Render `index.md` as a category-grouped dictionary-style table of contents with `label -> path` entries.
 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:
+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.
+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.