forge-openclaw-plugin 0.2.26 → 0.2.28

package/server/migrations/042_movement_boxes.sql

@@ -0,0 +1,47 @@
+CREATE TABLE IF NOT EXISTS movement_boxes (
+  id TEXT PRIMARY KEY,
+  user_id TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN ('stay', 'trip', 'missing')),
+  source_kind TEXT NOT NULL CHECK (source_kind IN ('automatic', 'user_defined')),
+  origin TEXT NOT NULL CHECK (
+    origin IN (
+      'recorded',
+      'continued_stay',
+      'repaired_gap',
+      'missing',
+      'user_defined',
+      'user_invalidated'
+    )
+  ),
+  started_at TEXT NOT NULL,
+  ended_at TEXT NOT NULL,
+  title TEXT NOT NULL DEFAULT '',
+  subtitle TEXT NOT NULL DEFAULT '',
+  place_label TEXT,
+  anchor_external_uid TEXT,
+  tags_json TEXT NOT NULL DEFAULT '[]',
+  distance_meters REAL,
+  average_speed_mps REAL,
+  editable INTEGER NOT NULL DEFAULT 0,
+  override_count INTEGER NOT NULL DEFAULT 0,
+  overridden_automatic_box_ids_json TEXT NOT NULL DEFAULT '[]',
+  raw_stay_ids_json TEXT NOT NULL DEFAULT '[]',
+  raw_trip_ids_json TEXT NOT NULL DEFAULT '[]',
+  raw_point_count INTEGER NOT NULL DEFAULT 0,
+  has_legacy_corrections INTEGER NOT NULL DEFAULT 0,
+  legacy_origin_key TEXT,
+  metadata_json TEXT NOT NULL DEFAULT '{}',
+  deleted_at TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_movement_boxes_user_time
+ON movement_boxes(user_id, started_at, ended_at);
+
+CREATE INDEX IF NOT EXISTS idx_movement_boxes_user_source
+ON movement_boxes(user_id, source_kind, deleted_at, started_at);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_movement_boxes_legacy_origin
+ON movement_boxes(user_id, legacy_origin_key)
+WHERE legacy_origin_key IS NOT NULL;

package/server/migrations/043_movement_box_overlap_overrides.sql

@@ -0,0 +1,26 @@
+ALTER TABLE movement_boxes
+ADD COLUMN true_started_at TEXT;
+
+ALTER TABLE movement_boxes
+ADD COLUMN true_ended_at TEXT;
+
+ALTER TABLE movement_boxes
+ADD COLUMN overridden_started_at TEXT;
+
+ALTER TABLE movement_boxes
+ADD COLUMN overridden_ended_at TEXT;
+
+ALTER TABLE movement_boxes
+ADD COLUMN overridden_by_box_id TEXT;
+
+ALTER TABLE movement_boxes
+ADD COLUMN overridden_user_box_ids_json TEXT NOT NULL DEFAULT '[]';
+
+ALTER TABLE movement_boxes
+ADD COLUMN override_ranges_json TEXT NOT NULL DEFAULT '[]';
+
+ALTER TABLE movement_boxes
+ADD COLUMN is_overridden INTEGER NOT NULL DEFAULT 0;
+
+ALTER TABLE movement_boxes
+ADD COLUMN is_fully_hidden INTEGER NOT NULL DEFAULT 0;

package/skills/forge-openclaw/SKILL.md

@@ -41,8 +41,9 @@ Wiki navigation and search rule:
 Health rule:
 
 - Sleep and sports records are first-class health surfaces, not generic notes or tasks.
-- Use `forge_get_sleep_overview` and `forge_get_sports_overview` for review.
-- Use `forge_update_sleep_session` and `forge_update_workout_session` when the user wants to attach reflective context, tags, or Forge links to an existing health record.
+- Use `forge_get_sleep_overview` and `forge_get_sports_overview` for review and trend reading.
+- Use the shared batch entity tools for ordinary `sleep_session` and `workout_session` create, update, delete, and search work. Do not force agents into a large one-route-per-entity mental model when the batch routes already cover the record cleanly.
+- Use `forge_update_sleep_session` and `forge_update_workout_session` only when the job is reflective enrichment on one existing health record after review, such as attaching notes, tags, mood, meaning, or Forge links.
 - Habit-generated workouts and imported HealthKit workouts belong to the same workout record model, so do not invent a separate storage path for sport sessions.
 
 Write to Forge only with clear user consent. If the user is just thinking aloud, helping first is usually better than writing immediately. After helping, you may offer one short Forge prompt if the match is strong. If the user agrees, ask only for the missing fields and only one to three focused questions at a time. Do not offer Forge again after a decline unless the user reopens it.
@@ -55,6 +56,7 @@ Entity conversation rule:
 - Before you ask, decide the exact missing thing you need and how that answer will help you name, place, or save the record.
 - Prefer a progression of:
   concrete example or intent -> working name -> purpose or meaning -> placement in Forge -> operational details -> linked context.
+- Use those same playbooks for action-heavy non-Psyche flows such as `work_adjustment`, `preference_judgment`, `preference_signal`, and specialized `movement`, `life_force`, or `workbench` requests so the conversation starts from what the user is trying to understand, change, add, update, link, or run before you choose the route.
 - For emotionally meaningful non-Psyche records such as goals, habits, and notes, reflect the meaning before you ask for structure.
 - When the user is vague, ask for one small concrete example, stake, or desired outcome before you ask them to name the record.
 - When the user is clear, say what the record seems to be becoming and ask only for the last missing detail.
@@ -64,9 +66,9 @@ Entity conversation rule:
 
 Forge data location rule:
 
-- by default, Forge stores data under the active runtime root at `data/forge.sqlite`
-- on a normal OpenClaw install, this usually means `~/.openclaw/extensions/forge-openclaw-plugin/data/forge.sqlite`
-- on a linked repo-local install, this usually means `<repo>/openclaw-plugin/data/forge.sqlite`
+- by default, Forge stores data under the active runtime root at `forge.sqlite`
+- on a normal OpenClaw install, this usually means `~/.openclaw/extensions/forge-openclaw-plugin/forge.sqlite`
+- on a linked repo-local install, this usually means `<repo>/openclaw-plugin/forge.sqlite`
 - if the user wants the data somewhere else for persistence, backup, or manual control, tell them to set `plugins.entries["forge-openclaw-plugin"].config.dataRoot` and restart the OpenClaw gateway
 - if the user asks where the data is stored or how to move it, explain the current default plainly and show the exact config field
 
@@ -282,17 +284,33 @@ Use the batch entity tools for stored records:
 `forge_search_entities`, `forge_create_entities`, `forge_update_entities`, `forge_delete_entities`, `forge_restore_entities`
 
 These tools operate on:
-`goal`, `project`, `task`, `habit`, `note`, `calendar_event`, `work_block_template`, `task_timebox`, `psyche_value`, `behavior_pattern`, `behavior`, `belief_entry`, `mode_profile`, `mode_guide_session`, `trigger_report`, `event_type`, `emotion_definition`
+`goal`, `project`, `strategy`, `task`, `habit`, `tag`, `note`, `insight`, `calendar_event`, `work_block_template`, `task_timebox`, `psyche_value`, `behavior_pattern`, `behavior`, `belief_entry`, `mode_profile`, `mode_guide_session`, `trigger_report`, `event_type`, `emotion_definition`, `preference_catalog`, `preference_catalog_item`, `preference_context`, `preference_item`, `questionnaire_instrument`, `sleep_session`, `workout_session`
 
 Use the wiki tools for file-first memory work:
 `forge_get_wiki_settings`, `forge_list_wiki_pages`, `forge_get_wiki_page`, `forge_search_wiki`, `forge_upsert_wiki_page`, `forge_get_wiki_health`, `forge_sync_wiki_vault`, `forge_reindex_wiki_embeddings`, `forge_ingest_wiki_source`
 
-Sleep and workout sessions are not batch entities. Use the health tools instead:
+Use the health tools for review and reflective enrichment, not as the default CRUD architecture:
 `forge_get_sleep_overview`, `forge_get_sports_overview`, `forge_update_sleep_session`, `forge_update_workout_session`
 
+Use the dedicated domain routes for specialized surfaces that are not simple batch entities:
+
+- Movement lives under `/api/v1/movement/*`. Treat it as a dedicated timeline of `stays` and `trips`, not as generic batch CRUD. A `stay` means the user remained in the same place for a span of time. A `trip` means the user traveled between places. Use the movement routes when the user wants to understand time in place, travel behavior, specific stays or trips, known places, or selected-span aggregates such as "how long was I at home in the past 2 weeks?" or "when did I travel last month?".
+- Movement user actions are: query movement behavior, add a place or manual stay/trip overlay, update an existing stay/trip/place, or link a specific movement item to another Forge entity. Keep the explanation user-facing: where they stayed, when they traveled, what changed, and what this movement should be linked to.
+- When the user is filling a missing-data gap, the default write path is a user-defined overlay box, not a raw stay or trip patch. Use `POST /api/v1/movement/user-boxes/preflight` if you need to confirm overlap or snap to the nearest missing interval, then `POST /api/v1/movement/user-boxes` with `kind: "stay"` or `kind: "trip"`.
+- Use `PATCH /api/v1/movement/stays/:id` or `PATCH /api/v1/movement/trips/:id` only when the user is editing an existing recorded stay or recorded trip. Do not use those routes to fill a missing span.
+- If the user says something as explicit as "that missing block was me staying home", do not reopen broad intake. Confirm the interval or place only if it is still ambiguous, then create the overlay and read the timeline back.
+- Life Force lives under `/api/v1/life-force*`. Use `GET /api/v1/life-force` for the current energy overview, `PATCH /api/v1/life-force/profile` for durable profile changes, `PUT /api/v1/life-force/templates/:weekday` for weekday curve edits, and `POST /api/v1/life-force/fatigue-signals` for real-time tired or recovered signals.
+- Workbench lives under `/api/v1/workbench/*`. Use those dedicated routes for flow catalog reads, flow CRUD, runs, published outputs, node results, and latest-node-output reads instead of trying to force Workbench through the batch entity routes.
+- If you are unsure which specialized route family applies, check `forge_get_agent_onboarding` and use its `entityRouteModel.specializedDomainSurfaces` section before guessing.
+
 Use live work tools for `task_run`:
 `forge_log_work`, `forge_start_task_run`, `forge_heartbeat_task_run`, `forge_focus_task_run`, `forge_complete_task_run`, `forge_release_task_run`
 
+Use `forge_adjust_work_minutes` for `work_adjustment` when the user wants a truthful signed minute correction on an existing task or project rather than a fake live run or a retroactive new task.
+
+Use the dedicated Preferences action tools for `preference_judgment` and `preference_signal`:
+`forge_submit_preferences_judgment`, `forge_submit_preferences_signal`, `forge_update_preferences_score`
+
 Use `forge_post_insight` for `insight`.
 Use the calendar tools for provider sync and planning:
 `forge_get_calendar_overview`, `forge_connect_calendar_provider`, `forge_sync_calendar_connection`, `forge_create_work_block_template`, `forge_recommend_task_timeboxes`, `forge_create_task_timebox`
@@ -343,7 +361,7 @@ For project deletion and recovery, prefer the generic delete and restore tools:
 
 For restore operations, each item must include `entityType` and `id`.
 
-Batch tools do not create or control `task_run` or `insight`.
+Batch tools do not create or control `task_run`.
 
 Use the exact route-facing field names. Do not invent friendlier aliases. If a field name is unclear, use `forge_get_agent_onboarding` as the schema source of truth.
 
@@ -376,10 +394,21 @@ Use the health tools when the request is about sleep or sports review:
 
 - `forge_get_sleep_overview` to inspect recent nights, averages, regularity, stage breakdown, and linked reflective context
 - `forge_get_sports_overview` to inspect training volume, workout types, effort trends, habit-generated sessions, and linked context
-- `forge_update_sleep_session` to add sleep-quality notes, tags, or links back to Forge entities
-- `forge_update_workout_session` to add subjective effort, mood, meaning, tags, or links on one workout
+- `forge_update_sleep_session` to add sleep-quality notes, tags, or links back to Forge entities after review
+- `forge_update_workout_session` to add subjective effort, mood, meaning, tags, or links on one workout after review
 - remember that the UI route is `/sports` while the backend overview route is `/api/v1/health/fitness`
 
+Use these exact health batch payload shapes when the user is creating or editing the stored records themselves:
+
+- create a manual sleep session:
+  `{"operations":[{"entityType":"sleep_session","data":{"startedAt":"2026-04-10T22:45:00.000Z","endedAt":"2026-04-11T06:45:00.000Z","qualitySummary":"Slept cleanly after a light evening.","links":[{"entityType":"habit","entityId":"habit_sleep_hygiene","relationshipType":"supports"}]}}]}`
+- update a sleep session through batch CRUD:
+  `{"operations":[{"entityType":"sleep_session","id":"sleep_123","patch":{"notes":"Woke once around 03:00 but settled quickly.","tags":["travel","recovered"]}}]}`
+- create a manual workout session:
+  `{"operations":[{"entityType":"workout_session","data":{"workoutType":"walk","startedAt":"2026-04-11T10:00:00.000Z","endedAt":"2026-04-11T10:45:00.000Z","subjectiveEffort":6,"meaningText":"Reset after a long planning block.","links":[{"entityType":"task","entityId":"task_123","relationshipType":"supports"}]}}]}`
+- update a workout session through batch CRUD:
+  `{"operations":[{"entityType":"workout_session","id":"workout_123","patch":{"moodAfter":"clear","tags":["zone2"]}}]}`
+
 Work-block payload guidance:
 
 - `kind` must be one of `main_activity`, `secondary_activity`, `third_activity`, `rest`, `holiday`, or `custom`
@@ -476,7 +505,8 @@ Additional first-class surfaces:
 
 - Use the high-level batch routes for basic Preferences CRUD. `preference_catalog`, `preference_catalog_item`, `preference_context`, and `preference_item` all go through `forge_create_entities`, `forge_update_entities`, and `forge_delete_entities`.
 - Use the high-level batch routes for basic questionnaire CRUD too. `questionnaire_instrument` goes through `forge_create_entities`, `forge_update_entities`, and `forge_delete_entities`.
+- Use the high-level batch routes for ordinary health-session CRUD too. `sleep_session` and `workout_session` go through `forge_search_entities`, `forge_create_entities`, `forge_update_entities`, and `forge_delete_entities` by default. Keep the dedicated health tools for review surfaces and reflective enrichment on one record.
 - Keep the dedicated Preferences tools only for real preference actions and read models: `forge_get_preferences_workspace`, `forge_start_preferences_game`, `forge_merge_preferences_contexts`, `forge_enqueue_preferences_item_from_entity`, `forge_submit_preferences_judgment`, `forge_submit_preferences_signal`, and `forge_update_preferences_score`.
 - Keep the dedicated questionnaire tools only for real flow actions and read models: `forge_list_questionnaires`, `forge_get_questionnaire`, `forge_clone_questionnaire`, `forge_ensure_questionnaire_draft`, `forge_publish_questionnaire_draft`, `forge_start_questionnaire_run`, `forge_get_questionnaire_run`, `forge_update_questionnaire_run`, and `forge_complete_questionnaire_run`.
 - Self-observation is note-backed. Read the calendar through `forge_get_self_observation_calendar`, but create or update the stored observation as a `note` tagged `Self-observation` with `frontmatter.observedAt` and links to the relevant `behavior_pattern`, `trigger_report`, or other Forge records.
-- `sleep_session` and `workout_session` are first-class health records. Review them through the dedicated health tools instead of treating them like loose notes.
+- `sleep_session` and `workout_session` are first-class health records. Treat them like ordinary stored entities for CRUD, and use the dedicated health tools for read models or post-review enrichment rather than pretending they live on a special mutation island.