Commit Graph
11 Commits
Author SHA1 Message Date
james.maesandClaude Opus 4.7 5ebe510627 docs: scrub Phase-7 + JarvisBusWorld doc drift (#19, #45) (#195)
* docs(memory): scrub Phase-7 hedge language from MemoryStore (#19)

Audit 2026-05-12 flagged five doc-comment references that mis-described
the implementation state. The cited plans (07-02, 07-03, 07-06) shipped
months ago — the bounded extraction channel, the hybrid FTS5 + vec0 read
path, the ReplayEvent emission, the regression corpus test seams, and
`installMemory`'s replay-sink wiring are all live, not "wires" or
"will replace" promises.

Five touchpoints rewritten to describe the code as it is:

- `MemoryReplaySink` doc: drop the "Plan 07-06" plan reference; the seam
  is just used at startup.
- `MemoryStore` actor doc: replace the "Plan 07-02 wires / Plan 07-03
  wires" sentence with the actual contract (single writer; hybrid search
  through `MemoryReadStore`; `recordRetrieval` emits `memoryRetrieval`).
- Read-path MARK: drop the "Plan 07-03" plan label; keep the
  requirement-ID list (MEM-07 / TEXT-03 / D-02 / D-05) since those are
  still useful for traceability to the audit corpus.
- `recordRetrieval` doc: replace "Mirrors recordMemoryMutation from 07-02"
  with "Mirrors recordMemoryMutation on the write path."
- Test-seams MARK: drop "Plan 07-06" prefix; describe by the test target
  (JARVIS_REAL_MODELS=1 corpus suite) instead.

The 2026-05-11 D-5/D-6 markers and the "Boot policy (changed 2026-05-11)"
doc are preserved unchanged — they document current behaviour, not
historical hedges.

`swift build --package-path packages/Memory` clean.

Closes #19

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* docs(bus): scrub JarvisBusWorld drift + add grep gate (#45)

`fb41c5f` (2026-05-02) unified `Injection.js` and the HUD bundle into the
default `WKContentWorld.page` and retired the prior isolated
`JarvisBusWorld` named world. The doc-comments and test fixtures across
20+ lines kept describing the bug-era topology — pre-existing-bus attach
"because cross-world isolation", message-handler-only-visible-in-named-
world, etc. — for months afterward. Result: a new reader following the
docs would conclude the bus uses two worlds when it actually uses one.

Five rationale rewrites:

- `WebviewBridge.swift` class doc — handler is on the page world, not an
  isolated named world. Page scripts in the loaded HUD bundle address it
  via `window.webkit.messageHandlers.jarvisBus`.
- `Injection.js` header — names the page world explicitly; one-line nod to
  `fb41c5f` for the historical context.
- `bridge.ts` JSDoc + `isJarvisBusShape` rationale — recast the H-02
  attach-to-existing path as a "defensive double-install guard" inside
  ONE page world. Injection.js fires first at document-start; the bundle
  installer fires later as a top-level `main.tsx` side-effect; the guard
  prevents the bundle from clobbering Injection.js's queued early
  messages and captured handshake state. The duck-type `isJarvisBusShape`
  CODE is unchanged — only the comment narrative was misleading.
- `webview/packages/hud/src/main.tsx` — drop the cross-world-isolation
  framing; describe the single-world reality.
- `App/AppDelegate.swift` install comment — page world, not isolated.

Test-side updates (same scrub, plus one latent test bug surfaced):

- `WebviewBridgeTests.test_scriptMessageHandlerIsRegisteredUnderConfigured-
  Name`: was removing from `WKContentWorld.world(name: "JarvisBusWorld")`
  while the bridge registered against `.page` — silent no-op since
  `removeScriptMessageHandler` doesn't throw on absent. Now removes from
  `.page` (the world the bridge actually uses), making the
  "registration-is-evidence-of-success" assertion meaningful again.
- `WebviewBridgeOutboundTests`: comment-only.
- `RealWKWebViewIntegrationTests`: comment-only (forensic narrative kept,
  literal world name replaced with "prior isolated named content world").
- `webview/packages/bus/tests/bridge.test.ts`: H-02 describe-block + one
  it-name rewritten to match the new defensive-double-install rationale.

Infrastructure:

- `scripts/check-no-jarvis-bus-world-references.sh`: new boundary gate.
  Greps for the literal `JarvisBusWorld` in tracked files; excludes
  `.planning/`, `docs/`, `webview/packages/*/dist/`, and this script
  itself. Wired into `CLAUDE.md`'s gate listing; the CI
  `boundary-gates` job auto-discovers all `scripts/check-*.sh`, so no
  workflow edit is needed.
- `webview/packages/bus/package.json`: 0.0.0 → 0.0.1 (per spec —
  comment-only changes still bump patch so consumers can pin).
- `webview/packages/bus/dist/bridge.{js,d.ts}`: rebuilt via `pnpm --filter
  @jarvis/bus build`; NOT committed because `dist/` is not tracked (the
  build phase regenerates on each xcodebuild invocation).

Verified locally:
- `swift build --package-path packages/Bus` clean
- `pnpm --filter @jarvis/bus test` — 37/37 pass
- `bash scripts/check-no-jarvis-bus-world-references.sh` — PASS
- `bash scripts/check-bus-protocol-version.sh` — PASS (v2.3.0)
- `bash scripts/check-bus-harness-parity.sh` — PASS

Closes #45

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-14 09:51:03 -05:00
james.maes 4cdb3560e9 ci(actions): age-filter zombie reaper (>= 1h) for multi-runner safety (#189)
Grogu will host multiple self-hosted runners simultaneously (planned: 3
runners). Each runner's job-start cleanup step previously killed ANY
xctest/swift-test/swift-driver — meaning sibling runners would nuke
each other's in-flight tests.

Real CI jobs complete in <10 min. Zombies from interactive Xcode use
are typically >hours old. A 1-hour age cutoff cleanly separates the
two populations.

awk filter: ps -o etime formats are `MM:SS` (<1h), `HH:MM:SS` (>=1h),
or `DD-HH:MM:SS` (days). Match the latter two by testing for `-` (days
prefix) or three `:`-separated groups.

Single-runner behavior unchanged. Validated against synthetic ps
output covering all three etime format cases.

Closes #188
2026-05-13 17:33:03 -05:00
james.maes 81ce64c3f7 ci(actions): reap orphan xctest/swift-test on self-hosted before each job (#183)
Grogu is a shared workstation, not an ephemeral VM. Interactive Xcode
test runs, aborted swift test sessions, or debugger crashes can leave
orphan xctest/swift-test/swift-driver processes around for hours,
holding Mach services + sockets + ports that subsequent CI jobs block
on when mounting their own test infrastructure.

Concrete incident: develop run 25824607025 hung in SPM AgentCore for
34 min (0% CPU, sleeping state) while 6 unrelated xctest zombies aged
22-24h were alive from prior interactive use. The runner only executes
one job at a time, so any such process at job start belongs to no live
job and is safe to kill.

Add a first step that runs SIGTERM then SIGKILL on any
xctest/swift-test/swift-driver process. Gated to runner.environment ==
'self-hosted' since github-hosted VMs start clean.

Closes #182
2026-05-13 16:37:27 -05:00
james.maes 5fc2d3fabf docs: reconcile Ollama model baseline to actual production names (#184)
The codebase moved to qwen3.6:latest (memory extractor) and
qwen2.5-coder:32b-instruct-q8_0 (agent fallback) in commit 8d0a959, but
CLAUDE.md and the MemoryRegressionCorpusTests doc-comments still cited
the vanilla qwen2.5-coder:32b string. Both updated to match what
ModelID.swift, MemoryExtractor.swift, and BootHealth.swift actually
use today.

No behavior change — documentation alignment only.

Closes #58
2026-05-13 16:25:00 -05:00
james.maesandClaude Opus 4.7 eef1725292 ci: move swift-packages matrix to self-hosted runner (Grogu) (#181)
* ci(actions): move swift-packages matrix to self-hosted runner (Grogu)

The github-hosted macos-15 pool was the rate-limiting step for v0.1: 13
matrix jobs + 1 app-build job all needed macOS slots, GitHub scheduled
them 1-3 at a time, and total wall-clock was ~1-2h per run versus actual
work of <10m. Grogu is registered with labels [self-hosted, macOS, ARM64,
jarvis] and _work/ symlinked to HD-2 (1.3 TB) for headroom.

Scope:
- swift-packages matrix only — app-build stays on macos-15 for now.
- `if:` clause blocks fork PRs from triggering self-hosted jobs (push,
  workflow_dispatch, and same-repo PRs only).
- Xcode select switches from `sudo xcode-select -s` to a per-process
  DEVELOPER_DIR env so the runner doesn't need passwordless sudo. The
  fallback chain now also accepts /Applications/Xcode.app/Contents/Developer
  so Grogu's local Xcode 26.5 is picked up.

Closes #180

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* ci(actions): fix self-hosted runner env quirks for keychain + cache

Three SPM failures on PR #181's first self-hosted CI run, all
environment-specific:

- SPM Keychain: errSecInteractionNotAllowed (-25308). The LaunchAgent
  has no UI session and the login keychain is locked.
- SPM Voice + SPM Harness: github-hosted actions/cache@v4 entries with
  absolute paths (/Users/runner/work/...) baked into
  .build/artifacts/onnxruntime.xcframework. Cache key only contained
  runner.os (= macOS for both environments), so self-hosted hit the
  poisoned github-hosted cache.

Fixes:

- Restrict actions/cache@v4 to runner.environment == 'github-hosted'.
  Self-hosted's _work/ on HD-2 persists between jobs naturally, so the
  cache action is unnecessary there and prevents path-baked cache
  poisoning between environments.

- Add a "Unlock runner keychain" step gated to runner.environment ==
  'self-hosted'. Unlocks a pre-created jarvis-runner.keychain-db with
  password from the repo secret JARVIS_RUNNER_KEYCHAIN_PASSWORD and
  prepends it to the user search list so SecItemAdd writes there.

Document both in CLAUDE.md "Self-hosted CI runner".

Refs #180

* ci: retrigger after JARVIS_RUNNER_KEYCHAIN_PASSWORD secret fix

Previous run failed all 13 SPM jobs with 'passphrase you entered is not
correct' because the secret value was set to literal '-' (gh secret set
parsed '--body -' as the body value, not as 'read from stdin'). Secret
now contains the correct password. This empty commit triggers a fresh
CI run that will resolve the corrected secret.

Refs #180

* ci(actions): drop set-keychain-settings from unlock step

The Security framework requires user interaction for set-keychain-settings
even when the keychain is unlocked, and the LaunchAgent on Grogu has no
UI. The settings (no-timeout, no-lock-on-sleep) are persistent and were
applied once at keychain-creation time; only the unlock step needs to
run every job.

Refs #180

* ci(actions): also set default-keychain so SecItemAdd targets jarvis-runner

SecItemAdd on the legacy file-based macOS keychain writes to the user's
DEFAULT keychain, not the first writable keychain in the search list.
Changing list-keychains alone left SecItemAdd targeting the locked
login.keychain-db, still returning errSecInteractionNotAllowed (-25308).

Also set the user's default keychain to jarvis-runner.keychain-db in the
unlock step. This is persistent for the runner user (james.maes), so
SecItemAdd from interactive use will also go there — documented as a
side effect in CLAUDE.md with the undo command.

Refs #180

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-13 15:29:09 -05:00
james.maes 61e06fb2dc docs(roadmap): user-outcome-focused milestone roadmap
All 142 open issues triaged into 6 GitHub milestones organized by
user-facing capability rather than technical area:

- v0.1 — It actually works (28 issues): voice, listening, seeing,
  facts, debugging dialogs, basic UI. Tactical patches for CRITICAL
  audit findings so user has working Jarvis NOW.
- v0.2 — Observable + stable (23): MED/LOW audit punch-list + PTT/TCC.
- v0.5 — API M-0..M-3 (31): Self/Settings/Diagnostics surfaces; B-08.
- v0.8 — API M-4..M-7 (36): Memory/Vision/Voice/Turn; B-03/B-04/B-05/B-06.
- v1.0 — Shipping (13): commenting, doc reconciliation.
- v1.1 — Backlog (11): Orpheus, WhisperKit, Voice Log, presence.

ROADMAP-2026-05-12.md supersedes the build-phase ROADMAP.md from
2026-04-22 (kept for history; describes shipped phases). CLAUDE.md
gains a Roadmap section pointing to the new doc + milestones URL.

Also lands the 5 audit-2026-05-12 reports referenced by the roadmap
(bus-hud, mcp-agent, memory, vision, voice).
2026-05-12 14:52:25 -05:00
james.maesandClaude Opus 4.7 4f4a5581c1 docs(claude.md): declare GitHub Issues as canonical tracker
Adds a new "Issue tracking" section near the top declaring
github.com/KofTwentyTwo/Jarvis/issues as the canonical tracker for all
bugs, audit findings, and feature work going forward. docs/TODO.md is
retained for historical reference only.

Refs #4..#63 (migration epics + audit findings + carry-forward bugs
filed 2026-05-12).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-12 14:12:06 -05:00
james.maesandClaude Opus 4.7 f9cd25d66e chore(test-naming): converge on Mock/Fake/Stub convention; document in CLAUDE.md; rename worst-mismatch stragglers
Per audit-2026-05-04 P2-15: 26 Mock*, 21 Fake*, 12 Stub* across the test
corpus, often used interchangeably for the same role. New CLAUDE.md
section "Test naming conventions" (line 127) sets the rule:

- Mock*: records calls AND returns scripted responses (assertion driver).
- Stub*: returns canned data without recording (deterministic input).
- Fake*: alternative implementation with realistic behavior (in-memory
  state-holder).

Renamed 15 worst-mismatch stragglers in the older corpus (per audit
constraint, did NOT touch types added in today's P1+P2 fix commits):

Stub* → Mock* (records + scripts):
- HybridSearchTests:    StubEmbedder → MockEmbedder
- HybridSearchTests:    StubStore → MockStore
- SessionHistoryTests:  StubStore → MockStore
- InProcessMemoryToolsTests: StubHybrid → MockHybrid
- InProcessMemoryToolsTests: StubHistory → MockHistory
- InProcessMemoryToolsTests: StubForget → MockForget

Mock* → Stub* (canned data, no recording):
- STTBackendSwitchTests: MockSpeechAnalyzerBridge → StubSpeechAnalyzerBridge
- STTBackendSwitchTests: MockWhisperKitBridge → StubWhisperKitBridge
- VoiceWiringTests:      MockVADEngineForW4 → StubVADEngineForW4
- VoiceWiringTests:      MockSTTProviderForW4 → StubSTTProviderForW4
- VoiceWiringTests:      MockTTSForW4 → StubTTSForW4
- VoiceWiringTests:      MockOrchestratorForW4 → StubOrchestratorForW4
- VoiceWiringTests:      MockBannerForW4 → StubBannerForW4
- VoiceWiringTests:      MockBusForW4 → StubBusForW4

Fake* → Mock* (records + scripts):
- WebviewBridgeOutboundTests:        FakeJSEvaluator → MockJSEvaluator
- HudStateCoordinatorBusWiringTests: FakeJSEvaluator → MockJSEvaluator
  (the comment on the type already said "Records each call for assertion")

Skipped per audit constraint:
- StubCapture/StubSink (Vision FrameAttachConfirmSendWiringTests, P1+P2)
- MockVADEngine + MockOrchestratorForController siblings (Voice
  VoiceControllerTests/VADGatedSessionTests, today's track-B churn)

Tests pass: Voice 87+23, MCP 85, Memory 88, Bus 58, AgentCore 19+72,
Vision 19, Shell 7+5. App target builds clean.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-04 16:42:16 -05:00
james.maesandClaude Opus 4.7 26f5ae32ef docs(claude): correct CLAUDE.md lede + populate build/test commands
Two doc-rot sites flagged by 2026-05-04 documentation audit:

1. Lines 5-7 said "Pre-implementation. Planning complete; Phase 1 next."
   while the project is at v0.12.0 with Tracks A/B/C/D shipped. Replace
   with the actual state — post-v0.12.0 audit-and-stabilize, day-to-day
   handoff in `docs/SESSION-STATE.md` + `docs/TODO.md`, milestone state
   in `.planning/STATE.md`.

2. The Build/test commands section read "to be populated once scaffolded"
   even though the project has been building/testing all along. Populate
   with the actual commands:
   - per-package `swift test --package-path packages/<Pkg>` (the default
     fast loop) plus single-test filter syntax.
   - `scripts/check-app-builds.sh` for the App target (Xcode 26 xctest
     harness is upstream-broken on ad-hoc Debug bundles).
   - `scripts/build-webview.sh` + pnpm dev/test commands for the HUD.
   - All 17 boundary gates (`scripts/check-*.sh`) listed explicitly so
     they're discoverable from the entry-point doc.
   - Entitlement / codesign verifiers.
   - The three `JARVIS_REAL_*` env-flag interactive lanes (real Ollama,
     real camera, real Orpheus weights) — skipped by default, runnable
     interactively.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-04 15:25:35 -05:00
james.maes 995e960e8e chore: migrate pre-GSD source material to .planning/source-material/ and refresh top-level docs 2026-04-22 05:37:16 -05:00
james.maes 95fbf744af feat(initial-checkin): initial checkin 2026-04-21 20:28:34 -05:00