toga-ai 1.0.95 → 1.0.96

package/knowledge/CONVENTIONS.md

@@ -58,6 +58,45 @@ The shared identity/topology of every repo. Maintained **only by the skills**.
 (`_underscore` for 2.0, `library` for 1.0), plus any transitive `dependsOn`.
 `node knowledge.js deps --repo=<repo>` resolves the full load order.
 
+## Client app-scope (`apps:` on `profile.md`)
+
+A single client's work routinely spans **several** repos/frameworks that are not obvious
+from the client's name — e.g. Compass USA touches `_underscore`, `api2`, `toga2-supply`,
+`worker` (1.0), and `dbchanges2`. A developer (or a teammate who only says *"I'm fixing a
+Compass bug"*) should **not** have to know or list those. So each client's `profile.md`
+declares its in-scope repos in an **`apps:`** frontmatter list:
+
+```yaml
+---
+title: Compass USA
+framework: "2.0"
+apps:                      # repos auto-loaded whenever this client is mentioned
+  - _underscore
+  - api2
+  - toga2-supply
+  - worker
+  - dbchanges2
+client: compass-usa
+type: profile
+...
+---
+```
+
+- **Auto-load.** `node knowledge.js kickoff-preflight --client=<slug>` unions a client's
+  `apps` into the chosen repos, so they are loaded **in full** (architecture + matched
+  features) even when the developer names no repos. The command works with `--client` alone.
+  The preflight output's `clientScope` block reports which repos came from the client vs. were
+  named by the developer. List a `core` repo (e.g. `dbchanges2`, `_underscore`) in `apps` when
+  its **full** doc matters for that client's work — otherwise core repos load only as summaries,
+  and detail-only rules (e.g. dbchanges2's mandatory `YYYY-MM-DD<letter>` filename suffix) can
+  be missed.
+- **Every entry must be a real, registered repo** — `validate` fails on an unknown `apps` repo.
+- **Auto-maintenance (capture's job — see the capture skill).** When a session's work for a
+  client touches a repo **not** in that client's `apps`, `capture` **adds it automatically** and
+  notes it — a teammate never has to tell us "also load app X for this client." Conversely, a
+  developer may explicitly ask to **add** or **remove** a repo from a client's scope, and that
+  instruction wins. Removal is the only way a repo leaves `apps`; detection only ever adds.
+
 ## Frontmatter (every doc)
 
 ```yaml

package/knowledge/clients/compass-canada/profile.md

@@ -1,6 +1,12 @@
 ---
 title: Compass Canada
 framework: "2.0"
+apps:
+  - _underscore
+  - api2
+  - toga2-supply
+  - worker
+  - dbchanges2
 project: _Underscore
 client: compass-canada
 type: profile

package/knowledge/clients/compass-usa/profile.md

@@ -1,6 +1,12 @@
 ---
 title: Compass USA
 framework: "2.0"
+apps:
+  - _underscore
+  - api2
+  - toga2-supply
+  - worker
+  - dbchanges2
 project: _Underscore
 client: compass-usa
 type: profile

package/knowledge/clients/elite/profile.md

@@ -1,6 +1,9 @@
 ---
 title: Elite
 framework: "2.0"
+apps:
+  - worker2
+  - library
 project: Worker
 client: elite
 type: profile

package/knowledge/clients/nycdoe/profile.md

@@ -1,6 +1,9 @@
 ---
 title: New York City Department of Education
 framework: "1.0"
+apps:
+  - worker
+  - library
 project: Worker
 client: nycdoe
 type: profile

package/knowledge/clients/office-depot/profile.md

@@ -1,6 +1,8 @@
 ---
 title: Office Depot
 framework: "2.0"
+apps:
+  - voice-to-voice
 project: TOGa Voice
 client: office-depot
 type: profile

package/knowledge/clients/prudential/profile.md

@@ -1,6 +1,10 @@
 ---
 title: Prudential Financial
 framework: "2.0"
+apps:
+  - _underscore
+  - api2
+  - dbchanges2
 project: _Underscore
 client: prudential
 type: profile

package/knowledge/clients/rate/profile.md

@@ -1,6 +1,10 @@
 ---
 title: "Rate"
 framework: "2.0"
+apps:
+  - _underscore
+  - saml
+  - toga2-view
 project: SAML SSO Gateway
 client: rate
 type: profile

package/knowledge/clients/tow-foundation/profile.md

@@ -1,6 +1,8 @@
 ---
 title: "Tow Foundation"
 framework: "2.0"
+apps:
+  - worker2
 project: Worker
 client: tow-foundation
 type: profile

package/knowledge.js

@@ -161,13 +161,14 @@ function cmdManifest() {
     if (fs.existsSync(clientsDir)) {
         for (const slug of fs.readdirSync(clientsDir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name)) {
             const profile = path.join(clientsDir, slug, 'profile.md');
-            let title = slug, framework = '';
+            let title = slug, framework = '', apps = [];
             if (fs.existsSync(profile)) {
                 const { data } = parseFrontmatter(fs.readFileSync(profile, 'utf8'));
                 title = data.title || slug;
                 framework = data.framework || '';
+                apps = Array.isArray(data.apps) ? data.apps : [];
             }
-            clients.push({ slug, title, framework });
+            clients.push({ slug, title, framework, apps });
         }
     }
     console.log(JSON.stringify({ repos, clients }));
@@ -198,9 +199,23 @@ function extractSection(body, heading) {
 
 function cmdPreflight(args) {
     const registry = loadRegistry();
-    const chosen = String(args.repos || '').split(',').map(s => s.trim()).filter(Boolean);
+    const devChosen = String(args.repos || '').split(',').map(s => s.trim()).filter(Boolean);
+    // Client-scoped apps: when a client is named, auto-include the repos listed in its
+    // profile.md `apps:` so a teammate who only mentions the client still gets every
+    // app/framework that client's work spans — without having to name them. Unknown
+    // repo names are ignored (validate flags them separately).
+    const slug = args.client && args.client !== 'shared' && args.client !== true ? String(args.client) : null;
+    let clientApps = [];
+    if (slug) {
+        const profilePath = path.join(ROOT, 'clients', slug, 'profile.md');
+        if (fs.existsSync(profilePath)) {
+            const { data } = parseFrontmatter(fs.readFileSync(profilePath, 'utf8'));
+            clientApps = (Array.isArray(data.apps) ? data.apps : []).filter(r => registry.find(x => x.repo === r));
+        }
+    }
+    const chosen = [...new Set([...devChosen, ...clientApps])];
     if (!chosen.length) {
-        console.log(JSON.stringify({ error: 'PREFLIGHT: --repos=<repo,repo> required' }));
+        console.log(JSON.stringify({ error: 'PREFLIGHT: provide --repos=<repo,repo> and/or --client=<slug> whose profile lists apps' }));
         process.exitCode = 1;
         return;
     }
@@ -266,7 +281,6 @@ function cmdPreflight(args) {
 
     // 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));
@@ -306,7 +320,11 @@ function cmdPreflight(args) {
         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 }));
+    // clientScope tells the kickoff skill which repos were auto-pulled from the client's
+    // profile.md `apps:` (vs. named by the developer) so it can show "loaded because you
+    // mentioned <client>" and the dev can still add/remove.
+    const clientScope = { client: slug, fromClient: clientApps, fromDev: devChosen };
+    console.log(JSON.stringify({ frameworks, loadSet, unknown, clientScope, repos: repoOut, standards, client, reads }));
 }
 
 /* ------------------------------------------------------------------ */
@@ -635,6 +653,13 @@ function cmdValidate() {
                 if (entry && d.data.project !== entry.project) { fail(`${d.rel}: project "${d.data.project}" != registry "${entry.project}"`); ok = false; }
             }
         }
+        // client profile `apps:` must reference real, registered repos (the client-scope
+        // load-set the kickoff skill auto-loads when this client is mentioned).
+        if (d.data.type === 'profile' && Array.isArray(d.data.apps)) {
+            for (const app of d.data.apps) {
+                if (!registry.find(r => r.repo === app)) { fail(`${d.rel}: apps lists unknown repo "${app}"`); ok = false; }
+            }
+        }
         if (ELEVATED_TYPES.includes(d.data.type)) elevated.push(d.rel);
         for (const s of scanSecrets(fs.readFileSync(d.file, 'utf8'))) {
             fail(`${d.rel}:${s.line}: possible secret committed — ${s.reason}; redact it (reference the config/constant location, never paste credential values into knowledge docs)`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.95",
+  "version": "1.0.96",
   "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

@@ -189,6 +189,30 @@ config key, the file) but not its value. `validate` (run by Step 6's publish and
 pre-commit hook) scans for credential literals and **fails the publish** if it finds one, so
 a leaked secret blocks the whole capture until redacted. Reference, never reproduce.
 
+## Step 5b — Maintain the client's app-scope (`apps:` on `profile.md`)
+
+When this session's work was **for a specific client**, keep that client's `apps` list (the
+repos auto-loaded whenever the client is mentioned — see `CONVENTIONS.md` → *Client app-scope*)
+in sync. **This is automatic — a teammate must never have to tell us "also load app X for this
+client."**
+
+1. **Detect.** Collect every repo this session actually touched (from the files changed and the
+   `files:` you wrote on docs this capture). Read the client's `clients/<slug>/profile.md`
+   `apps:` list.
+2. **Auto-add.** For any touched repo **not** already in `apps`, add it to the profile's `apps`
+   list (and bump `updated`). Detection only ever **adds** — never silently removes. Briefly note
+   each addition in the Step 7 report (e.g. "Added `dbchanges2` to Compass USA scope"). Add a
+   `core` repo (e.g. `dbchanges2`, `_underscore`) when its **full** doc — not just its summary —
+   mattered to the work, so the next session loads it in full.
+3. **Honor explicit instructions (these win).** If the developer said to **add** or **remove** a
+   repo from the client's scope this session, apply it: add even if untouched, or remove even if
+   touched. Removal happens **only** on an explicit request.
+4. **New client with no `apps` yet?** Seed it from the repos this session touched.
+
+The `apps` change is an ordinary `profile.md` edit (not elevated) — apply it without asking,
+then it publishes with everything else in Step 6. `validate` rejects an `apps` entry that is not
+a registered repo, so only add real repos (run New-repo onboarding first if needed).
+
 ## Step 6 — Publish (validate → index → mirror → rebase-push, one command)
 
 Finish every capture with the deterministic publisher — **do not** run validate/index/git
@@ -366,6 +390,8 @@ any client docs:
 ---
 title: "<Formal Client Name>"   # the client's formal name IS the title; slug is only the folder
 framework: "<1.0|2.0>"
+apps:                           # repos auto-loaded when this client is mentioned (seed from
+  - <repo>                      # the repos this session touched; maintained per Step 5b)
 project: <Project>
 client: <slug>
 type: profile

package/skills/kickoff/SKILL.md

@@ -138,7 +138,7 @@ When resolved, if there was no `team-repo-path` memory, **write one** (memory ty
 ## Step 2 — Interview the developer (ask the work questions FIRST)
 
 Get the pickable lists in **one call**: `node "<TEAM_REPO>/knowledge.js" manifest` returns
-minified JSON `{repos:[{repo,project,framework,role}], clients:[{slug,title,framework}]}`.
+minified JSON `{repos:[{repo,project,framework,role}], clients:[{slug,title,framework,apps}]}`.
 **Do not read `registry.json` or any `profile.md` to build these lists.** Ask all questions
 in one message:
 
@@ -147,12 +147,25 @@ in one message:
 3. **Repo(s) / project(s)** — list EVERY manifest repo for the chosen framework(s).
    **Multi-select (checkbox), not single choice** — a session often spans several repos. If
    they name a repo not listed, run **New-repo onboarding** (below) for each before continuing.
+   **This question is OPTIONAL when a client is chosen** — that client's `apps` are auto-loaded
+   (see the client-scope note below), so a developer who only knows the client need not pick
+   repos. Use it to let them *add* repos beyond the client's scope.
 4. **Client** — list EVERY manifest client by its **`title`** (the formal name, not the slug),
    plus "shared / internal" and "a new client".
 5. **What are you building or changing?** (a sentence — used to pick relevant feature docs.)
 
 If any answer is unclear, ask again. Do not guess framework, repo, project, or client.
 
+**Client app-scope (do this automatically — never make the developer enumerate apps).** Each
+client in the manifest carries an `apps` list — the repos/frameworks that client's work spans
+(e.g. Compass USA → `_underscore, api2, toga2-supply, worker, dbchanges2`). When a client is
+chosen, **all of its `apps` are loaded for you by preflight** even if the developer named no
+repos — so "I'm fixing a Compass bug" is enough. After loading, briefly tell the developer
+which repos were pulled in because of the client (from preflight's `clientScope.fromClient`),
+and that they can say **"also add `<repo>`"** or **"drop `<repo>` for this session"** to adjust.
+A session-only add/remove does **not** change the client's stored scope; a request to change it
+**for this client going forward** is a profile edit captured at `/capture` time.
+
 **Presenting q3 and q4:** do NOT use the option-chip / radio control — it caps at ~4 options
 and silently truncates a 7-repo / 5-client list. Render the full list as a numbered markdown
 list and have the developer reply with numbers (e.g. "1, 3, 5") — no cap, supports
@@ -172,8 +185,15 @@ node "<TEAM_REPO>/knowledge.js" kickoff-preflight \
   --q=<2-4 keywords from the developer's task sentence>
 ```
 
+`--repos` is **optional when `--client` is given** — the client's `apps` are auto-unioned into
+the load-set, so `--client=<slug>` alone resolves the full set. Pass `--repos` only to add repos
+the developer named beyond the client's scope (or for a shared/internal session with no client).
+
 It prints minified JSON:
-- `loadSet` — framework core(s) + chosen repos + transitive `dependsOn`, in load order.
+- `loadSet` — framework core(s) + chosen repos + the client's `apps` + transitive `dependsOn`,
+  in load order.
+- `clientScope` — `{client, fromClient[], fromDev[]}`: which repos were auto-loaded from the
+  client's profile vs. named by the developer. Surface `fromClient` to the developer in Step 5.
 - `repos[]` — each with `architecture` `{path,exists}`, `role`, `chosen`, an inline
   `summary` (for non-chosen repos), and matched `features[]` (features returned only for the
   repos the developer chose, not deps).