toga-ai 1.0.170 → 1.0.172

package/knowledge/sessions/2026-06-23-team-shared-sessions-jcardinal.md

@@ -0,0 +1,69 @@
+---
+type: session
+slug: team-shared-sessions
+title: Team-shared sessions + skill discovery
+author: jcardinal
+repos: [_underscore]
+framework: "2.0"
+client: shared
+status: active
+created: 2026-06-23
+updated: 2026-06-23
+---
+
+# Session: team-shared-sessions
+**Date:** 2026-06-23
+**Project/Repo:** toga-tech harness (team `claude` repo) — not an application repo
+**Task:** Make /session-save and /session-resume store sessions in the team knowledge repo (knowledge/sessions/) so one developer can save an in-progress session and another can resume it, with automatic push/pull, a way to list sessions, and manual delete of stale ones — plus a /team-skills discovery skill.
+
+---
+
+## What WORKED
+- Added five subcommands to `knowledge.js` (committed to `_main`, `44f740d`): `session-save`, `session-list`, `session-show`, `session-delete`, `skills`. Verified: `node -c knowledge.js` passes; `skills --installed=d:/WWW/.claude/skills` correctly flags `worker2-action` as local-only; `session-list` empty + populated both render.
+- Key design win confirmed during exploration: `knowledge/sessions/` rides the existing `publish` git rails for free, AND `allDocs()` only walks `1.0/ 2.0/ standalone/ clients/`, so `validate`/`index` ignore `sessions/` with zero exemption code. `node knowledge.js validate` → "OK (24 repos)" with a session file present.
+- `session-list`/`show`/`delete` read from `origin/<branch>` via `git ls-tree`/`git show` after a `git fetch` — shows teammates' pushed sessions without touching the working tree. Verified working-tree fallback when origin has none.
+- All three `session-save` guard paths reject BEFORE any push: outside-dir → `ABORT_OUTSIDE_SESSIONS`; missing keys → `INVALID — missing frontmatter: ...`; planted `AKIA...` key → `SECRET — line N: AWS access key id`.
+- Rewrote `skills/session-save/SKILL.md` (team-by-default + local fallback) and `skills/session-resume/SKILL.md` (fetch-first; `latest`/`<slug-or-id>`/`list`/`delete <id>`; briefing names the author).
+- Created `skills/team-skills/SKILL.md` (read-only discovery; pairs with `/sync-team-skills`).
+- Updated `scripts/hooks/session-start.js`: time-boxed (3500ms) `teamSessions()` peek that prints available team sessions; fails silent offline. `node -c` passes; runs clean (silent when no sessions — correct).
+- Documented `type: session` + `knowledge/sessions/` in `knowledge/CONVENTIONS.md`.
+- Synced all skills to `d:\WWW\.claude\skills` via `node sync-skills.js d:/WWW` (9 skills incl. team-skills) and copied the updated hook locally.
+- Committed only the 6 intended files + new `team-skills/` to `_main` and pushed (had to `git stash push -- CLAUDE.md` first because of a pre-existing unstaged CLAUDE.md edit; popped it back after).
+
+## What did NOT work — DO NOT RETRY THESE
+- `git rebase origin/_main` failed with `error: cannot rebase: You have unstaged changes` because `CLAUDE.md` had a PRE-EXISTING (not-ours) modification in the team repo working tree. FIX that worked: `git stash push -- CLAUDE.md`, rebase+push, then `git stash pop`. Do NOT commit CLAUDE.md to "fix" this — that edit is not ours.
+- Do NOT treat `toga-tech/.claude/skills/` as the source of truth — it is untracked/gitignored (a local install). The COMMITTED source is the root-level `skills/`, `knowledge.js`, `sync-skills.js`, `scripts/hooks/`. Editing `.claude/` copies would not ship.
+
+## Not tried yet (candidates for next session)
+- Optional: `knowledge.js skills --write-readme` (or fold into `sync-skills.js`) to regenerate the stale README skill table from frontmatter automatically. Explicitly deferred this session.
+- End-to-end cross-developer resume has only been simulated locally (origin had no sessions during testing). Once this very session file is pushed, verify `/session-resume team-shared-sessions` from a fresh clone / another machine.
+- `session-list` does a network `git fetch` (6s timeout) on every call; the startup hook bounds it to 3.5s. Consider a `--no-fetch` fast path for the hook if startup latency is felt in practice.
+
+## Current file state
+| File | Status | Notes |
+|------|--------|-------|
+| toga-tech/knowledge.js | Modified, committed `44f740d` | +session-* and skills subcommands, shared `pushStaged()` helper |
+| toga-tech/skills/session-save/SKILL.md | Modified, committed | team-by-default save + push, local fallback |
+| toga-tech/skills/session-resume/SKILL.md | Modified, committed | fetch-first; latest/slug/list/delete; author in briefing |
+| toga-tech/skills/team-skills/SKILL.md | Created, committed | new discovery skill |
+| toga-tech/scripts/hooks/session-start.js | Modified, committed | team-session startup peek |
+| toga-tech/knowledge/CONVENTIONS.md | Modified, committed | type: session schema + sessions/ layout |
+| d:/WWW/.claude/skills/* + hooks/toga/session-start.js | Synced locally | for immediate local use (gitignored install) |
+| toga-tech/CLAUDE.md | Pre-existing unstaged edit (NOT ours) | left untouched; was stashed/popped during push |
+
+## Decisions made
+- Store sessions under `knowledge/sessions/` (not a new top-level dir) — reuses `publish` staging + `npx toga-ai` distribution with no new git plumbing. Rejected: separate branch per session (merge complexity), separate sync mechanism.
+- One file per session named `YYYY-MM-DD-<slug>-<author>.md` — author suffix prevents slug collisions between developers.
+- Team-by-default save; local `~/.claude/session-data` only as offline/no-clone fallback. (User decision.)
+- Cleanup = manual delete + age flagging (`STALE` > 14 days); no auto-deletion. (User decision.)
+- SessionStart hook surfaces team sessions with a timeout-guarded fetch. (User decision.)
+- Sessions are NOT knowledge docs: they get their own lightweight frontmatter + secret scan in `session-save`, and are deliberately excluded from `validate`/`index` (free, via `allDocs()` scope).
+
+## Blockers
+none
+
+## Exact next step
+> From a fresh clone or another machine, run `/session-resume team-shared-sessions` and confirm it fetches and renders this session's briefing — the real cross-developer round-trip that was only simulated locally this session.
+
+---
+_Saved by /session-save on 2026-06-23_

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.170",
+  "version": "1.0.172",
   "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/session-resume/SKILL.md

@@ -47,7 +47,12 @@ to change the threshold. If it prints "No team sessions saved yet.", say so and
 No team sessions saved yet. Save one at the end of your work: /session-save [name]
 ```
 
-**`list` mode:** render this table and stop here.
+Whenever you render this table to the developer (in `list` mode **and** in the
+no-argument discovery flow), explicitly disclose that delete is available — e.g. a
+trailing line: "To retire a stale session, run `/session-resume delete <id>`." A
+developer must never have to already know the command to discover it.
+
+**`list` mode:** render this table (with the delete disclosure) and stop here.
 
 **`delete <id>` mode:** confirm with the developer, then run
 `node "<TEAM_REPO>/knowledge.js" session-delete <id> --msg="session: retire <id>"`,
@@ -61,7 +66,8 @@ report the `SESSION: DELETED|NOT_FOUND|CONFLICT` result, and stop.
 - `<slug-or-id>` → the row whose id equals it or contains the slug. If several match
   (same slug, different authors/dates), show those candidates (date + author) and ask which.
 - If none match: "No session found matching '<x>'. Available: [list ids]."
-- No argument → ask: "Which session should I load? (id or slug)"
+- No argument → ask: "Which session should I load? (id or slug — or `delete <id>` to
+  retire a stale one)"
 
 ---