| 1 | # AutoResearch Runtime Verification Matrix |
| 2 | |
| 3 | Date: 2026-06-30 |
| 4 | |
| 5 | Scope: host-managed AutoResearch runtime, controller integration, desktop API, |
| 6 | frontend visibility, and focused end-to-end verification. |
| 7 | |
| 8 | ## Summary |
| 9 | |
| 10 | AutoResearch has moved from a prompt convention to a host-managed runtime for |
| 11 | the implemented scope. The host now creates and resumes task state under |
| 12 | `.reasonix/autoresearch/<task-id>/`, injects a runtime summary into active goal |
| 13 | turns, records heartbeats and stale progress, records accepted evidence from |
| 14 | structured assistant evidence blocks, gates completion through default required |
| 15 | criteria, and exposes desktop/frontend status APIs with compact tab metadata. |
| 16 | |
| 17 | The implementation is verified against the design requirements listed below. |
| 18 | The only residual limitation is that an external browser smoke test cannot call |
| 19 | the Wails `window.go` bridge directly; bridge behavior is covered by Go and |
| 20 | TypeScript tests, and the running Wails app was smoke-tested through `./dev`. |
| 21 | |
| 22 | ## Requirement Matrix |
| 23 | |
| 24 | | Requirement | Evidence | Status | |
| 25 | | --- | --- | --- | |
| 26 | | Host creates task id and directory layout | `internal/autoresearch.Store.CreateTask`; `TestCreateTaskCreatesHostOwnedLayoutAndInitialState` | Verified | |
| 27 | | State files are host-owned JSON/JSONL under `.reasonix/autoresearch/<task-id>/` | `task_spec.json`, `progress.json`, `directions_tried.json`, `findings.jsonl`, `iteration_log.jsonl`, `heartbeat.jsonl`; store tests and `./dev` smoke task directory | Verified | |
| 28 | | Schema validation rejects missing required fields | `ValidateTask`; `TestValidateTaskReportsSchemaErrors` | Verified | |
| 29 | | JSONL append rejects invalid entries | `AppendFinding`; `TestAppendFindingRejectsInvalidEntry` | Verified | |
| 30 | | Accepted findings satisfy readiness | `Readiness`; `TestAppendFindingRecordsAcceptedEvidenceForReadiness`, `TestRecordEvidenceLinksFindingToCriterionAndSatisfiesReadiness` | Verified | |
| 31 | | Direction repetition increments stale count and pivot threshold | `RecordDirection`; `TestRecordDirectionIncrementsStaleAndRequiresPivot` | Verified | |
| 32 | | Controller computes stale/pivot instead of relying on prompt | `recordAutoResearchTurnProgress`; `TestResearchGoalTurnUpdatesAutoResearchStaleProgress` | Verified | |
| 33 | | Per-task concurrent writes are serialized | `Store.lockTask`; `TestConcurrentDirectionWritesAreSerializedPerTask` | Verified | |
| 34 | | `/goal --research` creates task and persists `AutoResearchTaskID` | `SetGoalWithResearchMode`; `TestResearchGoalCreatesHostManagedAutoResearchTask` | Verified | |
| 35 | | Explicit `.reasonix/autoresearch/<task-id>/` resumes existing task | `ResumeFromGoalText`; `TestResumeFromGoalTextLoadsExplicitTaskPath` | Verified | |
| 36 | | Missing explicit task path blocks instead of silently creating a new task | `ensureAutoResearchTask`; `TestResearchGoalMissingExplicitTaskBlocksInsteadOfCreatingNewTask` | Verified | |
| 37 | | Cold resume restores running AutoResearch task id | `goalMachine.restoreRunningFromState`; `TestResumeRestoresRunningAutoResearchGoalFromSidecar` | Verified | |
| 38 | | Compose injects host-generated `<autoresearch-runtime>` | `Controller.Compose`; `TestResearchGoalCreatesHostManagedAutoResearchTask`, resume test | Verified | |
| 39 | | Heartbeats are written around turns | `appendAutoResearchHeartbeat`; `TestResearchGoalTurnAppendsAutoResearchHeartbeats`; `./dev` smoke heartbeat log | Verified | |
| 40 | | Summary includes last heartbeat | `Summary`; `TestAppendHeartbeatRecordsDurableTurnStatus` | Verified | |
| 41 | | Completion is intercepted when readiness fails | `autoResearchReadinessFailure`; `TestResearchGoalCompletionIsInterceptedWhenReadinessFails` | Verified | |
| 42 | | Completion requires host-readable evidence for default criteria | `defaultAutoResearchSuccessCriteria`; `TestResearchGoalCreatesHostManagedAutoResearchTask`, `TestResearchGoalCompletionMarksAutoResearchTaskComplete` | Verified | |
| 43 | | Completion/blocked goal updates AutoResearch status | `finalizeAutoResearchTask`; `TestResearchGoalCompletionMarksAutoResearchTaskComplete`, `TestResearchGoalBlockedMarksAutoResearchTaskBlocked` | Verified | |
| 44 | | Host controller records structured evidence | `RecordAutoResearchEvidence`; `TestControllerRecordsAutoResearchEvidence` | Verified | |
| 45 | | Assistant replies can record structured evidence without changing tool schemas | `<autoresearch-evidence>` parser; `TestResearchGoalCompletionMarksAutoResearchTaskComplete` | Verified | |
| 46 | | AutoResearch evidence recording does not alter the default provider-visible tool surface | `TestAutoResearchEvidenceDoesNotChangeDefaultToolSurface`; boot tool contract tests | Verified | |
| 47 | | Desktop API exposes current/status/list/findings/open/record evidence | `desktop/app.go`; `TestAutoResearchStatusSurfaceForActiveTab`, `TestAutoResearchFindingsAreLoadedOnDemand`, `TestAutoResearchListReturnsWorkspaceTasks`, `TestAutoResearchOpenTaskRevealsTaskDirectory`, `TestAutoResearchRecordEvidenceThroughDesktopAPI` | Verified | |
| 48 | | Tab metadata includes compact summary only | `compactAutoResearch`; `TestAutoResearchStatusSurfaceForActiveTab` | Verified | |
| 49 | | Findings load on demand and cap by limit | `AutoResearchFindings`; `TestAutoResearchFindingsAreLoadedOnDemand` | Verified | |
| 50 | | AutoResearch does not appear as a configurable default status bar item | `statusbar-workspace.test.tsx` | Verified | |
| 51 | | Frontend bridge tolerates transient Wails IPC timing errors | `bridge-drag-rejection.test.ts` | Verified | |
| 52 | | Transcript lifecycle cards exist | Controller emits `event.Notice`; frontend renders notices via `NoticeCard`; `./dev` smoke shows `autoresearch task created` notice | Verified | |
| 53 | | `./dev` starts and AutoResearch creates durable state | Browser smoke against `http://127.0.0.1:34193`; task `20260630-065721-e2e-verify-autoresearch-ui-smoke-test` created | Verified | |
| 54 | |
| 55 | ## Commands Run |
| 56 | |
| 57 | ```bash |
| 58 | GOCACHE=/private/tmp/reasonix-go-build-cache go test ./internal/autoresearch ./internal/control -count=1 |
| 59 | GOCACHE=/private/tmp/reasonix-go-build-cache go test . -run 'TestAutoResearch|TestMetaReportsGoalStatus' -count=1 |
| 60 | GOCACHE=/private/tmp/reasonix-go-build-cache go test . -count=1 |
| 61 | ./node_modules/.bin/tsc --noEmit -p tsconfig.test.json |
| 62 | ./node_modules/.bin/tsx src/__tests__/statusbar-workspace.test.tsx |
| 63 | pnpm test |
| 64 | ./dev |
| 65 | ``` |
| 66 | |
| 67 | `tsx` tests required running outside the sandbox because `tsx` creates IPC pipes |
| 68 | under `/var/folders`. |
| 69 | |
| 70 | ## End-to-End Smoke Notes |
| 71 | |
| 72 | - `./dev` started successfully. |
| 73 | - Wails devserver: `http://127.0.0.1:34193`. |
| 74 | - External browser loaded the page with title `Reasonix`. |
| 75 | - Browser console had no error/warn entries. |
| 76 | - Submitted `/goal --research e2e verify autoresearch ui smoke test`. |
| 77 | - The transcript rendered `autoresearch task created: |
| 78 | 20260630-065721-e2e-verify-autoresearch-ui-smoke-test`. |
| 79 | - Host state files were created under `.reasonix/autoresearch/...`. |
| 80 | - Cancelling the smoke goal wrote heartbeat warning `context canceled`. |
| 81 | - Known Wails dev terminal noise remains: `runtime:ready -> Unknown message from |
| 82 | front end: runtime:ready`. |
| 83 | |
| 84 | ## Remaining Risk |
| 85 | |
| 86 | - The external browser smoke test cannot directly call Wails `window.go`; bridge |
| 87 | behavior is covered by Go/TS tests and the running Wails desktop app, but not |
| 88 | by direct browser-side method calls. |
| 89 | - The implementation intentionally avoids background daemon behavior; AutoResearch |
| 90 | advances only during normal Goal turns. |
| 91 |