@handsupmin/gc-tree 0.4.0 → 0.4.2

package/dist/src/cli.js

@@ -11,6 +11,7 @@ import { scaffoldHostIntegration } from './scaffold.js';
 import { requirePreferredProvider, writeSettings, readSettings } from './settings.js';
 import { checkoutBranch, initHome, listBranches, readHead, resetBranchContext, statusForBranch, ensureBranchExists, isBranchContextEmpty } from './store.js';
 import { updateBranchContext } from './update.js';
+import { verifyOnboarding } from './verify-onboarding.js';
 function readArg(flag) {
     const index = process.argv.indexOf(flag);
     return index === -1 ? undefined : process.argv[index + 1];
@@ -28,6 +29,7 @@ function usage() {
   gctree set-repo-scope --branch NAME [--repo NAME] [--cwd DIR] (--include|--exclude) [--home DIR]
   gctree status [--home DIR] [--cwd DIR]
   gctree onboard [--home DIR] [--branch NAME] [--provider <codex|claude-code>] [--target DIR] [--no-launch]
+  gctree verify-onboarding [--home DIR] [--branch NAME]
   gctree reset-gc-branch [--home DIR] [--branch NAME] --yes
   gctree resolve --query TEXT [--home DIR] [--branch NAME] [--cwd DIR]
   gctree show-doc --id ID [--home DIR] [--branch NAME]
@@ -246,6 +248,12 @@ async function main() {
             console.log(JSON.stringify({ mode: 'guided_onboarding', gc_branch: gcBranch, preferred_provider: provider, scaffold, launch }, null, 2));
             return;
         }
+        case 'verify-onboarding': {
+            const gcBranch = readArg('--branch') || (await readHead(home)) || DEFAULT_BRANCH;
+            const result = await verifyOnboarding({ home, branch: gcBranch });
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
         case '__apply-onboarding': {
             const inputPath = readArg('--input');
             if (!inputPath)

package/dist/src/onboarding-protocol.js

@@ -7,20 +7,19 @@ export function onboardingProtocolLines() {
         'Do **not** start with a repo scan, a company guess, or a broad hypothesis built from directories like `~/sources`.',
         'Do **not** ask for a full information dump up front.',
         'If docs, reference material, or reference paths are provided, read those first, summarize your understanding back, ask whether that summary is correct before continuing, and skip any questions the docs already answered well.',
-        'If no docs are available, continue from the user\'s own description first and ask for the most relevant repo, path, or file only when needed.',
-        'Only inspect docs, repos, directories, or files after the user has pointed you at them or confirmed they matter.',
-        'When you inspect, dig only through the user-provided material and the minimum related files needed for the next question.',
+        'If no docs are available, continue from the user\'s own description first, then after the user\'s first answer, proactively inspect related repos, docs, paths, and workflows that appear materially connected.',
+        'Use bounded local inspection to confirm or challenge the user\'s description instead of waiting for the user to enumerate every related repo manually.',
         'Do **not** scan broad directories or inspect every source file; prefer docs, READMEs, summaries, and a few pointed paths first.',
         'Then ask whether anything important is still missing or worth adding before you continue into deeper discovery.',
-        'When you do present a hypothesis, offer structured numbered confirmations such as: 1. This is basically correct. 2. Part of it is wrong. I will explain what differs. 3. This is the wrong frame. I will explain what you should inspect or how this gc-branch should be approached.',
-        'If the user picks 2 or 3, ask only for the delta, correction, or better pointer instead of restarting from scratch.',
+        'When you do present a hypothesis, offer only these structured numbered confirmations: 1. This is mostly correct. 2. Some parts are wrong. Please explain what differs. 3. Most of this is wrong. Please explain the right frame.',
+        'If the user picks 2 or 3, ask only for the delta, correction, or right frame instead of restarting from scratch.',
         'Do **not** start by asking what one repository does.',
         'Only ask the user who they are, what kind of person they are in the organization, and what work they usually own or lead after the provided docs or description still leave real gaps.',
         'Ask next for one core recurring work type only when the provided docs or description still do not make the work types clear, then ask whether there are more work types to capture.',
         'For each work type, ask how that work shows up day to day.',
         'Only after the work types are clear should you ask which repositories are involved in each work type.',
         'For each repository, ask what role it plays in the work, what directories or files matter most, what the actual workflow is, and what hidden conventions, glossary terms, or boundaries matter.',
-        'If a relevant repo, path, or doc is available locally and the user has pointed you to it, inspect it and present a lightweight hypothesis before asking what is correct or wrong about that frame.',
+        'After the user\'s first answer, proactively inspect relevant local repos, docs, paths, and workflows whenever the connection is strong enough to test your current frame.',
         'Ask whether there are additional repositories for the current work type before moving on.',
         'After repository coverage, ask for company/domain glossary terms and acronyms that should become durable context.',
         'Then ask which verification commands should be treated as defaults for this kind of work.',
@@ -29,10 +28,13 @@ 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"`.',
         '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.',
         'Ask whether that final summary matches the user\'s reality, and capture any corrections before you wrap up.',
         'Ask whether anything else should be saved while the context is still fresh.',
-        'End with remaining risks, blind spots, or details that still need confirmation, then remind the user that future changes belong in `gctree update-global-context`.',
+        '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, and default verification commands are either captured or explicitly unavailable should you wrap up, then remind the user that future changes belong in `gctree update-global-context`.',
     ];
 }

package/dist/src/verify-onboarding.js

@@ -0,0 +1,24 @@
+import { readFile } from 'node:fs/promises';
+import { parseIndexEntries } from './markdown.js';
+import { branchIndexPath, DEFAULT_BRANCH } from './paths.js';
+import { ensureBranchExists, statusForBranch } from './store.js';
+export async function verifyOnboarding({ home, branch, }) {
+    const gcBranch = branch || DEFAULT_BRANCH;
+    await ensureBranchExists(home, gcBranch);
+    const status = await statusForBranch(home, gcBranch);
+    const indexRaw = await readFile(branchIndexPath(home, gcBranch), 'utf8');
+    const docs = parseIndexEntries(indexRaw);
+    const indexedDocCount = docs.length;
+    const complete = status.doc_count > 0 && indexedDocCount > 0;
+    return {
+        status: complete ? 'complete' : 'incomplete',
+        gc_branch: gcBranch,
+        doc_count: status.doc_count,
+        indexed_doc_count: indexedDocCount,
+        docs,
+        warnings: status.warnings,
+        message: complete
+            ? `Onboarding is complete for gc-branch "${gcBranch}".`
+            : `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.4.0",
+  "version": "0.4.2",
   "description": "Global Context Tree, a lightweight branch-aware global context orchestrator for AI coding tools",
   "type": "module",
   "private": false,

package/skills/onboard/SKILL.md

@@ -17,16 +17,15 @@ Use this when a user wants to create global context for a product, company, or w
 - do not ask for a full information dump up front
 - if docs, reference material, or reference paths are provided, read them first and summarize your understanding back before asking for more
 - ask whether that summary is correct before continuing, let the user correct it, and skip questions the docs already answered well
-- if no docs are available, continue from the user's own description first and ask for the most relevant repo, path, or file only when needed
-- only inspect docs, repos, directories, or files after the user has pointed you at them or confirmed they matter
-- dig only through the user-provided material and the minimum related files needed for the next question
+- if no docs are available, continue from the user's own description first, then after the user's first answer, proactively inspect related repos, docs, paths, and workflows that appear materially connected
+- use bounded local inspection to confirm or challenge the user's description instead of waiting for them to enumerate every related repo manually
 - do not inspect every source file; prefer docs, READMEs, summaries, and a few pointed paths first
 - when you do present a hypothesis, keep it lightweight and only after the user has narrowed the scope
-- use structured numbered confirmations like:
-  1. This is basically correct.
-  2. Part of it is wrong. I will explain what differs.
-  3. This is the wrong frame. I will explain what you should inspect or how this gc-branch should be approached.
-- if the user picks 2 or 3, ask only for the delta or better pointer instead of restarting from scratch
+- offer only these structured numbered confirmations:
+  1. This is mostly correct.
+  2. Some parts are wrong. Please explain what differs.
+  3. Most of this is wrong. Please explain the right frame.
+- if the user picks 2 or 3, ask only for the delta or right frame instead of restarting from scratch
 - ask whether anything important is still missing before continuing deeper
 - do not start by asking what one repo does
 - ask who the person is and what work they usually own only after the provided docs or description still leave real gaps
@@ -42,15 +41,14 @@ Use this when a user wants to create global context for a product, company, or w
 3. Wait for the user's first answer. Start by asking them to paste or share organized docs or reference material if they have any; otherwise ask what kind of work they mainly do.
 4. Do not scan broad directories like `~/sources`, guess the company/product from unrelated repos, or inspect every source file before the user narrows the scope.
 5. If docs, reference material, or reference paths are provided, read those first, summarize your understanding back, ask whether that summary is correct, and ask whether anything important is still missing before moving on.
-6. If no docs are available, continue from the user's own description first and ask for the most relevant repo, path, or file only when needed.
-7. Only inspect docs, repos, directories, or files after the user has pointed you at them or confirmed they matter.
-8. When you inspect, dig only through the user-provided material and the minimum related files needed for the next question. Prefer docs, READMEs, summaries, and a few pointed paths first.
-9. Once the scope is narrow enough, present a lightweight hypothesis from the evidence you inspected, then ask the user to choose one:
-   1. This is basically correct.
-   2. Part of it is wrong. I will explain what differs.
-   3. This is the wrong frame. I will explain what you should inspect or how this gc-branch should be approached.
-10. If the user picks 2 or 3, ask only for the delta or the next best pointer to inspect instead of requesting a full rewrite of the context.
-11. When the inspected evidence already covers the basics well, confirm that and skip ahead to the missing parts instead of re-asking everything from scratch.
+6. If no docs are available, continue from the user's own description first, then after the user's first answer, proactively inspect related repos, docs, paths, and workflows that appear materially connected.
+7. Use bounded local inspection to confirm or challenge the user's description instead of waiting for them to enumerate every relevant repo manually. Prefer docs, READMEs, summaries, and a few pointed paths first.
+8. Once the scope is narrow enough, present a lightweight hypothesis from the evidence you inspected, then ask the user to choose one:
+   1. This is mostly correct.
+   2. Some parts are wrong. Please explain what differs.
+   3. Most of this is wrong. Please explain the right frame.
+9. If the user picks 2 or 3, ask only for the delta or right frame instead of requesting a full rewrite of the context, then continue inspecting.
+10. When the inspected evidence already covers the basics well, confirm that and skip ahead to the missing parts instead of re-asking everything from scratch.
 12. Start from the person only when the provided docs or description still do not make that clear:
    - who they are
    - what kind of work they usually own or lead
@@ -62,13 +60,16 @@ Use this when a user wants to create global context for a product, company, or w
    - which paths matter most
    - what the actual workflow is
    - what hidden conventions, glossary terms, boundaries, or constraints matter
-17. If a relevant repo, path, or doc is available locally and the user has pointed you to it, inspect it and show a lightweight hypothesis so the user can correct your frame.
+17. After the user's first answer, proactively inspect relevant local repos, docs, paths, and workflows whenever the connection is strong enough to test your current frame.
 18. Ask for company/domain glossary terms and acronyms that should become durable context.
 19. Ask which verification commands should be treated as defaults for this gc-branch.
 20. Launch the guided onboarding flow with `gctree onboard [--branch <name>]`.
-21. After the onboarding docs are written, explicitly list which durable docs were saved.
-22. Summarize what you now understand from the saved docs instead of ending at the filenames alone.
-23. Ask whether that final summary matches the user's reality, and capture any corrections before you wrap up.
-24. Ask whether anything else should be saved while the context is still fresh.
-25. End with remaining risks, blind spots, or details that still need confirmation, and remind the user that future changes belong in `gctree update-global-context`.
-26. Keep the current gc-branch explicit while gathering context.
+21. Before you claim onboarding is complete, run `gctree verify-onboarding --branch <current-gc-branch>` and inspect the real gc-tree files.
+22. Do not claim onboarding is complete unless verification returns `status: "complete"`.
+23. After the onboarding docs are written, explicitly list which durable docs were saved.
+24. Summarize what you now understand from the saved docs instead of ending at the filenames alone.
+25. Ask whether that final summary matches the user's reality, and capture any corrections before you wrap up.
+26. Ask whether anything else should be saved while the context is still fresh.
+27. Do not finish onboarding while material related repos, workflows, or domain terms remain uninspected when recoverable local evidence is still available.
+28. Only after the related repos, workflows, glossary, and default verification commands are either captured or explicitly unavailable should you wrap up, then remind the user that future changes belong in `gctree update-global-context`.
+29. Keep the current gc-branch explicit while gathering context.