toga-ai 1.0.1023 → 1.0.1024

package/knowledge/standalone/apps/claude/INDEX.md

@@ -5,7 +5,7 @@
 | [Memory Scope Guard — Keep Team Rules Out of Local Claude Memory](features/memory-scope-guard.md) | Rule + PostToolUse warn hook + `/finish` sweep that keep team build rules in the KB, not in one developer's private Claude memory. |
 | [Review-Enforcement Hooks — Mandatory sql-reviewer / php-reviewer Routing on Write](features/review-enforcement-hooks.md) | PostToolUse hooks that force a specialist review (`sql-reviewer` / `php-reviewer`) after SQL/PHP writes; open before turning either into a pre-write gate. |
 | [ClickUp Ticket Workflow — /start, /commit, /pseudocode, /finish](workflows/clickup-ticket-workflow.md) | Every Claude session is tied to one ClickUp ticket: the 4 skills, the ticket-write rules, the field ids, and the tested ClickUp facts. |
-| [Harness Distribution — How a knowledge.js Fix Reaches Teammates](workflows/harness-distribution.md) | How a `knowledge.js` fix reaches teammates — two copies exist, only the git clone matters; `npx toga-ai` pulls it. |
+| [Harness Distribution — How Harness Updates (skills, hooks, knowledge.js) Reach Teammates](workflows/harness-distribution.md) | How harness updates reach teammates — npm bundle (skills/agents/rules/hooks) + git clone (knowledge.js), both via `npx toga-ai@latest`. |
 | [Knowledge Base Publish / Push Pipeline](workflows/knowledge-publish-pipeline.md) | How `/finish` and `/session-save` push knowledge docs to `agilantsolutions/claude` `_main` — the git sequence, retry, and the `47fbdc4` PUSH_FAILED fix. |
 | [MCP Tool Usage — "Talos" Means the Internal Knowledge Base, and Run Your Own SELECTs](workflows/mcp-tool-usage.md) | "Talos" means the Internal Knowledge Base MCP (not the repo); run your own `toga-db` SELECTs unprompted. |
 | [Ticket-Branch Creation Safety — How the Retired /work-ticket Armed Pushes to Production Branches](workflows/ticket-branch-creation-safety.md) | How `/work-ticket` armed VS Code Commit+Sync to push ticket code straight to production branches — root cause, fixes, recovery. |

package/knowledge/standalone/apps/claude/workflows/harness-distribution.md

@@ -1,22 +1,24 @@
 ---
-title: Harness Distribution — How a knowledge.js Fix Reaches Teammates
+title: Harness Distribution — How Harness Updates (skills, hooks, knowledge.js) Reach Teammates
 framework: "standalone"
 repo: claude
 project: Claude Harness
 client: shared
 type: workflow
 status: active
-updated: 2026-10-09
+updated: 2026-10-14
 owners: ["jcardinal"]
 files:
   - claude/scripts/install.js
+  - claude/scripts/hooks/harness-version-check.js
+  - claude/scripts/hooks/lib/npm-latest.js
   - claude/knowledge.js
   - claude/.claude/settings.json
 related:
   - standalone/apps/claude/workflows/knowledge-publish-pipeline.md
 ---
 
-How a `knowledge.js` fix reaches teammates — two copies exist, only the git clone matters; `npx toga-ai` pulls it. Open when a harness fix "didn't take".
+How harness updates reach teammates — npm bundle (skills/agents/rules/hooks) + git clone (knowledge.js), both via `npx toga-ai@latest`. Open when a harness fix "didn't take".
 
 ## Summary
 
@@ -24,10 +26,14 @@ There are **two copies** of `knowledge.js` on a developer's machine, and the ski
 
 ## Steps
 
+0. **Update command is always `npx toga-ai@latest`.** Bare `npx toga-ai` reuses the npx cache and reinstalls the old version. npm is the only update path: `sync-skills.js` and `/sync-team-skills` are retired.
+   - SessionStart hook `scripts/hooks/harness-version-check.js` compares `<project>/.claude/toga-ai.version` to npm latest (`scripts/hooks/lib/npm-latest.js`) and warns "Run: npx toga-ai@latest" every session until updated. Warn-only, exit 0, never blocks. Cache `~/.claude/toga-ai-latest.json`: 1h; 10 min after a failed lookup; a future `checkedAt` counts as expired. Opt-out `TOGA_VERSION_CHECK_DISABLED=1`.
+   - **Decided (dev + CTO, TRUE-82829): warn, never auto-update at session start.** Auto-update overwrites loaded skills/hooks/settings mid-session and fails silently on Windows.
+
 1. The two copies:
    - `/finish`, `/start`, `/session-save` all invoke `node "<TEAM_REPO>/knowledge.js"` — the **git clone's** copy at `~/toga-tech/knowledge.js`.
    - The npm bundle installs a *separate* copy into the project's `.claude/knowledge.js`. The skills do not run it, so a new published npm version alone changes nothing about captures.
-2. Deliver a fix: run `npx toga-ai`. It calls `tryGitPull()` (`scripts/install.js`, ~lines 182-210, called at ~line 548), which does `git pull --ff-only` inside `~/toga-tech`. **That pull is what actually delivers a fixed `knowledge.js`.**
+2. Deliver a fix: run `npx toga-ai@latest`. It calls `tryGitPull()` (`scripts/install.js`, ~lines 182-210, called at ~line 548), which does `git pull --ff-only` inside `~/toga-tech`. **That pull is what actually delivers a fixed `knowledge.js`.**
 3. Equivalent manual route: `git -C ~/toga-tech pull`.
 4. Verify a teammate has a given fix:
 
@@ -39,11 +45,13 @@ There are **two copies** of `knowledge.js` on a developer's machine, and the ski
 
 ## Gotchas
 
+- **On Windows, `spawnSync('npm', {shell:false})` fails** (needs `npm.cmd`). This silently killed install.js's "newer version" warning, so devs ran stale harnesses. Use the shared `lib/npm-latest.js` lookup, not a raw spawn.
+
 - **`npx toga-ai` can silently fail to update the knowledge repo** (open issue, not yet fixed). On a non-zero `git pull --ff-only` exit, `tryGitPull()` returns `{ pulled: false, newDocs: 0, message: null }` — the git stderr is discarded and **nothing is printed to the developer**. A teammate whose pull is refused (e.g. local edits to a tracked file the incoming commits also touch — `.claude/settings.json` is the usual culprit) will believe they are up to date while still running old tooling. Suggested fix, not applied: surface the git stderr in the `pulled: false` path so a refused pull is visible. Same defect class as the swallowed-stderr bug in the publish pipeline.
 - Until that is fixed, if a harness fix "didn't take", check the pull manually rather than trusting `npx toga-ai`'s output.
 
 - **The harness `.claude` lives only at the workspace root, never in a sub-repo.** Hook commands must anchor on `$CLAUDE_PROJECT_DIR` (`node "$CLAUDE_PROJECT_DIR/.claude/hooks/toga/X.js"`), not relative paths: relative paths resolve against cwd, so a sub-repo cwd gives MODULE_NOT_FOUND. A hook error naming a sub-repo `.claude` path is a path-resolution bug, not a folder to create. The settings file ships from the bundle, so the fix must live upstream or `npx toga-ai` reverts it.
-- **Publish Action (`.github/workflows/publish.yml`, on push to `_main`: bump patch, `npm publish`).** Devs get a change only after a version bump (`/start` runs `npx toga-ai@latest` when installed != latest).
+- **Publish Action (`.github/workflows/publish.yml`, on push to `_main`: bump patch, `npm publish`).** Devs get a change only after a version bump (the SessionStart version-check hook tells them to run `npx toga-ai@latest`).
   - `npm publish` **E404** ("could not be found or you do not have permission") = auth failure, not a missing package: the `NPM_TOKEN` secret in the repo's **Actions environment** expired. Fix: new npm Automation token, update the secret, re-run only the latest failed run.
   - A publish ships the whole tip of `_main`, so earlier failed runs are not lost. Do not retry old runs (they hit "version already published").
 - **Removing a permission rule from the shipped `.claude/settings.json` does not remove it from devs.** `mergeSettings()` only adds template rules. To retire one, also list it in `RETIRED_TOGA_PERMISSIONS` (`scripts/install.js`); `npx toga-ai` then filters it out of the dev's existing lists.
@@ -51,6 +59,7 @@ There are **two copies** of `knowledge.js` on a developer's machine, and the ski
 
 ## Change history
 
+- 2026-10-14 — Added `@latest` rule, SessionStart version-check hook, warn-not-auto-update decision, Windows npm.cmd gotcha; sync-team-skills retired (TRUE-82829). (jcardinal)
 - 2026-10-09 — Added permission-retire (`RETIRED_TOGA_PERMISSIONS`) and auto-mode settings-edit gotchas. (jcardinal)
 
 ## Related

package/package.json

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