toga-ai 1.0.480 → 1.0.481

package/knowledge/INDEX.md

@@ -39,6 +39,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 - **togatech** (TOGA Technology Website) — 4 doc(s) → [standalone/apps/togatech/INDEX.md](standalone/apps/togatech/INDEX.md)
 - **websocket** (WebSocket Server) — 2 doc(s) → [standalone/apps/websocket/INDEX.md](standalone/apps/websocket/INDEX.md)
 - **forward** (Forwarder) — 3 doc(s) → [standalone/apps/forward/INDEX.md](standalone/apps/forward/INDEX.md)
+- **claude** (Claude Harness) — 2 doc(s) → [standalone/apps/claude/INDEX.md](standalone/apps/claude/INDEX.md)
 
 ## Clients
 

package/knowledge/registry.json

@@ -184,7 +184,9 @@
     "project": "TOGa Commerce",
     "framework": "2.0",
     "role": "app",
-    "dependsOn": ["api2"]
+    "dependsOn": [
+      "api2"
+    ]
   },
   {
     "repo": "toga",
@@ -227,5 +229,12 @@
       "api2",
       "worker2"
     ]
+  },
+  {
+    "repo": "claude",
+    "project": "Claude Harness",
+    "framework": "standalone",
+    "role": "app",
+    "dependsOn": []
   }
 ]

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

@@ -0,0 +1,6 @@
+# claude (Claude Harness) — standalone knowledge
+
+| Doc | Summary | Files |
+|-----|---------|-------|
+| [Harness Distribution — How a knowledge.js Fix Reaches Teammates](workflows/harness-distribution.md) | There are **two copies** of `knowledge.js` on a developer's machine, and the skills use only one of them. | claude/scripts/install.js, claude/knowledge.js |
+| [Knowledge Base Publish / Push Pipeline](workflows/knowledge-publish-pipeline.md) | How `/capture` and `/session-save` get knowledge docs from your working tree into `agilantsolutions/claude` on `_main`. | claude/knowledge.js |

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

@@ -0,0 +1,57 @@
+---
+title: Harness Distribution — How a knowledge.js Fix Reaches Teammates
+framework: "standalone"
+repo: claude
+project: Claude Harness
+client: shared
+type: workflow
+status: active
+updated: 2026-07-30
+owners: ["jcardinal"]
+files:
+  - claude/scripts/install.js
+  - claude/knowledge.js
+related:
+  - standalone/apps/claude/workflows/knowledge-publish-pipeline.md
+---
+
+## Summary
+There are **two copies** of `knowledge.js` on a developer's machine, and the skills use only
+one of them. Publishing a new npm version does **not** fix a teammate's `/capture` — the git
+clone is what has to be updated. `npx toga-ai` is the mechanism that does it.
+
+## How it works
+- `/capture`, `/kickoff`, and `/session-save` all invoke
+  `node "<TEAM_REPO>/knowledge.js"` — that is 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.
+- `npx toga-ai` runs `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`.**
+- Equivalent manual route: `git -C ~/toga-tech pull`.
+
+Verify a teammate has a given fix:
+
+```
+git -C ~/toga-tech log --oneline -1 knowledge.js
+```
+
+For the 2026-07-30 publish/push fix, that must show `47fbdc4` or newer.
+
+## Gotchas / known issues
+- **`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 that 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.
+
+## Change history
+- 2026-07-30 — Documented that the skills run the git clone's `knowledge.js` (not the npm
+  bundle copy), so `npx toga-ai` / `git -C ~/toga-tech pull` is required to distribute a
+  harness fix; recorded the silent `tryGitPull()` failure as a known issue. (jcardinal)

package/knowledge/standalone/apps/claude/workflows/knowledge-publish-pipeline.md

@@ -0,0 +1,72 @@
+---
+title: Knowledge Base Publish / Push Pipeline
+framework: "standalone"
+repo: claude
+project: Claude Harness
+client: shared
+type: workflow
+status: active
+updated: 2026-07-30
+owners: ["jcardinal"]
+files:
+  - claude/knowledge.js
+related:
+  - standalone/apps/claude/workflows/harness-distribution.md
+---
+
+## Summary
+How `/capture` and `/session-save` get knowledge docs from your working tree into
+`agilantsolutions/claude` on `_main`. Both go through `knowledge.js` — `cmdPublish()` for
+`/capture`, `pushStaged()` for `/session-save`. Both run the same three-step git sequence,
+and both had the same defect until 2026-07-30 (`47fbdc4`): they reported `PUSH_FAILED` on
+every run while a manual `git push` always worked.
+
+## How it works
+The publish sequence, run inside the team repo clone (`~/toga-tech`):
+
+1. `node knowledge.js validate` — aborts the publish on any `ERROR:` line.
+2. `git add` the touched paths under `knowledge/` and commit.
+3. `git fetch origin <branch>`
+4. `git rebase --autostash origin/<branch>`
+5. `git push origin HEAD:<branch>`
+
+Steps 3–5 are wrapped in a 3-attempt retry with a 2s/4s backoff between attempts
+(`sleepSync()`, implemented with `Atomics.wait`). On final failure the tool prints both the
+manual-push command **and** the underlying git error:
+
+```
+PUBLISH: PUSH_FAILED after 3 attempts — run manually: git -C "<TEAM>" push origin HEAD:_main
+PUBLISH: last git error — <git stderr, first 5 lines>
+```
+
+`/session-save` prints the same pair under a `SESSION:` prefix.
+
+Direct commits to `_main` in this repo are intentional and are the documented exception to
+the team's branch-protection rule. Force-pushing is never automatic here either.
+
+## Gotchas / known issues
+- **`git rebase` refuses to run while ANY tracked file has unstaged changes** — even a file
+  with nothing to do with `knowledge/`. It exits with
+  `error: cannot rebase: You have unstaged changes.` That means the rebase failed *before*
+  the push was ever attempted, which is why the manual `git push` always succeeded (push
+  does not require a clean working tree). `--autostash` is therefore **required, not a
+  nicety**: it stashes the unrelated edits, rebases, and restores them. Do not remove it.
+- **This was never a CI race.** The retry loop's original comment claimed it was retrying a
+  "CI version-bump race". That diagnosis was wrong, and three instant retries just repeated
+  the same deterministic failure three times.
+- **`.claude/settings.json` is tracked in this repo and is edited by the harness itself**, so
+  local drift there is expected and recurring. It was the dirty file that made the failure
+  100% reproducible on at least one machine. `--autostash` makes publish tolerate it, but the
+  drift still wants a periodic `git diff .claude/settings.json` decision — commit it or revert
+  it. It is also the file most likely to make `npx toga-ai`'s `git pull --ff-only` refuse (see
+  the harness distribution doc).
+- **A `catch` that discards `stderr` disguises a deterministic bug as a flaky one.** This bug
+  went undiagnosed for months purely because `catch (e)` threw git's stderr away while git was
+  naming the exact cause on every single run. Any retry wrapper around a shell command in this
+  repo must surface `e.stderr || e.stdout` on final failure.
+
+## Change history
+- 2026-07-30 — Fixed permanent `PUSH_FAILED`: `git rebase` → `git rebase --autostash`, surface
+  git stderr as a `last git error` line, and add 2s/4s backoff (`sleepSync()`) between retries.
+  Applied identically in `cmdPublish()` and `pushStaged()`, which had the same defect
+  (`47fbdc4`). (jcardinal)

package/package.json

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