toga-ai 1.0.45 → 1.0.47

package/knowledge.js

@@ -14,10 +14,13 @@
  *   node /path/to/claude/knowledge.js <command> [--flags]
  *
  * Commands:
- *   search   --framework= --repo= --project= --client= --file= --q=
+ *   search            --framework= --repo= --project= --client= --file= --q=
  *   index
- *   deps     --repo=<repo>
+ *   deps              --repo=<repo>
  *   validate
+ *   manifest
+ *   kickoff-preflight --repos=a,b,c --client=<slug> --layer=<...> --q=<...>
+ *   publish           --msg= --mirror= --branch=
  */
 
 'use strict';
@@ -170,6 +173,193 @@ function cmdManifest() {
     console.log(JSON.stringify({ repos, clients }));
 }
 
+/* ------------------------------------------------------------------ */
+/* command: kickoff-preflight — one JSON bundle for kickoff Steps 3+4.  */
+/* Given the chosen repos (+client, +layer), resolves the dependency    */
+/* load-set, every doc to read (with exists flags), and an ordered      */
+/* `reads` list — so kickoff stops running deps/search/path-probing in  */
+/* context. Prints minified JSON. Flags:                                */
+/*   --repos=a,b,c   (required)  --client=<slug>  --layer=<back-end|     */
+/*   front-end|hybrid>  --q=<keywords to match feature docs>            */
+/* ------------------------------------------------------------------ */
+
+function cmdPreflight(args) {
+    const registry = loadRegistry();
+    const chosen = String(args.repos || '').split(',').map(s => s.trim()).filter(Boolean);
+    if (!chosen.length) {
+        console.log(JSON.stringify({ error: 'PREFLIGHT: --repos=<repo,repo> required' }));
+        process.exitCode = 1;
+        return;
+    }
+    const layer = String(args.layer || 'hybrid').toLowerCase();
+    const q = args.q ? String(args.q).toLowerCase() : null;
+    const unknown = chosen.filter(r => !registry.find(x => x.repo === r));
+
+    // frameworks involved (from the chosen repos)
+    const fwSet = new Set();
+    for (const r of chosen) { const e = registry.find(x => x.repo === r); if (e) fwSet.add(e.framework); }
+    const frameworks = [...fwSet];
+
+    // dependency load-set: framework core(s) first, then transitive dependsOn, then chosen
+    const seen = new Set();
+    const loadSet = [];
+    const visit = (r) => {
+        const e = registry.find(x => x.repo === r);
+        if (!e) return;
+        for (const d of (e.dependsOn || [])) visit(d);
+        if (!seen.has(r)) { seen.add(r); loadSet.push(r); }
+    };
+    for (const fw of frameworks) for (const core of coreReposFor(registry, fw)) visit(core);
+    for (const r of chosen) visit(r);
+
+    const docs = allDocs();
+    const chosenSet = new Set(chosen);
+    const fileInfo = (rel) => ({ path: rel, exists: fs.existsSync(path.join(ROOT, rel.split('/').join(path.sep))) });
+    const matchQ = (d) => !q || (((d.data.title || '') + ' ' + (d.data.files || []).join(' ') + ' ' + d.body).toLowerCase().includes(q));
+
+    // per-repo inventory; feature docs only for explicitly chosen repos
+    const repoOut = loadSet.map(repo => {
+        const e = registry.find(x => x.repo === repo);
+        const fw = e ? e.framework : '';
+        const repoDir = path.join(ROOT, fw, 'apps', repo);
+        const isChosen = chosenSet.has(repo);
+        let features = [];
+        if (isChosen) {
+            features = docs
+                .filter(d => d.file.startsWith(repoDir + path.sep) && d.data.type !== 'architecture' && matchQ(d))
+                .map(d => ({ path: d.rel, title: d.data.title || '', files: (d.data.files || []).join(', ') }));
+        }
+        return {
+            repo, framework: fw, project: e ? e.project : '', role: e ? e.role : '', chosen: isChosen,
+            architecture: fileInfo(`${fw}/apps/${repo}/architecture.md`),
+            features,
+        };
+    });
+
+    // standards per involved framework, filtered by layer
+    const wantBackend = layer === 'back-end' || layer === 'backend' || layer === 'hybrid';
+    const wantFrontend = layer === 'front-end' || layer === 'frontend' || layer === 'hybrid';
+    const standards = [];
+    for (const fw of frameworks) {
+        if (wantBackend) standards.push({ ...fileInfo(`${fw}/standards/backend-php.md`), framework: fw });
+        if (wantFrontend) standards.push({ ...fileInfo(`${fw}/standards/frontend.md`), framework: fw });
+    }
+
+    // client docs (profile + features/workflows filtered to involved frameworks)
+    let client = null;
+    const slug = args.client && args.client !== 'shared' && args.client !== true ? String(args.client) : null;
+    if (slug) {
+        const clientDir = path.join(ROOT, 'clients', slug);
+        const cDocs = docs.filter(d => d.file.startsWith(clientDir + path.sep));
+        const profileDoc = cDocs.find(d => path.basename(d.file) === 'profile.md');
+        const cFeatures = cDocs
+            .filter(d => path.basename(d.file) !== 'profile.md')
+            .filter(d => !frameworks.length || !d.data.framework || frameworks.includes(d.data.framework))
+            .filter(matchQ)
+            .map(d => ({ path: d.rel, title: d.data.title || '', framework: d.data.framework || '', type: d.data.type || '' }));
+        client = {
+            slug,
+            title: (profileDoc && profileDoc.data.title) || slug,
+            profile: fileInfo(`clients/${slug}/profile.md`),
+            docs: cFeatures,
+        };
+    }
+
+    // ordered read list — mirrors kickoff Step 4: core arch → repo arch+features → standards → client
+    const reads = [];
+    for (const r of repoOut.filter(r => r.role === 'core')) {
+        reads.push({ label: 'core-architecture', repo: r.repo, ...r.architecture });
+        for (const f of r.features) reads.push({ label: 'feature', repo: r.repo, path: f.path, exists: true, title: f.title });
+    }
+    for (const r of repoOut.filter(r => r.role !== 'core')) {
+        reads.push({ label: r.chosen ? 'repo-architecture' : 'dep-architecture', repo: r.repo, ...r.architecture });
+        for (const f of r.features) reads.push({ label: 'feature', repo: r.repo, path: f.path, exists: true, title: f.title });
+    }
+    for (const s of standards) reads.push({ label: 'standard', path: s.path, exists: s.exists });
+    if (client) {
+        reads.push({ label: 'client-profile', path: client.profile.path, exists: client.profile.exists });
+        for (const d of client.docs) reads.push({ label: 'client-doc', path: d.path, exists: true, title: d.title });
+    }
+
+    console.log(JSON.stringify({ frameworks, loadSet, unknown, repos: repoOut, standards, client, reads }));
+}
+
+/* ------------------------------------------------------------------ */
+/* command: publish — capture's deterministic finish (validate, index, */
+/* optional mirror, commit knowledge/, rebase-before-push with retry). */
+/* Replaces ~80 lines of skill prose + 6 model-orchestrated git calls.  */
+/* Flags: --msg=<commit msg> --mirror=<project .claude dir> --branch=   */
+/* Prints one PUBLISH: <STATUS> line the skill can branch on.           */
+/* ------------------------------------------------------------------ */
+
+function copyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const e of fs.readdirSync(src, { withFileTypes: true })) {
+        const s = path.join(src, e.name), d = path.join(dest, e.name);
+        if (e.isDirectory()) copyDir(s, d);
+        else fs.copyFileSync(s, d);
+    }
+}
+
+function cmdPublish(args) {
+    const cp = require('child_process');
+    const TEAM = __dirname;
+    const node = process.argv[0];
+    const self = __filename;
+    const branch = args.branch || '_main';
+    const run = (cmd) => cp.execSync(cmd, { cwd: TEAM, encoding: 'utf8', stdio: 'pipe' });
+
+    // 0. must be a git clone
+    try { run('git rev-parse --git-dir'); }
+    catch { console.log('PUBLISH: NOT_GIT — knowledge written locally only; run `npx toga-ai` to create a pushable clone'); return; }
+
+    // 1. validate (inherit output so any ERROR: lines are visible); abort on failure
+    try { cp.execSync(`"${node}" "${self}" validate`, { cwd: TEAM, stdio: 'inherit' }); }
+    catch { console.log('PUBLISH: VALIDATE_FAILED — fix the errors above; nothing pushed'); process.exitCode = 1; return; }
+
+    // 2. rebuild indexes
+    cp.execSync(`"${node}" "${self}" index`, { cwd: TEAM, stdio: 'inherit' });
+
+    // 3. optional mirror back to the project bundle (keeps local reads fresh)
+    if (args.mirror && typeof args.mirror === 'string') {
+        const dest = path.join(args.mirror, 'knowledge');
+        if (path.resolve(dest) !== path.resolve(ROOT)) { copyDir(ROOT, dest); console.log('PUBLISH: mirrored knowledge/ -> ' + dest); }
+    }
+
+    // 4. stage knowledge/ ONLY; bail if anything else slipped in
+    run('git add knowledge/');
+    const staged = run('git diff --cached --name-only').split('\n').map(s => s.trim()).filter(Boolean);
+    if (staged.length === 0) { console.log('PUBLISH: NO_CHANGES — nothing new to push'); return; }
+    const outside = staged.filter(f => !f.startsWith('knowledge/'));
+    if (outside.length) { run('git reset -q'); console.log('PUBLISH: ABORT_OUTSIDE_KNOWLEDGE — refusing to commit non-knowledge files: ' + outside.join(', ')); process.exitCode = 1; return; }
+
+    // 5. commit
+    const msg = String(args.msg || 'knowledge: capture session updates').replace(/["\\]/g, "'").slice(0, 200);
+    run(`git commit -m "${msg}"`);
+
+    // 6. rebase-before-push, retrying the CI version-bump race up to 3x
+    for (let attempt = 1; attempt <= 3; attempt++) {
+        try {
+            run('git fetch origin');
+            run(`git rebase origin/${branch}`);
+            run(`git push origin HEAD:${branch}`);
+            console.log(`PUBLISH: PUSHED to ${branch} — CI publishes a new npm version; teammates get it on \`npx toga-ai\``);
+            return;
+        } catch (e) {
+            let status = '';
+            try { status = run('git status --porcelain'); } catch { /* ignore */ }
+            if (/^(UU|AA|DD|AU|UA|DU|UD) /m.test(status)) {
+                try { run('git rebase --abort'); } catch { /* ignore */ }
+                console.log(`PUBLISH: CONFLICT — rebase onto origin/${branch} hit a real conflict; resolve manually, then re-run publish`);
+                process.exitCode = 1; return;
+            }
+            // else: almost certainly a fresh CI bump (non-fast-forward) — loop and retry
+        }
+    }
+    console.log(`PUBLISH: PUSH_FAILED after 3 attempts — run manually: git -C "${TEAM}" push origin HEAD:${branch}`);
+    process.exitCode = 1;
+}
+
 /* ------------------------------------------------------------------ */
 /* command: deps                                                       */
 /* ------------------------------------------------------------------ */
@@ -405,8 +595,10 @@ function main() {
         case 'deps': return cmdDeps(args);
         case 'validate': return cmdValidate();
         case 'manifest': return cmdManifest();
+        case 'kickoff-preflight': return cmdPreflight(args);
+        case 'publish': return cmdPublish(args);
         default:
-            console.log('Usage: node knowledge.js <search|index|deps|validate|manifest> [--flags]');
+            console.log('Usage: node knowledge.js <search|index|deps|validate|manifest|kickoff-preflight|publish> [--flags]');
             process.exitCode = 1;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.45",
+  "version": "1.0.47",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",

package/skills/capture/SKILL.md

@@ -53,8 +53,8 @@ done
 **`~/toga-tech` must be probed first** — `npx toga-ai` runs `initLocalRepo` there, which
 creates a proper git repo seeded from the bundle even when the remote is private.
 
-**If `IS_GIT_CLONE` is false** (only `.claude/` bundle found): warn immediately and skip
-Steps 5–7 for git operations:
+**If `IS_GIT_CLONE` is false** (only `.claude/` bundle found): you can still write docs
+locally (Step 5), but the Step 6 publish will report `NOT_GIT` instead of pushing. Warn:
 > "⚠ No git clone found at standard paths. Docs will be written locally only.
 > Run `npx toga-ai` first (it creates `~/toga-tech` as a pushable git repo),
 > then re-run /capture to push to GitHub."
@@ -143,94 +143,34 @@ For a client `profile.md`, the `title:` **is** the client's formal name (e.g. "C
 there is no separate name field; `validate` requires `title`. See New-client onboarding.
 Add `related:` cross-links. Append new repos to `<TEAM_REPO>/knowledge/registry.json`.
 
-## Step 6 — Validate, index, mirror back (mandatory)
+## Step 6 — Publish (validate → index → mirror → rebase-push, one command)
 
-```bash
-node "<TEAM_REPO>/knowledge.js" validate
-node "<TEAM_REPO>/knowledge.js" index
-```
-
-If `validate` reports any ERROR — stop and fix before continuing.
-
-After both pass, **mirror back** to keep the project's local reads fresh:
-```bash
-# Only when TEAM_REPO != <project>/.claude
-cp -r "<TEAM_REPO>/knowledge/" "<project>/.claude/knowledge/"
-```
-Skip mirror-back if the paths are the same directory.
-
-## Step 7 — Push (only when IS_GIT_CLONE is true)
-
-**This push is pre-authorized and mandatory — never ask the developer to confirm it.**
-Running `/capture` IS the authorization to publish. After validate + index pass and the
-staged set is confined to `knowledge/`, commit and push automatically as the final step of
-every capture. Do not pause, do not present a "ready to push?" prompt, do not offer to "leave
-it staged locally." The only reasons to stop are the guardrails already listed below: nothing
-new to push (Check B empty), files staged outside `knowledge/`, or a push that errors.
-
-If `IS_GIT_CLONE` is false — skip this step entirely and show:
-> "⚠ Docs written to `.claude/knowledge/` only (no git clone). Run `npx toga-ai`
-> to create `~/toga-tech`, then re-run /capture to push."
-
-Otherwise:
-
-**Check A — origin URL correct?**
-```bash
-git -C "<TEAM_REPO>" remote get-url origin
-```
-If wrong or missing: `git -C "<TEAM_REPO>" remote set-url origin https://github.com/agilantsolutions/claude`
-
-**Check B — anything new to push?**
-```bash
-git -C "<TEAM_REPO>" status --short knowledge/
-```
-If empty — report "No new knowledge to push" and exit cleanly.
-
-**Commit:**
-```bash
-git -C "<TEAM_REPO>" add knowledge/
-git -C "<TEAM_REPO>" diff --cached --quiet || \
-  git -C "<TEAM_REPO>" commit -m "knowledge: <one-line summary>"
-```
-
-Never stage files outside `knowledge/`. If `git diff --cached` includes anything outside
-`knowledge/`, abort and warn before committing.
-
-**Sync, then push (rebase BEFORE pushing — this prevents the version-bump conflict):**
-
-Every push to this branch triggers a CI job that commits a `chore: bump version [skip ci]`
-back to the branch. So after *any* prior push (e.g. an earlier capture in the same session),
-your local branch is one commit behind the remote, and a naive push is rejected as a
-non-fast-forward. Rebase your fresh commit onto the remote **before** pushing — this pulls in
-commits that already exist (no waiting on CI), so the push fast-forwards cleanly:
+Finish every capture with the deterministic publisher — **do not** run validate/index/git
+by hand. The push is **pre-authorized and mandatory**: running `/capture` IS the
+authorization, so never ask "ready to push?".
 
 ```bash
-git -C "<TEAM_REPO>" fetch origin
-git -C "<TEAM_REPO>" rebase origin/_main
-git -C "<TEAM_REPO>" push origin HEAD:_main
+node "<TEAM_REPO>/knowledge.js" publish --msg="knowledge: <one-line summary>" --mirror="<project>/.claude"
 ```
 
-> **Do NOT "pull after push" instead** — the bump commit for *this* push is created
-> asynchronously by CI a few seconds later, so pulling immediately afterward races CI and
-> usually grabs nothing. Rebasing *before* the push is what reliably avoids the conflict,
-> with zero dependency on npm build/publish timing.
-
-**If the push is still rejected** (a bump commit landed in the brief window between your
-rebase and push), simply repeat `fetch` → `rebase` → `push`, up to 2 more times. This is an
-expected occasional race, not an error — do not report it as a failure unless all retries are
-exhausted.
-
-**If push succeeds:**
-> "✓ Pushed to `_main` — CI publishes new npm version. Teammates get it on `npx toga-ai`."
+This validates, rebuilds indexes, mirrors `knowledge/` back to the project bundle, then
+stages **only** `knowledge/`, commits, and rebase-pushes to `_main` (auto-retrying the CI
+version-bump race). Omit `--mirror` if TEAM_REPO already *is* the project bundle. Read the
+final `PUBLISH:` line and act on it:
 
-**If push fails** — show exact git error, then:
-> "⚠ Push failed: `<error>`. Run manually: `git -C <TEAM_REPO> push origin HEAD:_main`"
+- **`PUSHED`** — done. Report: "✓ Pushed to `_main` — teammates get it on `npx toga-ai`."
+- **`NO_CHANGES`** — report "No new knowledge to push" and finish.
+- **`VALIDATE_FAILED`** — fix the printed `ERROR:` lines, then re-run publish. Never push around it.
+- **`CONFLICT`** — a real rebase conflict; resolve manually, then re-run publish.
+- **`ABORT_OUTSIDE_KNOWLEDGE`** — non-`knowledge/` files were staged; investigate before retrying.
+- **`NOT_GIT`** — no git clone; docs are local only. Tell the dev to run `npx toga-ai` first.
+- **`PUSH_FAILED`** — show the printed manual-push command.
 
-## Step 8 — Report
+## Step 7 — Report
 
 List exactly what changed (clickable relative paths), and note any ⚠ ELEVATED docs the
 developer approved so they remember those touched senior-owned standards/architecture.
-If Step 7 pushed successfully, include the push confirmation in the report.
+If Step 6 published successfully (`PUSHED`), include the push confirmation in the report.
 
 ---
 
@@ -396,4 +336,4 @@ Suggest a slug from the work, e.g. `/session-save clickup-deploy-worker`.
 
 `.claude/settings.json` runs `node knowledge.js validate` after every write to `knowledge/`,
 so `ERROR:`/`OK` output appears inline as each doc is written — fix any error before writing
-the next. Step 6's explicit `validate` is still required as the final global-consistency gate.
+the next. Step 6's `publish` re-runs `validate` as the final global-consistency gate before pushing.

package/skills/kickoff/SKILL.md

@@ -128,33 +128,49 @@ and silently truncates a 7-repo / 5-client list. Render the full list as a numbe
 list and have the developer reply with numbers (e.g. "1, 3, 5") — no cap, supports
 multi-select. Framework (q1) and layer (q2) have ≤4 options, so chips are fine there.
 
-## Step 3 — Resolve the repos this work needs (local paths, lazily)
+## Step 3 — Preflight: resolve the load-set and the exact read list (one call)
 
-Compute the load set with `node "<TEAM_REPO>/knowledge.js" deps --repo=<chosen-repo>`
-(returns the framework core + chosen repo + transitive `dependsOn`, in load order). For
-**both** frameworks, run it for each chosen repo and union the results.
+Run **one** command — it does the dependency resolution, feature-doc matching, standards
+selection, and client-doc filtering that used to be several `deps`/`search` calls plus
+in-context path-probing:
 
-For **each** repo in the load set, get its local path so you can navigate the actual code:
+```bash
+node "<TEAM_REPO>/knowledge.js" kickoff-preflight \
+  --repos=<comma-separated chosen repos> \
+  --client=<slug | omit if shared/internal> \
+  --layer=<back-end | front-end | hybrid> \
+  --q=<2-4 keywords from the developer's task sentence>
+```
+
+It prints minified JSON:
+- `loadSet` — framework core(s) + chosen repos + transitive `dependsOn`, in load order.
+- `repos[]` — each with `architecture` `{path,exists}`, `role`, `chosen`, and matched
+  `features[]` (features are returned only for the repos the developer chose, not deps).
+- `standards[]` and `client` `{title, profile, docs[]}` — both `{path,exists}`-flagged.
+- `reads[]` — **the ordered list of knowledge files to read**, each `{label, path, exists}`.
+- `unknown[]` — any `--repos` value not in the registry (run New-repo onboarding for each).
+
+**Do not run `deps` or `search` separately, and do not probe the filesystem for these docs.**
+The preflight already resolved everything; trust `reads[]`.
+
+Then, for **each repo in `loadSet`**, get its local code path (so you can navigate the actual
+source — this is the one thing preflight can't know):
 - Look for a Claude `reference` memory named `repo-path-<repo>` (e.g. `repo-path-worker2`).
 - If absent, **ask**: "What is the path to the `<repo>` repository?" Validate it exists,
   then **write a `repo-path-<repo>` memory** (+ MEMORY.md pointer).
 
-Never ask for a repo the session doesn't touch.
+Never ask for a repo not in `loadSet`.
 
 ## Step 4 — Load the knowledge
 
-Read and internalize, in this order:
-1. **Framework core architecture** — `<TEAM_REPO>/knowledge/<fw>/apps/<core-repo>/architecture.md`
-   (e.g. `2.0/apps/_underscore/architecture.md`). Always load this first.
-2. **The chosen repo's** `architecture.md`, then feature docs matched to the description:
-   `node "<TEAM_REPO>/knowledge.js" search --framework=<fw> --repo=<repo> --q=<keywords>`.
-3. **Coding standards** for the framework(s): `<fw>/standards/backend-php.md` and/or
-   `frontend.md` per the layer answer (plus any others that exist). Load whichever exist.
-4. **Client knowledge** (if a real client): `clients/<client>/profile.md` and that client's
-   `features/`/`workflows/` filtered to the selected framework(s)
-   (`search --client=<client> --framework=<fw>`).
-
-For **both** frameworks, union across `1.0/` and `2.0/`.
+Read every entry in the preflight `reads[]` array **in order**, resolving each `path`
+against `<TEAM_REPO>/knowledge/`. Skip entries with `exists:false` — that doc isn't written
+yet; note it in the Step 5 summary as "no knowledge captured yet."
+
+The `reads[]` order already encodes the correct precedence (framework core architecture →
+chosen-repo architecture + matched features → dep architecture → standards → client profile +
+client docs), and already unions across `1.0/` and `2.0/` for a both-frameworks session. You
+do not need to re-derive this order or run any further `search`.
 
 **Do NOT create or modify any `CLAUDE.md` stub** — kickoff only reads. A blank session is a
 valid choice; this skill is opt-in.