|
| 1 | +--- |
| 2 | +phase: 260508-b8m |
| 3 | +plan: 01 |
| 4 | +subsystem: docs |
| 5 | +tags: [claude-md, tag-api, fastsensecompanion, matlab-mcp] |
| 6 | +type: quick |
| 7 | +dependency_graph: |
| 8 | + requires: [] |
| 9 | + provides: |
| 10 | + - CLAUDE.md (refreshed project instructions matching on-disk reality) |
| 11 | + - "## Running MATLAB code" guidance for matlab MCP tools |
| 12 | + affects: |
| 13 | + - CLAUDE.md |
| 14 | +tech_stack: |
| 15 | + added: [] |
| 16 | + patterns: |
| 17 | + - GSD-style HTML comment markers for new manually-managed CLAUDE.md sections |
| 18 | +key_files: |
| 19 | + created: [] |
| 20 | + modified: |
| 21 | + - CLAUDE.md |
| 22 | +decisions: |
| 23 | + - Use GSD-style markers (`<!-- GSD:matlab-mcp-start -->` / `-end -->`) for the new MATLAB MCP section so future regenerators preserve it. |
| 24 | + - Updated `Public API` example to actual FastSense methods (`addLine/addTag/addThreshold/addBand/render/updateData`) — `addSensor` no longer exists. |
| 25 | + - Updated suite-test naming example to current files (`TestTag`, `TestMonitorTag`, `TestTagRegistry`, `TestDashboardEngine`); `TestSensor.m` and `TestEventDetector.m` are gone. |
| 26 | + - Updated function-test naming example to current files (`test_add_line`, `test_add_threshold`, `test_companion_filter_tags`); `test_sensor.m` / `test_add_sensor.m` were never created or have been removed. |
| 27 | +metrics: |
| 28 | + duration_seconds: 209 |
| 29 | + completed_date: "2026-05-08" |
| 30 | + tasks_completed: 2 |
| 31 | + files_modified: 1 |
| 32 | +--- |
| 33 | + |
| 34 | +# Phase 260508-b8m Plan 01: Refresh CLAUDE.md for Tag-Based API and Add MATLAB MCP Guidance Summary |
| 35 | + |
| 36 | +CLAUDE.md is now in sync with on-disk reality: every class name in Architecture / Layers / Key Abstractions / Entry Points was verified against `ls libs/`, the `FastSenseCompanion` library is documented as the sixth layer, and a new "## Running MATLAB code" section instructs the assistant to use the matlab MCP server tools instead of asking the user to run code manually. |
| 37 | + |
| 38 | +## What Changed |
| 39 | + |
| 40 | +### Architecture block (between `<!-- GSD:architecture-start -->` and `<!-- GSD:architecture-end -->`) |
| 41 | + |
| 42 | +- **Pattern Overview**: "Five independent libraries" → "Six independent libraries" with the actual list (FastSense, SensorThreshold, EventDetection, Dashboard, FastSenseCompanion, WebBridge). Added a bullet describing the FastSenseCompanion role. |
| 43 | +- **FastSense layer**: expanded `Contains` to enumerate every top-level `.m` actually present (`FastSenseTheme.m`, `FastSenseDefaults.m`, `FastSenseDataStore.m`, `ConsoleProgressBar.m`, `binary_search.m`, `build_mex.m`, `mex_stamp.m` were missing). Added FastSenseCompanion to `Used by`. |
| 44 | +- **SensorThreshold layer**: replaced the entire stale class list (`Sensor.m`, `SensorRegistry.m`, `ThresholdRule.m`, `StateChannel.m`, `loadModuleData.m`, `loadModuleMetadata.m`, `ExternalSensorRegistry.m`) with the Tag-based classes that actually exist: `Tag.m` (abstract), `SensorTag.m`, `MonitorTag.m`, `CompositeTag.m`, `DerivedTag.m`, `StateTag.m`, `TagRegistry.m`, `BatchTagPipeline.m`, `LiveTagPipeline.m`, `readRawDelimitedForTest_.m`. Updated Purpose to match the Tag model. Updated `Used by` to use `FastSense.addTag()` and to add FastSenseCompanion. |
| 45 | +- **EventDetection layer**: removed deleted classes (`EventDetector.m`, `IncrementalEventDetector.m`, `EventConfig.m`, `detectEventsFromSensor.m`). Listed the actual files including the newer `EventBinding.m`, `eventLogger.m`, `printEventSummary.m`. Updated `Depends on` to reference `MonitorTag` rather than `Sensor`/`ThresholdRule`. |
| 46 | +- **Dashboard layer**: enumerated every widget/file present, including the previously missing `ChipBarWidget`, `DashboardConfigDialog`, `DashboardPage`, `DashboardProgress`, `DetachedMirror`, `DividerWidget`, `IconCardWidget`, `SparklineCardWidget`, `TimeRangeSelector`. Added FastSenseCompanion to `Used by`. |
| 47 | +- **FastSenseCompanion layer (NEW)**: full new entry with purpose, location, contents (`FastSenseCompanion.m`, `TagCatalogPane.m`, `DashboardListPane.m`, `InspectorPane.m`, `CompanionTheme.m`, `CompanionSettingsDialog.m`, `companionPrefs.m`, the three `*EventData.m` classes, `runFilterTagsTests.m`, plus `private/`), dependencies (`SensorThreshold/TagRegistry`, `Dashboard/DashboardEngine`, `FastSense/SensorDetailPlot+FastSenseGrid`), and consumers. |
| 48 | +- **WebBridge layer**: unchanged — its on-disk file list matched the existing text. |
| 49 | +- **Data Flow**: `SensorRegistry is a persistent singleton` → `TagRegistry is a persistent singleton`. Added a bullet describing FastSenseCompanion's selection state and event-based pane communication. |
| 50 | +- **Key Abstractions**: replaced `SensorRegistry` example with `TagRegistry`. Added a new `Tag (abstract)` abstraction listing the five concrete subclasses. Expanded the FastSense `add*()` example with the actual method set. |
| 51 | +- **Entry Points**: rewrote the `LiveEventPipeline` description (it no longer uses `IncrementalEventDetector`; it now polls `DataSourceMap` and runs `processMonitorTag_`). Added a new `FastSenseCompanion` entry point describing the constructor, three-pane wiring, event names, and live-refresh delegation. |
| 52 | +- **Error Handling**: replaced the stale namespaced-error example (`'SensorRegistry:unknownKey'`, `'EventDetector:unknownOption'`) with current ones (`'FastSense:alreadyRendered'`, `'MonitorTag:unknownOption'`, `'FastSenseCompanion:invalidEventData'`) — all three were verified to exist via `grep`. Added a bullet about FastSenseCompanion's try/catch + `uialert` callback wrapping. |
| 53 | + |
| 54 | +### Conventions block — small targeted fixes (within preserved markers) |
| 55 | + |
| 56 | +- `Classes:` example: `EventDetector.m` → `MonitorTag.m`, `FastSenseCompanion.m`. |
| 57 | +- `Test files (suite):` example: `TestSensor.m`, `TestEventDetector.m` → `TestTag.m`, `TestMonitorTag.m`, `TestTagRegistry.m`, `TestDashboardEngine.m` (all verified via `ls tests/suite/`). |
| 58 | +- `Test files (Octave function-based):` example: `test_sensor.m`, `test_add_sensor.m` → `test_add_line.m`, `test_add_threshold.m`, `test_companion_filter_tags.m` (verified via `ls tests/`). |
| 59 | +- `Public API:` example: `addSensor(), addThreshold(), addLine(), render()` → `addLine(), addTag(), addThreshold(), addBand(), render(), updateData()` (verified by grepping `function .* = ?add*` on `libs/FastSense/FastSense.m`). |
| 60 | +- `Pattern: ClassName:camelCaseProblem` example: `Sensor:unknownOption, EventDetector:unknownOption` → `MonitorTag:unknownOption, FastSenseCompanion:invalidEventData`. |
| 61 | + |
| 62 | +### New "## Running MATLAB code" section |
| 63 | + |
| 64 | +Added between `<!-- GSD:architecture-end -->` and `<!-- GSD:workflow-start -->`, wrapped in `<!-- GSD:matlab-mcp-start -->` / `<!-- GSD:matlab-mcp-end -->`. Contents: |
| 65 | + |
| 66 | +- Names all five matlab MCP tools (`mcp__matlab__check_matlab_code`, `mcp__matlab__evaluate_matlab_code`, `mcp__matlab__run_matlab_file`, `mcp__matlab__run_matlab_test_file`, `mcp__matlab__detect_matlab_toolboxes`) with one-line purposes. |
| 67 | +- States that a live MATLAB session is already running on the user's machine and figures appear in the MATLAB UI which is visible to the user — so don't dump base64 PNGs back to chat unsolicited. |
| 68 | +- Repo conventions: toolbox-free; run `install` if `which FastSense` is empty; prefer single test files over the full suite. |
| 69 | +- Safety: don't run untrusted code that alters filesystem / env / preferences without explicit user consent; avoid `clear all` / `clear classes`; explicit consent required for `delete`, `rmdir`, `setpref`, `system()` / `!`. |
| 70 | + |
| 71 | +### Sections preserved verbatim |
| 72 | + |
| 73 | +`<!-- GSD:project-start -->...<!-- GSD:project-end -->`, `<!-- GSD:stack-start -->...<!-- GSD:stack-end -->`, `<!-- GSD:workflow-start -->...<!-- GSD:workflow-end -->`, `<!-- GSD:profile-start -->...<!-- GSD:profile-end -->` were not modified. The Conventions block kept its markers and structure; only the example-name bullets called out in the plan were changed. |
| 74 | + |
| 75 | +## Deviations from Plan |
| 76 | + |
| 77 | +### Auto-fixed issues |
| 78 | + |
| 79 | +**1. [Rule 1 — staleness] Updated suite-test and function-test naming examples** |
| 80 | + |
| 81 | +- **Found during:** Task 1 (post-`ls tests/suite/` and `ls tests/`). |
| 82 | +- **Issue:** The plan said to leave the `Test files (suite)` example alone "unless an `ls tests/suite/` shows clear renames". The audit-time list showed `TestSensor.m`, `TestEventDetector.m` — neither exists. Today's `tests/suite/` contains `TestTag.m`, `TestMonitorTag.m`, `TestTagRegistry.m`, etc. Same for the function-based test example (`test_sensor.m`, `test_add_sensor.m` — neither exists; current files include `test_add_line.m`, `test_add_threshold.m`, `test_companion_filter_tags.m`). |
| 83 | +- **Fix:** Updated both example bullets to current file names so future Claude sessions don't try to open non-existent test files. |
| 84 | +- **Files modified:** CLAUDE.md (Conventions block). |
| 85 | +- **Commit:** 8c6a0c4 (rolled into Task 1). |
| 86 | + |
| 87 | +### Deviations from `verified_on_disk_state` snapshot |
| 88 | + |
| 89 | +The audit memo's snapshot of libs/ was accurate. The only differences I found while re-listing on disk: |
| 90 | + |
| 91 | +- **libs/FastSense/** contains additional files not enumerated in the snapshot (irrelevant — the snapshot focused on the migrated libraries): `ConsoleProgressBar.m`, `FastSenseDefaults.m`, `FastSenseTheme.m`, `binary_search.m`, `build_mex.m`, `mex_stamp.m`. These were already in the previous CLAUDE.md text or are infrastructure files and were folded into the new `Contains:` list. |
| 92 | +- **libs/EventDetection/** matches the snapshot exactly (no `EventDetector`, no `IncrementalEventDetector`, no `EventConfig`, no `detectEventsFromSensor`; current files include the newer `EventBinding.m`, `eventLogger.m`, `printEventSummary.m`). |
| 93 | +- **libs/SensorThreshold/** matches the snapshot exactly. |
| 94 | +- **libs/FastSenseCompanion/** matches the snapshot exactly (all eleven files plus `private/` were present). |
| 95 | +- **libs/Dashboard/** matches the snapshot exactly — the nine "additions vs current CLAUDE.md" widgets all exist on disk. |
| 96 | + |
| 97 | +No surprises; no architectural escalation needed. |
| 98 | + |
| 99 | +## Authentication Gates |
| 100 | + |
| 101 | +None. |
| 102 | + |
| 103 | +## Verification Results |
| 104 | + |
| 105 | +``` |
| 106 | +$ grep -c "SensorRegistry|ThresholdRule|EventDetector|IncrementalEventDetector|EventConfig|detectEventsFromSensor|StateChannel|ExternalSensorRegistry" CLAUDE.md |
| 107 | +0 |
| 108 | +
|
| 109 | +$ grep -c "TagRegistry|MonitorTag|FastSenseCompanion" CLAUDE.md |
| 110 | +24 |
| 111 | +
|
| 112 | +$ grep -c "GSD:project-start|GSD:project-end|GSD:stack-start|GSD:stack-end|GSD:conventions-start|GSD:conventions-end|GSD:architecture-start|GSD:architecture-end|GSD:matlab-mcp-start|GSD:matlab-mcp-end|GSD:workflow-start|GSD:workflow-end|GSD:profile-start|GSD:profile-end" CLAUDE.md |
| 113 | +14 |
| 114 | +
|
| 115 | +$ grep -c "^## Running MATLAB code$" CLAUDE.md |
| 116 | +1 |
| 117 | +
|
| 118 | +$ grep -c "mcp__matlab__check_matlab_code|mcp__matlab__evaluate_matlab_code|mcp__matlab__run_matlab_file|mcp__matlab__run_matlab_test_file|mcp__matlab__detect_matlab_toolboxes" CLAUDE.md |
| 119 | +8 |
| 120 | +
|
| 121 | +# Section ordering |
| 122 | +ORDER_OK (architecture-end < matlab-mcp-start < workflow-start) |
| 123 | +
|
| 124 | +# HTML comment balance |
| 125 | +BALANCED |
| 126 | +``` |
| 127 | + |
| 128 | +All success criteria from the plan satisfied. |
| 129 | + |
| 130 | +## Self-Check: PASSED |
| 131 | + |
| 132 | +- **CLAUDE.md** — verified present and modified (`git log --oneline -3` shows commits 8c6a0c4 and 90d9c03). |
| 133 | +- **Commit 8c6a0c4** — `docs(260508-b8m-01): refresh CLAUDE.md architecture for Tag-based API` — found in `git log`. |
| 134 | +- **Commit 90d9c03** — `docs(260508-b8m-02): add Running MATLAB code section to CLAUDE.md` — found in `git log`. |
| 135 | +- All grep verification commands above return the expected values. |
| 136 | +- No stale class names remain. All preserved GSD markers still bracketed correctly. The new MATLAB MCP section is correctly positioned between architecture and workflow blocks. |
0 commit comments