v0.2.2 to v0.2.2

---

name: goal-manual

description: >

Goal notification manual: `.notification/goal.json` source-of-truth, fields,

instructions, idle reminders, protected dismiss behavior, and cancellation or

completion semantics.

version: 0.2.2

tags: [lingtai, goal, notifications, reminders]

last_changed_at: 2026-07-27T00:00:00Z

related_files:

- src/lingtai/intrinsic_skills/system-manual/SKILL.md

- src/lingtai/kernel/nudge/goal.py

maintenance: |

Tracks the goal-notification topic it documents; update when that integration changes.

---

# Goal Manual

A goal is represented by `.notification/goal.json`. This file is the protected

source of truth for the agent's current active goal. The short reminder event only

points the agent back to this file; it does not contain the goal details.

## Guided setup via `/goal`

`/goal` is the TUI entry point for human-guided goal creation. It does **not**

write `.notification/goal.json` directly. Instead, the TUI appends a system event

to `.notification/system.json` so the running agent can guide the human before

creating or changing the goal file:

```json

{

"source": "goal.request",

"ref_id": "goal.request:<timestamp>",

"body": "Human wants to set or revise an active goal..."

}

```

When you receive a `source="goal.request"` event:

1. **Read this manual first.** The event is a request to guide goal creation, not

permission to invent goal details.

2. **Explain the mechanism briefly to the human.** Tell them that an active goal

lives in `.notification/goal.json`, idle reminders are short

`goal.reminder` system events, and dismissing a reminder only hides the

reminder.

3. **Ask for the missing goal fields.** At minimum, clarify:

- objective: what should be accomplished;

- criteria: how the human and agent will know it is done;

- status/id: a stable `data.id` and active status if the goal should start

now;

- reminder cadence: optional `data.reminder_delay_seconds`;

- constraints: deadlines, channels to report on, what not to do, or approval

gates.

4. **Explain cancellation and completion before writing** — see "Protected

dismiss behavior" below for the exact semantics.

5. **Write `.notification/goal.json` only after confirmation.** If the human gave

a complete inline draft with `/goal <text>`, restate the structured goal and

ask for confirmation unless the instruction explicitly and unambiguously says

to create it now.

6. **Dismiss the request after handling it.** Use the event `ref_id` so other

system events survive:

```text

notification(action="dismiss_ref",

input={"ref_id": "goal.request:<timestamp>", "channel": null,

"force": null, "reason": null},

reasoning="the goal request is handled")

```

If the human changes their mind during setup, dismiss the `goal.request` event

without creating `goal.json`. If a previous active goal exists, do not overwrite

it silently; explain the existing goal and ask whether to complete, cancel, or

replace it.

## Minimal goal file

```json

{

"header": "Active goal: finish notification PR",

"icon": "🎯",

"priority": "high",

"published_at": "2026-06-10T00:00:00Z",

"instructions": "Current active goal. Read data.objective and data.criteria. This channel is protected: do not dismiss it. To cancel the goal, delete .notification/goal.json. See the goal manual under system-manual.",

"data": {

"id": "notification-pr",

"status": "active",

"objective": "Implement notification whitelist, atomic system-event dismiss, and goal reminders.",

"criteria": ["tests pass", "manuals updated", "PR opened"],

"reminder_delay_seconds": 120

}

}

```

Recommended fields live under `data`:

- `id`: stable identifier used by reminders as `ref_id="goal:<id>"`.

- `status`: omit or use `active` for active work. `done`, `complete`,

`completed`, `superseded`, `cancelled`, `canceled`, or `inactive` suppress

reminders.

- `objective`: what to accomplish.

- `criteria`: what done means.

- `reminder_delay_seconds`: optional idle delay before a reminder. If absent, the

The top-level `instructions` field should explicitly say to read the goal data,

that the `goal` channel is protected, and that this manual has the mechanism

details.

## Protected dismiss behavior

`goal` is not an ordinary dismissible notification mirror. Generic dismiss refuses:

```text

notification(action="dismiss_channel",

input={"channel": "goal", "force": null, "reason": null},

reasoning="...") # refused

```

To cancel the goal, delete `.notification/goal.json` or mark `data.status`

`inactive`/`cancelled`/`canceled`. To complete or supersede it, mark

`data.status` `done`/`complete`/`completed`/`superseded`, or delete/replace the

file. Dismissing a `goal.reminder` does **not** cancel the goal. Agents are

trusted to decide when the source-of-truth file should change; the protection only

prevents misleading API semantics where dismissing a notification looks like

canceling a goal.

## Idle reminder behavior

The reminder trigger requires the source-of-truth file itself: if

`.notification/goal.json` is absent, no goal reminder is generated.

When `.notification/goal.json` exists, is active, and the agent remains IDLE for

the configured delay, the kernel publishes one short event into

`.notification/system.json`:

```json

{

"source": "goal.reminder",

"ref_id": "goal:<id>",

"body": "Goal reminder: read .notification/goal.json and follow its instructions; see the goal manual under system-manual."

}

```

The reminder is intentionally brief. The actual goal and instructions stay in

`goal.json`. Dismissing the reminder clears only the system event:

Same call shape as the goal-request dismiss above, with

`ref_id="goal:<id>"`.

Cancellation and completion semantics are above, under "Protected dismiss

behavior": dismissing a reminder never cancels the goal, so if the goal remains

active a fresh idle interval can generate another reminder. If `goal.json` is

deleted or marked inactive/done while a reminder is already present, the next

IDLE goal check clears that stale `goal.reminder` system event.

## Cross-reference

For notification channels, envelopes, allowlist behavior, and atomic system-event

dismiss, read the first-level `notification-manual` skill.