@handsupmin/gc-tree 0.7.3 → 0.7.4

package/dist/src/onboarding-protocol.js

@@ -40,8 +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"`.',
-        '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.',
+        '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.',

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.3",
+  "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,8 +81,8 @@ 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. 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.
+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: