forge-openclaw-plugin 0.2.13 → 0.2.18

package/dist/server/repositories/habits.js

@@ -0,0 +1,358 @@
+import { randomUUID } from "node:crypto";
+import { getDatabase, runInTransaction } from "../db.js";
+import { HttpError } from "../errors.js";
+import { getGoalById } from "./goals.js";
+import { getProjectById } from "./projects.js";
+import { getBehaviorById, getBehaviorPatternById, getBeliefEntryById, getModeProfileById, getPsycheValueById, getTriggerReportById } from "./psyche.js";
+import { getTaskById } from "./tasks.js";
+import { recordActivityEvent } from "./activity-events.js";
+import { recordHabitCheckInReward } from "./rewards.js";
+import { createHabitCheckInSchema, createHabitSchema, habitCheckInSchema, habitSchema, updateHabitSchema } from "../types.js";
+function todayKey(now = new Date()) {
+    return now.toISOString().slice(0, 10);
+}
+function parseWeekDays(raw) {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((value) => Number.isInteger(value) && value >= 0 && value <= 6) : [];
+}
+function parseIdList(raw) {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((value) => typeof value === "string" && value.trim().length > 0) : [];
+}
+function uniqueIds(values) {
+    return [...new Set(values.filter((value) => typeof value === "string" && value.trim().length > 0))];
+}
+function normalizeLinkedBehaviorIds(input) {
+    const fromArray = Array.isArray(input.linkedBehaviorIds) ? input.linkedBehaviorIds : [];
+    return uniqueIds([...fromArray, input.linkedBehaviorId ?? null]);
+}
+function validateExistingIds(ids, getById, code, label) {
+    for (const id of ids) {
+        if (!getById(id)) {
+            throw new HttpError(404, code, `${label} ${id} does not exist`);
+        }
+    }
+}
+function mapCheckIn(row) {
+    return habitCheckInSchema.parse({
+        id: row.id,
+        habitId: row.habit_id,
+        dateKey: row.date_key,
+        status: row.status,
+        note: row.note,
+        deltaXp: row.delta_xp,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at
+    });
+}
+function listCheckInsForHabit(habitId, limit = 14) {
+    const rows = getDatabase()
+        .prepare(`SELECT id, habit_id, date_key, status, note, delta_xp, created_at, updated_at
+       FROM habit_check_ins
+       WHERE habit_id = ?
+       ORDER BY date_key DESC, created_at DESC
+       LIMIT ?`)
+        .all(habitId, limit);
+    return rows.map(mapCheckIn);
+}
+function isAligned(habit, checkIn) {
+    return (habit.polarity === "positive" && checkIn.status === "done") || (habit.polarity === "negative" && checkIn.status === "missed");
+}
+function calculateCompletionRate(habit, checkIns) {
+    if (checkIns.length === 0) {
+        return 0;
+    }
+    const aligned = checkIns.filter((checkIn) => isAligned(habit, checkIn)).length;
+    return Math.round((aligned / checkIns.length) * 100);
+}
+function calculateStreak(habit, checkIns) {
+    let streak = 0;
+    for (const checkIn of checkIns) {
+        if (!isAligned(habit, checkIn)) {
+            break;
+        }
+        streak += 1;
+    }
+    return streak;
+}
+function isHabitDueToday(habit, latestCheckIn, now = new Date()) {
+    if (habit.status !== "active") {
+        return false;
+    }
+    const key = todayKey(now);
+    if (latestCheckIn?.dateKey === key) {
+        return false;
+    }
+    if (habit.frequency === "daily") {
+        return true;
+    }
+    return habit.weekDays.includes(now.getUTCDay());
+}
+function mapHabit(row, checkIns = listCheckInsForHabit(row.id)) {
+    const latestCheckIn = checkIns[0] ?? null;
+    const linkedBehaviorIds = normalizeLinkedBehaviorIds({
+        linkedBehaviorIds: parseIdList(row.linked_behavior_ids_json),
+        linkedBehaviorId: row.linked_behavior_id
+    });
+    const linkedBehaviors = linkedBehaviorIds
+        .map((behaviorId) => getBehaviorById(behaviorId))
+        .filter((behavior) => behavior !== undefined);
+    const draft = {
+        id: row.id,
+        title: row.title,
+        description: row.description,
+        status: row.status,
+        polarity: row.polarity,
+        frequency: row.frequency,
+        targetCount: row.target_count,
+        weekDays: parseWeekDays(row.week_days_json),
+        linkedGoalIds: parseIdList(row.linked_goal_ids_json),
+        linkedProjectIds: parseIdList(row.linked_project_ids_json),
+        linkedTaskIds: parseIdList(row.linked_task_ids_json),
+        linkedValueIds: parseIdList(row.linked_value_ids_json),
+        linkedPatternIds: parseIdList(row.linked_pattern_ids_json),
+        linkedBehaviorIds,
+        linkedBeliefIds: parseIdList(row.linked_belief_ids_json),
+        linkedModeIds: parseIdList(row.linked_mode_ids_json),
+        linkedReportIds: parseIdList(row.linked_report_ids_json),
+        linkedBehaviorId: linkedBehaviorIds[0] ?? null,
+        linkedBehaviorTitle: linkedBehaviors[0]?.title ?? null,
+        linkedBehaviorTitles: linkedBehaviors.map((behavior) => behavior.title),
+        rewardXp: row.reward_xp,
+        penaltyXp: row.penalty_xp,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        lastCheckInAt: latestCheckIn?.createdAt ?? null,
+        lastCheckInStatus: latestCheckIn?.status ?? null,
+        streakCount: calculateStreak({ polarity: row.polarity }, checkIns),
+        completionRate: calculateCompletionRate({ polarity: row.polarity }, checkIns),
+        dueToday: false,
+        checkIns
+    };
+    draft.dueToday = isHabitDueToday({ status: draft.status, frequency: draft.frequency, weekDays: draft.weekDays }, latestCheckIn);
+    return habitSchema.parse(draft);
+}
+function getHabitRow(habitId) {
+    return getDatabase()
+        .prepare(`SELECT
+         id, title, description, status, polarity, frequency, target_count, week_days_json,
+         linked_goal_ids_json, linked_project_ids_json, linked_task_ids_json,
+         linked_value_ids_json, linked_pattern_ids_json, linked_behavior_ids_json,
+         linked_belief_ids_json, linked_mode_ids_json, linked_report_ids_json,
+         linked_behavior_id, reward_xp, penalty_xp, created_at, updated_at
+       FROM habits
+       WHERE id = ?`)
+        .get(habitId);
+}
+export function listHabits(filters = {}) {
+    const parsed = filters;
+    const whereClauses = [];
+    const params = [];
+    if (parsed.status) {
+        whereClauses.push("status = ?");
+        params.push(parsed.status);
+    }
+    if (parsed.polarity) {
+        whereClauses.push("polarity = ?");
+        params.push(parsed.polarity);
+    }
+    const limitSql = parsed.limit ? "LIMIT ?" : "";
+    if (parsed.limit) {
+        params.push(parsed.limit);
+    }
+    const whereSql = whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";
+    const rows = getDatabase()
+        .prepare(`SELECT
+         id, title, description, status, polarity, frequency, target_count, week_days_json,
+         linked_goal_ids_json, linked_project_ids_json, linked_task_ids_json,
+         linked_value_ids_json, linked_pattern_ids_json, linked_behavior_ids_json,
+         linked_belief_ids_json, linked_mode_ids_json, linked_report_ids_json,
+         linked_behavior_id, reward_xp, penalty_xp, created_at, updated_at
+       FROM habits
+       ${whereSql}
+       ORDER BY
+         CASE status WHEN 'active' THEN 0 WHEN 'paused' THEN 1 ELSE 2 END,
+         updated_at DESC
+       ${limitSql}`)
+        .all(...params);
+    const habits = rows.map((row) => mapHabit(row));
+    return parsed.dueToday ? habits.filter((habit) => habit.dueToday) : habits;
+}
+export function getHabitById(habitId) {
+    const row = getHabitRow(habitId);
+    return row ? mapHabit(row) : undefined;
+}
+export function createHabit(input, activity) {
+    const parsed = createHabitSchema.parse(input);
+    const linkedBehaviorIds = normalizeLinkedBehaviorIds(parsed);
+    validateExistingIds(parsed.linkedGoalIds, getGoalById, "goal_not_found", "Goal");
+    validateExistingIds(parsed.linkedProjectIds, getProjectById, "project_not_found", "Project");
+    validateExistingIds(parsed.linkedTaskIds, getTaskById, "task_not_found", "Task");
+    validateExistingIds(parsed.linkedValueIds, getPsycheValueById, "value_not_found", "Value");
+    validateExistingIds(parsed.linkedPatternIds, getBehaviorPatternById, "pattern_not_found", "Pattern");
+    validateExistingIds(linkedBehaviorIds, getBehaviorById, "behavior_not_found", "Behavior");
+    validateExistingIds(parsed.linkedBeliefIds, getBeliefEntryById, "belief_not_found", "Belief");
+    validateExistingIds(parsed.linkedModeIds, getModeProfileById, "mode_not_found", "Mode");
+    validateExistingIds(parsed.linkedReportIds, getTriggerReportById, "report_not_found", "Report");
+    return runInTransaction(() => {
+        const now = new Date().toISOString();
+        const id = `habit_${randomUUID().replaceAll("-", "").slice(0, 10)}`;
+        getDatabase()
+            .prepare(`INSERT INTO habits (
+          id, title, description, status, polarity, frequency, target_count, week_days_json,
+          linked_goal_ids_json, linked_project_ids_json, linked_task_ids_json,
+          linked_value_ids_json, linked_pattern_ids_json, linked_behavior_ids_json,
+          linked_belief_ids_json, linked_mode_ids_json, linked_report_ids_json,
+          linked_behavior_id, reward_xp, penalty_xp, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, parsed.title, parsed.description, parsed.status, parsed.polarity, parsed.frequency, parsed.targetCount, JSON.stringify(parsed.weekDays), JSON.stringify(parsed.linkedGoalIds), JSON.stringify(parsed.linkedProjectIds), JSON.stringify(parsed.linkedTaskIds), JSON.stringify(parsed.linkedValueIds), JSON.stringify(parsed.linkedPatternIds), JSON.stringify(linkedBehaviorIds), JSON.stringify(parsed.linkedBeliefIds), JSON.stringify(parsed.linkedModeIds), JSON.stringify(parsed.linkedReportIds), linkedBehaviorIds[0] ?? null, parsed.rewardXp, parsed.penaltyXp, now, now);
+        const habit = getHabitById(id);
+        if (activity) {
+            recordActivityEvent({
+                entityType: "habit",
+                entityId: habit.id,
+                eventType: "habit_created",
+                title: `Habit created: ${habit.title}`,
+                description: `${habit.frequency === "daily" ? "Daily" : "Weekly"} ${habit.polarity} habit added to Forge.`,
+                actor: activity.actor ?? null,
+                source: activity.source,
+                metadata: {
+                    polarity: habit.polarity,
+                    frequency: habit.frequency,
+                    targetCount: habit.targetCount
+                }
+            });
+        }
+        return habit;
+    });
+}
+export function updateHabit(habitId, input, activity) {
+    const current = getHabitById(habitId);
+    if (!current) {
+        return undefined;
+    }
+    const parsed = updateHabitSchema.parse(input);
+    const nextLinkedBehaviorIds = parsed.linkedBehaviorIds !== undefined || parsed.linkedBehaviorId !== undefined
+        ? normalizeLinkedBehaviorIds({
+            linkedBehaviorIds: parsed.linkedBehaviorIds ?? current.linkedBehaviorIds,
+            linkedBehaviorId: parsed.linkedBehaviorId === undefined
+                ? current.linkedBehaviorId
+                : parsed.linkedBehaviorId
+        })
+        : current.linkedBehaviorIds;
+    validateExistingIds(parsed.linkedGoalIds ?? current.linkedGoalIds, getGoalById, "goal_not_found", "Goal");
+    validateExistingIds(parsed.linkedProjectIds ?? current.linkedProjectIds, getProjectById, "project_not_found", "Project");
+    validateExistingIds(parsed.linkedTaskIds ?? current.linkedTaskIds, getTaskById, "task_not_found", "Task");
+    validateExistingIds(parsed.linkedValueIds ?? current.linkedValueIds, getPsycheValueById, "value_not_found", "Value");
+    validateExistingIds(parsed.linkedPatternIds ?? current.linkedPatternIds, getBehaviorPatternById, "pattern_not_found", "Pattern");
+    validateExistingIds(nextLinkedBehaviorIds, getBehaviorById, "behavior_not_found", "Behavior");
+    validateExistingIds(parsed.linkedBeliefIds ?? current.linkedBeliefIds, getBeliefEntryById, "belief_not_found", "Belief");
+    validateExistingIds(parsed.linkedModeIds ?? current.linkedModeIds, getModeProfileById, "mode_not_found", "Mode");
+    validateExistingIds(parsed.linkedReportIds ?? current.linkedReportIds, getTriggerReportById, "report_not_found", "Report");
+    return runInTransaction(() => {
+        const updatedAt = new Date().toISOString();
+        getDatabase()
+            .prepare(`UPDATE habits
+         SET title = ?, description = ?, status = ?, polarity = ?, frequency = ?, target_count = ?,
+             week_days_json = ?, linked_goal_ids_json = ?, linked_project_ids_json = ?, linked_task_ids_json = ?,
+             linked_value_ids_json = ?, linked_pattern_ids_json = ?, linked_behavior_ids_json = ?,
+             linked_belief_ids_json = ?, linked_mode_ids_json = ?, linked_report_ids_json = ?,
+             linked_behavior_id = ?, reward_xp = ?, penalty_xp = ?, updated_at = ?
+         WHERE id = ?`)
+            .run(parsed.title ?? current.title, parsed.description ?? current.description, parsed.status ?? current.status, parsed.polarity ?? current.polarity, parsed.frequency ?? current.frequency, parsed.targetCount ?? current.targetCount, JSON.stringify(parsed.weekDays ?? current.weekDays), JSON.stringify(parsed.linkedGoalIds ?? current.linkedGoalIds), JSON.stringify(parsed.linkedProjectIds ?? current.linkedProjectIds), JSON.stringify(parsed.linkedTaskIds ?? current.linkedTaskIds), JSON.stringify(parsed.linkedValueIds ?? current.linkedValueIds), JSON.stringify(parsed.linkedPatternIds ?? current.linkedPatternIds), JSON.stringify(nextLinkedBehaviorIds), JSON.stringify(parsed.linkedBeliefIds ?? current.linkedBeliefIds), JSON.stringify(parsed.linkedModeIds ?? current.linkedModeIds), JSON.stringify(parsed.linkedReportIds ?? current.linkedReportIds), nextLinkedBehaviorIds[0] ?? null, parsed.rewardXp ?? current.rewardXp, parsed.penaltyXp ?? current.penaltyXp, updatedAt, habitId);
+        const habit = getHabitById(habitId);
+        if (activity) {
+            recordActivityEvent({
+                entityType: "habit",
+                entityId: habit.id,
+                eventType: "habit_updated",
+                title: `Habit updated: ${habit.title}`,
+                description: "Habit settings and recurrence were updated.",
+                actor: activity.actor ?? null,
+                source: activity.source,
+                metadata: {
+                    polarity: habit.polarity,
+                    frequency: habit.frequency,
+                    targetCount: habit.targetCount
+                }
+            });
+        }
+        return habit;
+    });
+}
+export function deleteHabit(habitId, activity) {
+    const current = getHabitById(habitId);
+    if (!current) {
+        return undefined;
+    }
+    return runInTransaction(() => {
+        getDatabase().prepare(`DELETE FROM habits WHERE id = ?`).run(habitId);
+        if (activity) {
+            recordActivityEvent({
+                entityType: "habit",
+                entityId: current.id,
+                eventType: "habit_deleted",
+                title: `Habit deleted: ${current.title}`,
+                description: "Habit removed from Forge.",
+                actor: activity.actor ?? null,
+                source: activity.source,
+                metadata: {
+                    polarity: current.polarity,
+                    frequency: current.frequency
+                }
+            });
+        }
+        return current;
+    });
+}
+export function createHabitCheckIn(habitId, input, activity) {
+    const habit = getHabitById(habitId);
+    if (!habit) {
+        return undefined;
+    }
+    const parsed = createHabitCheckInSchema.parse(input);
+    return runInTransaction(() => {
+        const existing = getDatabase()
+            .prepare(`SELECT id, habit_id, date_key, status, note, delta_xp, created_at, updated_at
+         FROM habit_check_ins
+         WHERE habit_id = ? AND date_key = ?`)
+            .get(habitId, parsed.dateKey);
+        const reward = recordHabitCheckInReward(habit, parsed.status, parsed.dateKey, activity ?? { source: "ui", actor: null });
+        const now = new Date().toISOString();
+        if (existing) {
+            getDatabase()
+                .prepare(`UPDATE habit_check_ins
+           SET status = ?, note = ?, delta_xp = ?, updated_at = ?
+           WHERE id = ?`)
+                .run(parsed.status, parsed.note, reward.deltaXp, now, existing.id);
+        }
+        else {
+            getDatabase()
+                .prepare(`INSERT INTO habit_check_ins (id, habit_id, date_key, status, note, delta_xp, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(`hci_${randomUUID().replaceAll("-", "").slice(0, 10)}`, habitId, parsed.dateKey, parsed.status, parsed.note, reward.deltaXp, now, now);
+        }
+        recordActivityEvent({
+            entityType: "habit",
+            entityId: habit.id,
+            eventType: parsed.status === "done" ? "habit_done" : "habit_missed",
+            title: `${parsed.status === "done" ? "Habit completed" : "Habit missed"}: ${habit.title}`,
+            description: habit.polarity === "positive"
+                ? parsed.status === "done"
+                    ? "Positive habit logged as completed."
+                    : "Positive habit logged as missed."
+                : parsed.status === "done"
+                    ? "Negative habit logged as performed."
+                    : "Negative habit logged as resisted.",
+            actor: activity?.actor ?? null,
+            source: activity?.source ?? "ui",
+            metadata: {
+                dateKey: parsed.dateKey,
+                status: parsed.status,
+                polarity: habit.polarity,
+                deltaXp: reward.deltaXp
+            }
+        });
+        return getHabitById(habitId);
+    });
+}

package/dist/server/repositories/rewards.js

@@ -43,6 +43,22 @@ const DEFAULT_RULES = [
         description: "Reward a concrete decision to apply a useful insight.",
         config: { fixedXp: 15 }
     },
+    {
+        id: "reward_rule_habit_aligned",
+        family: "consistency",
+        code: "habit_aligned",
+        title: "Habit alignment",
+        description: "Award XP when a habit outcome matches the intended direction.",
+        config: { award: "habit.rewardXp" }
+    },
+    {
+        id: "reward_rule_habit_misaligned",
+        family: "recovery",
+        code: "habit_misaligned",
+        title: "Habit miss",
+        description: "Apply a small XP penalty when a habit outcome moves against the intended direction.",
+        config: { penalty: "habit.penaltyXp" }
+    },
     {
         id: "reward_rule_psyche_reflection_capture",
         family: "alignment",
@@ -633,6 +649,52 @@ export function recordSessionEvent(input, activity, now = new Date()) {
     }, now);
     return { sessionEvent, rewardEvent };
 }
+export function recordHabitCheckInReward(habit, status, dateKey, activity) {
+    ensureDefaultRewardRules();
+    const aligned = (habit.polarity === "positive" && status === "done") ||
+        (habit.polarity === "negative" && status === "missed");
+    const rule = getRuleByCode(aligned ? "habit_aligned" : "habit_misaligned");
+    const deltaXp = aligned ? habit.rewardXp : -Math.abs(habit.penaltyXp);
+    const actionLabel = habit.polarity === "positive"
+        ? status === "done"
+            ? "completed"
+            : "missed"
+        : status === "done"
+            ? "performed"
+            : "resisted";
+    const eventLog = recordEventLog({
+        eventKind: aligned ? "reward.habit_aligned" : "reward.habit_misaligned",
+        entityType: "habit",
+        entityId: habit.id,
+        actor: activity.actor ?? null,
+        source: activity.source,
+        metadata: {
+            habitId: habit.id,
+            status,
+            polarity: habit.polarity,
+            dateKey,
+            deltaXp
+        }
+    });
+    return insertLedgerEvent({
+        ruleId: rule?.id ?? null,
+        eventLogId: eventLog.id,
+        entityType: "habit",
+        entityId: habit.id,
+        actor: activity.actor ?? null,
+        source: activity.source,
+        deltaXp,
+        reasonTitle: aligned ? `${habit.title} aligned` : `${habit.title} slipped`,
+        reasonSummary: `Habit ${actionLabel} on ${dateKey}.`,
+        reversibleGroup: `habit:${habit.id}:${dateKey}`,
+        metadata: {
+            habitId: habit.id,
+            status,
+            polarity: habit.polarity,
+            dateKey
+        }
+    });
+}
 export function listSessionEvents(limit = 50) {
     const rows = getDatabase()
         .prepare(`SELECT id, session_id, event_type, actor, source, metrics_json, created_at

package/dist/server/services/context.js

@@ -1,5 +1,7 @@
 import { listActivityEvents } from "../repositories/activity-events.js";
 import { listGoals } from "../repositories/goals.js";
+import { listHabits } from "../repositories/habits.js";
+import { listRewardLedger } from "../repositories/rewards.js";
 import { listTags, listTagsByIds } from "../repositories/tags.js";
 import { listTasks } from "../repositories/tasks.js";
 import { getDashboard } from "./dashboard.js";
@@ -109,6 +111,7 @@ export function getOverviewContext(now = new Date()) {
     const dashboard = getDashboard();
     const focusTasks = dashboard.tasks.filter((task) => task.status === "focus" || task.status === "in_progress").length;
     const overdueTasks = dashboard.tasks.filter((task) => task.status !== "done" && task.dueDate !== null && task.dueDate < now.toISOString().slice(0, 10)).length;
+    const dueHabits = dashboard.habits.filter((habit) => habit.dueToday).slice(0, 6);
     return overviewContextSchema.parse({
         generatedAt: now.toISOString(),
         strategicHeader: {
@@ -124,8 +127,9 @@ export function getOverviewContext(now = new Date()) {
         projects: dashboard.projects.slice(0, 5),
         activeGoals: dashboard.goals.filter((goal) => goal.status === "active").slice(0, 6),
         topTasks: sortStrategicTasks(dashboard.tasks.filter((task) => task.status !== "done")).slice(0, 6),
+        dueHabits,
         recentEvidence: listActivityEvents({ limit: 12 }),
-        achievements: buildAchievementSignals(listGoals(), listTasks(), now),
+        achievements: buildAchievementSignals(listGoals(), listTasks(), listHabits(), now),
         domainBalance: buildDomainBalance(listGoals(), listTasks()),
         neglectedGoals: buildNeglectedGoals(listGoals(), listTasks(), now)
     });
@@ -133,10 +137,12 @@ export function getOverviewContext(now = new Date()) {
 export function getTodayContext(now = new Date()) {
     const goals = listGoals();
     const tasks = listTasks();
-    const gamification = buildGamificationProfile(goals, tasks, now);
+    const habits = listHabits();
+    const gamification = buildGamificationProfile(goals, tasks, habits, now);
     const inProgressTasks = sortStrategicTasks(tasks.filter((task) => task.status === "in_progress")).slice(0, 4);
     const readyTasks = sortStrategicTasks(tasks.filter((task) => task.status === "focus" || task.status === "backlog")).slice(0, 4);
     const deferredTasks = sortStrategicTasks(tasks.filter((task) => task.status === "blocked")).slice(0, 4);
+    const dueHabits = habits.filter((habit) => habit.dueToday).slice(0, 6);
     const completedTasks = [...tasks]
         .filter((task) => task.status === "done" && task.completedAt !== null)
         .sort((left, right) => Date.parse(right.completedAt ?? "") - Date.parse(left.completedAt ?? ""))
@@ -185,13 +191,17 @@ export function getTodayContext(now = new Date()) {
                 completed: false
             }
         ],
-        milestoneRewards: buildMilestoneRewards(goals, tasks, now),
+        dueHabits,
+        milestoneRewards: buildMilestoneRewards(goals, tasks, habits, now),
+        recentHabitRewards: listRewardLedger({ entityType: "habit", limit: 8 }),
         momentum: {
             streakDays: gamification.streakDays,
             momentumScore: gamification.momentumScore,
-            recoveryHint: overdueCount > 0
-                ? `Clear ${overdueCount} overdue task${overdueCount === 1 ? "" : "s"} to keep momentum from decaying.`
-                : "No overdue drag right now. Preserve the rhythm with one decisive completion."
+            recoveryHint: dueHabits.length > 0
+                ? `${dueHabits.length} habit${dueHabits.length === 1 ? "" : "s"} still need a check-in today. Closing one will keep momentum honest.`
+                : overdueCount > 0
+                    ? `Clear ${overdueCount} overdue task${overdueCount === 1 ? "" : "s"} to keep momentum from decaying.`
+                    : "No overdue drag right now. Preserve the rhythm with one decisive completion."
         }
     });
 }

package/dist/server/services/dashboard.js

@@ -1,5 +1,6 @@
 import { listGoals } from "../repositories/goals.js";
 import { listActivityEvents } from "../repositories/activity-events.js";
+import { listHabits } from "../repositories/habits.js";
 import { buildNotesSummaryByEntity } from "../repositories/notes.js";
 import { listTagsByIds, listTags } from "../repositories/tags.js";
 import { listTasks } from "../repositories/tasks.js";
@@ -116,6 +117,7 @@ function buildGoalSummary(tasks, goalId) {
 export function getDashboard() {
     const goals = listGoals();
     const tasks = listTasks();
+    const habits = listHabits();
     const tags = listTags();
     const now = new Date();
     const weekStart = startOfWeek(now).toISOString();
@@ -150,9 +152,9 @@ export function getDashboard() {
     const suggestedTags = tags.filter((tag) => ["value", "execution"].includes(tag.kind)).slice(0, 6);
     const owners = [...new Set(tasks.map((task) => task.owner).filter(Boolean))].sort((left, right) => left.localeCompare(right));
     const executionBuckets = buildExecutionBuckets(tasks, todayIso, weekEndIso);
-    const gamification = buildGamificationProfile(goals, tasks, now);
-    const achievements = buildAchievementSignals(goals, tasks, now);
-    const milestoneRewards = buildMilestoneRewards(goals, tasks, now);
+    const gamification = buildGamificationProfile(goals, tasks, habits, now);
+    const achievements = buildAchievementSignals(goals, tasks, habits, now);
+    const milestoneRewards = buildMilestoneRewards(goals, tasks, habits, now);
     const recentActivity = listActivityEvents({ limit: 12 });
     const notesSummaryByEntity = buildNotesSummaryByEntity();
     return dashboardPayloadSchema.parse({
@@ -160,6 +162,7 @@ export function getDashboard() {
         goals: goalCards,
         projects,
         tasks,
+        habits,
         tags,
         suggestedTags,
         owners,

package/dist/server/services/entity-crud.js

@@ -4,11 +4,12 @@ import { createNote, deleteNote, getNoteById, listNotes, unlinkNotesForEntity, u
 import { createBehaviorPatternSchema, createBehaviorSchema, createBeliefEntrySchema, createEmotionDefinitionSchema, createEventTypeSchema, createModeGuideSessionSchema, createModeProfileSchema, createPsycheValueSchema, createTriggerReportSchema, updateBehaviorPatternSchema, updateBehaviorSchema, updateBeliefEntrySchema, updateEmotionDefinitionSchema, updateEventTypeSchema, updateModeGuideSessionSchema, updateModeProfileSchema, updatePsycheValueSchema, updateTriggerReportSchema } from "../psyche-types.js";
 import { buildSettingsBinPayload, cascadeSoftDeleteAnchoredCollaboration, clearDeletedEntityRecord, getDeletedEntityRecord, listDeletedEntities, restoreAnchoredCollaboration, restoreDeletedEntityRecord, upsertDeletedEntityRecord } from "../repositories/deleted-entities.js";
 import { createGoal, deleteGoal, getGoalById, listGoals, updateGoal } from "../repositories/goals.js";
+import { createHabit, deleteHabit, getHabitById, listHabits, updateHabit } from "../repositories/habits.js";
 import { createBehavior, createBehaviorPattern, createBeliefEntry, createEmotionDefinition, createEventType, createModeGuideSession, createModeProfile, createPsycheValue, createTriggerReport, deleteBehavior, deleteBehaviorPattern, deleteBeliefEntry, deleteEmotionDefinition, deleteEventType, deleteModeGuideSession, deleteModeProfile, deletePsycheValue, deleteTriggerReport, getBehaviorById, getBehaviorPatternById, getBeliefEntryById, getEmotionDefinitionById, getEventTypeById, getModeGuideSessionById, getModeProfileById, getPsycheValueById, getTriggerReportById, listBehaviors, listBehaviorPatterns, listBeliefEntries, listEmotionDefinitions, listEventTypes, listModeGuideSessions, listModeProfiles, listPsycheValues, listTriggerReports, updateBehavior, updateBehaviorPattern, updateBeliefEntry, updateEmotionDefinition, updateEventType, updateModeGuideSession, updateModeProfile, updatePsycheValue, updateTriggerReport } from "../repositories/psyche.js";
 import { createProject, deleteProject, getProjectById, listProjects, updateProject } from "../repositories/projects.js";
 import { createTag, deleteTag, getTagById, listTags, updateTag } from "../repositories/tags.js";
 import { createTask, deleteTask, getTaskById, listTasks, updateTask } from "../repositories/tasks.js";
-import { createGoalSchema, createInsightSchema, createNoteSchema, createProjectSchema, createTagSchema, createTaskSchema, updateGoalSchema, updateInsightSchema, updateNoteSchema, updateProjectSchema, updateTagSchema, updateTaskSchema } from "../types.js";
+import { createGoalSchema, createHabitSchema, createInsightSchema, createNoteSchema, createProjectSchema, createTagSchema, createTaskSchema, updateGoalSchema, updateHabitSchema, updateInsightSchema, updateNoteSchema, updateProjectSchema, updateTagSchema, updateTaskSchema } from "../types.js";
 class AtomicBatchRollback extends Error {
     index;
     code;
@@ -49,6 +50,15 @@ const CRUD_ENTITY_CAPABILITIES = {
         update: (id, patch, context) => updateTask(id, patch, context),
         hardDelete: (id, context) => deleteTask(id, context)
     },
+    habit: {
+        entityType: "habit",
+        routeBase: "/api/v1/habits",
+        list: () => listHabits(),
+        get: (id) => getHabitById(id),
+        create: (data, context) => createHabit(data, context),
+        update: (id, patch, context) => updateHabit(id, patch, context),
+        hardDelete: (id, context) => deleteHabit(id, context)
+    },
     tag: {
         entityType: "tag",
         routeBase: "/api/v1/tags",
@@ -174,6 +184,7 @@ const CREATE_ENTITY_SCHEMAS = {
     goal: createGoalSchema,
     project: createProjectSchema,
     task: createTaskSchema,
+    habit: createHabitSchema,
     tag: createTagSchema,
     note: createNoteSchema,
     insight: createInsightSchema,
@@ -191,6 +202,7 @@ const UPDATE_ENTITY_SCHEMAS = {
     goal: updateGoalSchema,
     project: updateProjectSchema,
     task: updateTaskSchema,
+    habit: updateHabitSchema,
     tag: updateTagSchema,
     note: updateNoteSchema,
     insight: updateInsightSchema,
@@ -312,6 +324,16 @@ function matchesLinkedTo(entityType, entity, linkedTo) {
             return linkedTo.entityType === "goal" && entity.goalId === linkedTo.id;
         case "task":
             return (linkedTo.entityType === "goal" && entity.goalId === linkedTo.id) || (linkedTo.entityType === "project" && entity.projectId === linkedTo.id);
+        case "habit":
+            return ((linkedTo.entityType === "goal" && Array.isArray(entity.linkedGoalIds) && entity.linkedGoalIds.includes(linkedTo.id)) ||
+                (linkedTo.entityType === "project" && Array.isArray(entity.linkedProjectIds) && entity.linkedProjectIds.includes(linkedTo.id)) ||
+                (linkedTo.entityType === "task" && Array.isArray(entity.linkedTaskIds) && entity.linkedTaskIds.includes(linkedTo.id)) ||
+                (linkedTo.entityType === "psyche_value" && Array.isArray(entity.linkedValueIds) && entity.linkedValueIds.includes(linkedTo.id)) ||
+                (linkedTo.entityType === "behavior_pattern" && Array.isArray(entity.linkedPatternIds) && entity.linkedPatternIds.includes(linkedTo.id)) ||
+                (linkedTo.entityType === "behavior" && Array.isArray(entity.linkedBehaviorIds) && entity.linkedBehaviorIds.includes(linkedTo.id)) ||
+                (linkedTo.entityType === "belief_entry" && Array.isArray(entity.linkedBeliefIds) && entity.linkedBeliefIds.includes(linkedTo.id)) ||
+                (linkedTo.entityType === "mode_profile" && Array.isArray(entity.linkedModeIds) && entity.linkedModeIds.includes(linkedTo.id)) ||
+                (linkedTo.entityType === "trigger_report" && Array.isArray(entity.linkedReportIds) && entity.linkedReportIds.includes(linkedTo.id)));
         case "note":
             return (Array.isArray(entity.links) &&
                 entity.links.some((link) => typeof link === "object" &&