@aitne-sh/aitne 0.1.8 → 0.1.10

package/agent-assets/docs/features/memory-files/agent-journal.md

@@ -1,7 +1,7 @@
 ---
 schema_version: 1
 slug: features/memory-files/agent-journal
-title: agent/journal.md
+title: journal/agent.md
 id: agent-journal
 aliases:
   - journal
@@ -10,96 +10,175 @@ aliases:
 category: features
 summary: |
   The agent's append-only log of decisions, retros, and judgement
-  calls. Distinct from Activity (which is action-shaped) — the journal
-  is reflection-shaped.
+  calls, at journal/agent.md. Distinct from Activity (which is
+  action-shaped) — the journal is reflection-shaped. Written by the
+  morning, evening, and weekly routines; the API enforces append-only.
 section: memory-files
 tags:
   - memory
   - journal
   - reflection
+  - routines
 status: stable
 ask_examples:
   - What is the agent journal?
   - Where does the agent log its own decisions?
   - How is the journal different from Activity?
+  - Why did journal/agent.md stop growing?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-06-07
 keywords:
   - journal
   - retros
   - decisions
   - reflection
+  - append-only
 related:
+  - features/routines/morning-routine
   - features/routines/evening-review
   - features/routines/weekly-review
+  - features/memory-files/agent-lessons
   - features/operations/activity-and-conversations
+  - concepts/memory-model
+process_keys:
+  - routine.morning_routine_journal
+  - routine.evening_review
+  - routine.weekly_review
+context_files:
+  - journal/agent.md
 ui_anchors:
-  - /connections/journal
+  - /knowledge?tab=context-files
   - /settings/journal
-context_files:
-  - agent/journal.md
 ---
 
-# agent/journal.md
+# journal/agent.md
 
-## In One Sentence
+## In one sentence
 
-`agent/journal.md` is the agent's own running diary — what it noticed,
+`journal/agent.md` is the agent's own running diary — what it noticed,
 what it tried, what it would do differently — appended (never
 rewritten) so a long timeline accumulates.
 
-## What It Does
+## What it is
 
 The journal is the place the agent writes about its own work in the
-first person. Each entry has:
-
-- A timestamp.
-- A short context line (which routine / conversation prompted it).
-- The reflection itself.
-
-Unlike Activity, the journal is opinion-shaped. The evening review
-adds the day's reflections; the weekly retro reads them back to
-look for patterns.
-
-## When It Runs / How It Is Triggered
+first person. Unlike Activity — which is the action-shaped audit log
+of *what happened* — the journal is reflection-shaped: it captures
+*why*, *what surprised it*, and *what it would change*.
 
-- **Evening review** adds the largest chunk — what worked, what was
-  surprising, what felt off.
-- **Weekly review** appends a retro that quotes prior journal entries
-  to find a thread.
-- **In-the-moment** entries fire when the agent notices something
-  worth flagging during reactive work.
+Each entry carries:
 
-## What It Outputs
-
-- An ever-growing append-only file at
-  `~/.personal-agent/context/agent/journal.md`.
-- A linked-from-roadmap section when an entry tied a project to a new
-  decision.
-
-## Where in the Dashboard
+- A dated heading — the morning routine stamps a
+  `## YYYY-MM-DD morning routine` H2; the weekly and monthly retros add
+  a `> Appended at: YYYY-MM-DD HH:MM` line under their section header.
+- A short context line — which routine or conversation prompted it.
+- The reflection itself.
 
-- **Connections → Journal** is the read view of the file.
-- **Settings → Journal** controls retention and which routines
-  contribute (currently always-on for evening / weekly).
+The file lives at `~/.personal-agent/context/journal/agent.md`. The
+day-to-day morning and ad-hoc entries accumulate indefinitely; the
+daily retention rollup keeps only a rolling window of the structured
+retros (the most recent 12 `## Weekly` and 24 `## Monthly` sections),
+pruning older ones. Later routines read it back to look for patterns.
+
+## Who writes it, and when
+
+Three routines append to the journal — none ever rewrites it:
+
+- **Morning routine** (Stage B, `routine.morning_routine_journal`) is
+  the recurring daily writer. After the day's stages settle, the
+  daemon appends a one-paragraph audit-trail entry assembled from the
+  prior day's `agent_actions` — stage results, retry stats, anomalies.
+  This is the entry you'll see most often.
+- **Weekly review** (`routine.weekly_review`) appends the largest
+  structured block: a `## Weekly YYYY-Www` retro with *What worked*,
+  *What slipped on my side*, *System improvement ideas*, and agent-side
+  metrics. It quotes prior entries to find a thread.
+- **Evening review** (`routine.evening_review`) appends short
+  bookkeeping lines — for example a one-liner each time it bumps a
+  roadmap review forward, or a validation error if a roadmap write was
+  rejected. It does not write the bulk of the diary.
+
+In-the-moment notes can also land here when the agent flags something
+worth recording during reactive work.
+
+### Example entry
+
+```
+## Weekly 2026-W21
+> Appended at: 2026-05-25 21:40
+
+### What worked
+- Morning brief landed before the 09:00 standup three days running.
+### What slipped on my side
+- Missed the Friday PR-review trigger — webhook arrived during quiet hours.
+### System improvement ideas
+- Add Saturday to the Weekend day-type default so weekend pushes triage.
+### Metrics (agent side)
+- Agent plan rows completed: 12
+- Did-not-fire / failed rows: 1
+- Observations reviewed / ignored: 18 / 4
+```
+
+## Append-only — enforced, not just convention
+
+The journal is append-only at the API layer, not merely by prompt
+discipline. `journal/agent.md` is the sole entry in `CREATE_ONLY_PUT`:
+a `PUT` only succeeds if the file does not yet exist, and a `PATCH`
+must use `append` or `append_to_file` mode. A `replace` or `clear`
+PATCH is rejected outright, so a misbehaving (or prompt-injected) agent
+cannot destroy history. Writes go through the daemon context API
+(`PATCH /api/context/journal/agent`) — the agent has no direct
+`Edit`/`Write` access to the file.
+
+## Where in the dashboard
+
+- **Knowledge → Context Files** (`/knowledge?tab=context-files`) is the
+  read view of the file — `journal/agent` is listed among the top-level
+  context files. It is flagged as sensitive: entering edit mode surfaces
+  a "deliberately pruning noise" warning before you change anything.
+- **Settings → Journal** (`/settings/journal`) does *not* edit this
+  file. It is a two-tab editor for the daily-journal rule files —
+  `policies/journal-format.md` (sections, voice, frontmatter) and
+  `policies/journal-export.md` (redaction / inclusion rules) — both of
+  which the morning routine reads when synthesizing `daily/YYYY-MM-DD.md`,
+  not `journal/agent.md`. `/connections/journal` is a compatibility alias
+  that redirects here.
 
 ## Configuration
 
-There is no per-entry configuration. The file is plain Markdown — you
-can hand-edit, prune, or git-version it like any other context file.
-
-## When Something Goes Wrong
-
-- A journal that **stops growing** points at the evening review not
-  running. See [Evening Review](../routines/evening-review.md).
-- A journal that **looks duplicated** usually means a routine retried
-  after a fallback. The agent's own anti-duplicate check is best-effort,
-  not bulletproof — manual prune is fine.
+There is no per-entry configuration. The file is plain Markdown, so
+**you** (the human owner) can hand-edit, prune, or git-version it like
+any other context file — the API append-only guard applies only to the
+agent's own writes, not to you editing the file on disk.
+
+## When something goes wrong
+
+- **The journal stops growing.** This usually points at the morning
+  routine's Stage B (the daily writer) or the evening/weekly review not
+  running. See [Morning Routine](../routines/morning-routine.md) and
+  [Evening Review](../routines/evening-review.md).
+- **Entries look duplicated.** This usually means a routine retried
+  after a backend fallback. Because writes are append-only, a retry
+  re-appends rather than overwrites — the weekly review deliberately
+  appends a fresh section instead of editing in place. The daemon's
+  daily retention rollup (`rollupAgentJournal`) collapses duplicate
+  `## Weekly YYYY-Www` / `## Monthly YYYY-MM` keys last-write-wins
+  within 24 hours, so duplicates self-heal; a manual prune is fine but
+  rarely needed.
 
 ## Related
 
-- [Evening Review](../routines/evening-review.md) — the daily writer.
-- [Weekly Review](../routines/weekly-review.md) — the consumer.
-- [Activity](../operations/activity-and-conversations.md) — the
-  action-shaped audit log, distinct from the journal.
+- [Morning Routine](../routines/morning-routine.md) — the recurring
+  daily writer (Stage B).
+- [Weekly Review](../routines/weekly-review.md) — the largest retro,
+  and the main consumer that reads prior entries back.
+- [Evening Review](../routines/evening-review.md) — appends short
+  bookkeeping lines.
+- [Activity & Conversations](../operations/activity-and-conversations.md)
+  — the action-shaped audit log, distinct from the reflection-shaped
+  journal.
+- [agent lessons](agent-lessons.md) — the directive-shaped learned-behavior
+  stores, distinct from this reflection-shaped diary.
+- [Memory model](../../concepts/memory-model.md) — how the journal fits
+  the wider context vault.

package/agent-assets/docs/features/memory-files/agent-lessons.md

@@ -0,0 +1,177 @@
+---
+schema_version: 1
+slug: features/memory-files/agent-lessons
+title: agent lessons
+id: agent-lessons
+aliases:
+  - lessons
+  - agent lessons
+  - feedback learning loop
+  - policies/agent-lessons.md
+category: features
+summary: |
+  The agent's learned-behavior stores — a global policies/agent-lessons.md
+  plus a per-agent policies/agents/<slug>/lessons.md. Your corrections and
+  preferences, the agent's own self-critiques, and your reactions are
+  captured as feedback signals, consolidated nightly into dated lessons,
+  re-generalized monthly, and injected back into the right executions.
+section: memory-files
+tags:
+  - memory
+  - feedback
+  - learning
+  - routines
+status: beta
+ask_examples:
+  - What are the agent lessons?
+  - Where does the agent remember my corrections?
+  - How does the feedback learning loop work?
+  - What is a provisional lesson?
+  - How do I tune the lesson caps?
+locale: en-US
+created: 2026-06-08
+updated: 2026-06-08
+keywords:
+  - lessons
+  - feedback
+  - learning loop
+  - corrections
+  - preferences
+  - self-critique
+  - provisional
+related:
+  - features/routines/evening-review
+  - features/routines/weekly-review
+  - features/memory-files/agent-journal
+  - reference/knowledge-layout
+process_keys:
+  - routine.evening_review
+  - routine.weekly_review
+  - routine.monthly_review
+context_files:
+  - policies/agent-lessons.md
+  - policies/agents/<slug>/lessons.md
+ui_anchors:
+  - /settings/lessons
+---
+
+# agent lessons
+
+## In one sentence
+
+The lesson stores are where the agent remembers how you want it to
+behave: a short, dated list of learned directives that grows from your
+corrections and the agent's own retros, and is fed back into the agent's
+work so it stops repeating the same mistakes.
+
+## What they are
+
+There are two kinds of store:
+
+- **Global agent behavior** — `policies/agent-lessons.md`. Lessons that
+  apply to the agent as a whole. These are injected into your DM
+  conversations and into the routines that decide whether to notify you.
+- **Per-agent** — `policies/agents/<slug>/lessons.md`, one per Agent
+  Definition. These are injected **only** into that agent's own
+  executions, so a lesson learned for your "weekly-report" agent never
+  leaks into an unrelated one.
+
+Both live under `~/.personal-agent/context/policies/`, alongside your
+other rule files, and are plain Markdown you can read or hand-edit.
+
+Each store is a `## Lessons` section of dated bullets. A lesson looks
+like:
+
+```
+- [2026-06-07] Keep the budget section in the weekly report. <!-- ev=2 kind=correction src=explicit conf=high last=2026-06-07 -->
+```
+
+The trailing HTML comment is bookkeeping the daemon manages: how much
+evidence backs the lesson (`ev`), what kind it is (a `correction`, a
+`do-more`/`do-less`, a hard `constraint`, …), how it was sourced, and
+when it was last reinforced. You can ignore the comment when reading —
+the prose before it is the directive.
+
+## How a lesson is born
+
+You never write these files to teach the agent a lesson; the loop does
+it for you. There are three ways signals enter:
+
+- **You correct it or state a preference.** When, in a DM, you correct
+  the agent, tell it how you want something done, or say
+  stop / do-more / do-less, it records that once as a feedback signal.
+  This does **not** change the current reply — your correction already
+  lives in that conversation — but it is remembered for later.
+- **The agent critiques itself.** The [weekly](../routines/weekly-review.md)
+  and monthly reviews post each concrete, actionable improvement idea as
+  a `self_critique` signal.
+- **Your reactions.** Whether you replied to or ignored a proactive
+  message is recorded as a weaker signal.
+
+Those raw signals don't become lessons immediately. Each night the
+[evening review](../routines/evening-review.md) folds the day's
+unconsumed signals into the right store as dated lessons, then marks them
+consumed (it skips the step entirely when nothing pends). Once a month
+the monthly review runs a re-generalize pass that collapses several
+same-theme lessons into one higher-level principle, keeping each store
+small.
+
+## Provisional vs. active
+
+A new lesson is stored but is not necessarily *injected* right away. A
+lesson carries a `<!-- provisional -->` marker until it has enough
+corroborating evidence; provisional lessons sit in the file but are not
+fed into the agent's prompts. This avoids over-fitting to a single
+offhand comment.
+
+How a lesson crosses from provisional to active:
+
+- A behavioral or self-critique lesson must reach weighted evidence at or
+  above the **promotion threshold** (`feedbackPromotionThreshold`,
+  default 2). Evidence is weighted by source — an explicit or corrected
+  signal counts 1.0, a reply or self-critique 0.5, an ignore 0.25.
+- An **explicit owner directive** ("always do X", "stop doing Y")
+  promotes on the first occurrence — it is taken at your word.
+- An **ignore on its own never promotes** a lesson, and is never read as
+  disapproval.
+
+## Bounded by design
+
+The stores can't grow without limit. Each is capped in bytes and entry
+count — the global store at `feedbackLessonMaxBytesGlobal` bytes
+(default 8192) / 40 entries, the per-agent stores at
+`feedbackLessonMaxBytesPerAgent` (default 4096) / 20 entries. When a
+store is full, the lowest-signal lessons are dropped first. Lessons that
+go untouched for `feedbackLessonStaleDays` (default 60) are pruned — with
+one exception: a `kind=constraint` lesson is durable and is never
+stale-pruned or collapsed away. The underlying feedback signals
+themselves are retained for `feedbackSignalRetentionDays` (default 180).
+
+## Where in the dashboard
+
+**Settings → Lessons** (`/settings/lessons`, labelled "Lessons" with a
+**Preview** badge) is the read/tune surface. From there you can view and
+edit the lessons themselves and adjust every knob above:
+`feedbackLearningEnabled` (the master kill-switch, on by default),
+`feedbackPromotionThreshold`, the byte caps, the stale-days horizon, and
+the signal retention window. Turning `feedbackLearningEnabled` off stops
+both capture and consolidation.
+
+## Configuration
+
+All of the loop's knobs are listed above and live on the Lessons page;
+there is nothing to configure in the files themselves. Because the stores
+are plain Markdown, **you** can hand-edit, prune, or remove a lesson at
+any time — the loop will pick up from whatever it finds the next night.
+
+## Related
+
+- [Evening Review](../routines/evening-review.md) — folds the day's
+  feedback signals into these stores each night.
+- [Weekly Review](../routines/weekly-review.md) — posts self-critique
+  signals that feed the loop. The monthly review re-generalizes the
+  stores once a month.
+- [agent journal](agent-journal.md) — the reflection-shaped diary, a
+  separate file from these directive stores.
+- [Knowledge layout](../../reference/knowledge-layout.md) — where the
+  `policies/` stores sit in the wider context vault.

package/agent-assets/docs/features/memory-files/projects.md

@@ -1,16 +1,18 @@
 ---
 schema_version: 1
 slug: features/memory-files/projects
-title: projects/ files
+title: plans/projects/ files
 id: projects
 aliases:
   - project files
   - projects directory
+  - plans/projects
 category: features
 summary: |
-  One Markdown file per active project under projects/. Each captures
+  One Markdown file per project under plans/projects/. Each captures
   the project's why, status, key links, and the per-project log of
-  agent activity. Cross-linked from the roadmap.
+  agent activity. Cross-linked from the roadmap and surfaced by the
+  morning routine while the project is active.
 section: memory-files
 tags:
   - memory
@@ -20,43 +22,97 @@ status: stable
 ask_examples:
   - Where do I find the per-project files?
   - How does the agent decide a project is active?
+  - How does the agent write to a project file?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-06-07
 keywords:
-  - projects.md
+  - projects
   - project file
-  - projects/<slug>.md
+  - plans/projects/<slug>.md
   - active project
 related:
   - features/memory-files/roadmap
+  - features/memory-files/today
+ui_anchors:
+  - /knowledge?tab=context-files
+api_endpoints:
+  - GET /api/context/list/:dir
+  - PUT /api/context/*
+  - PATCH /api/context/*
 context_files:
-  - projects/<slug>.md
+  - plans/projects/<slug>.md
 ---
 
-# projects/ Files
+# plans/projects/ Files
 
 ## In One Sentence
 
-One Markdown file per active project; the agent appends notes,
-decisions, and external references over the project's lifetime.
+One Markdown file per project, stored at `plans/projects/<slug>.md`;
+the agent appends notes, decisions, and external references over the
+project's lifetime.
 
 ## What It Does
 
-- Captures the project's purpose, status, links, recent decisions.
-- Surfaces in the morning routine when the project is active and
-  has Preparation Timeline rows.
+- Captures the project's purpose, status, links, and recent decisions
+  in a single durable note.
+- Surfaces in the morning routine while the project is active and the
+  roadmap has Preparation Timeline rows pointing at it.
 - Becomes the canonical reference the agent quotes from in DMs.
 
+## File Shape
+
+Each file lives at `plans/projects/<slug>.md`. The daemon validates
+only the minimum — `type: project`, `owner: shared`, an `updated`
+date, and an H1 title. By convention the agent also writes `slug`,
+`state`, `start`, `due`, `stakeholders`, `next_milestone`, and `tags`.
+
+`state` is what marks a project **active**: the Obsidian `_active.base`
+Bases view filters on it (`state != "archived"`), and the morning
+routine surfaces every project whose `state` is not `archived` — a
+file with no `state` (or any state other than `archived`) is treated
+as active and surfaced.
+
+```markdown
+---
+type: project
+owner: shared
+slug: spring-launch
+state: active
+due: 2026-06-15
+next_milestone: ship beta
+updated: 2026-05-28
+---
+
+# Spring Launch
+
+## Why
+Ship the public beta before the conference.
+
+## Log
+- 2026-05-28: agreed to cut feature X for v1.
+```
+
 ## When It Runs / How It Is Triggered
 
-Read on demand. Written when the operator asks the agent to
-remember something project-specific.
+Read on demand. Written when the operator asks the agent to remember
+something project-specific, or when a DM expresses project intent
+(create, update status, mark done).
+
+The agent never edits files on disk — it has no `Edit`/`Write` tools.
+All project writes go through the context API:
+
+- `GET /api/context/list/projects` — discover existing project files.
+- `PUT /api/context/plans/projects/<slug>` — create or fully replace.
+- `PATCH /api/context/plans/projects/<slug>` — append a log line or
+  update a section.
 
 ## Where in the Dashboard
 
-- **Knowledge → Context Files → projects/**.
+- **Knowledge → Context Files** (`/knowledge?tab=context-files`), under
+  the `plans/projects/` folder.
 
 ## Related
 
-- [roadmap.md](roadmap.md)
+- [roadmap.md](roadmap.md) — cross-links to project files for deeper context.
+- [today.md](today.md) — where active-project prep surfaces each day.

package/agent-assets/docs/features/memory-files/roadmap.md

@@ -15,26 +15,33 @@ summary: |
 section: memory-files
 tags:
   - memory
-  - planning
   - core
 status: stable
 ask_examples:
   - What is the roadmap file?
   - What is a Preparation Timeline?
   - How does the morning routine use the roadmap?
+  - How do I add a roadmap entry?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-06-07
 keywords:
   - roadmap.md
   - roadmap
   - long-term goals
   - preparation timeline
+  - milestones
 related:
   - features/routines/morning-routine
   - features/memory-files/projects
+  - features/memory-files/today
+ui_anchors:
+  - /knowledge?tab=context-files
+api_endpoints:
+  - PUT /api/context/*
+  - PATCH /api/context/*
 context_files:
-  - roadmap.md
+  - plans/roadmap.md
 ---
 
 # roadmap.md
@@ -42,19 +49,54 @@ context_files:
 ## In One Sentence
 
 A multi-week plan: each goal carries dates and Preparation Timeline
-rows the morning routine fires on the day of.
+rows that the morning routine fires on the day they come due.
 
 ## What It Does
 
-- Captures long-running goals beyond a single day.
-- Preparation Timeline rows like "T-7 days: book hotel" surface in
-  the morning routine on the right day.
+- Captures long-running goals that span more than a single day, so
+  they don't fall out of `state/today.md` (which is replaced fresh
+  each morning).
+- Preparation Timeline rows like "2026-06-13 [notify]: book hotel"
+  surface in the morning routine on the day each row is dated (or once
+  it is overdue) — turning a far-off milestone into concrete actions at
+  the right moment.
 - Cross-links to project files for deeper context.
 
+## What It Looks Like
+
+A goal with a Preparation Timeline is just Markdown the agent reads
+each morning. For example:
+
+```markdown
+### 2026-06-20: Conference talk
+
+Goal: deliver the keynote in Tokyo.
+
+**Preparation Timeline:**
+- 2026-06-06 [today]: finalize slide deck
+- 2026-06-13 [notify]: book hotel
+- 2026-06-18 [today]: dry run with the team
+- 2026-06-20 [today]: travel day
+```
+
+Each Preparation Timeline row carries an absolute date and a tag
+(`[notify]`, `[today]`, `[check]`, or `[schedule]`). On 2026-06-06 the
+morning routine sees the `2026-06-06` row come due and pulls "finalize
+slide deck" into that day's plan; on 2026-06-13 it surfaces "book
+hotel", and so on.
+
 ## When It Runs / How It Is Triggered
 
-Read by the morning routine; updated by the operator (or the agent
-on request).
+Read by the morning routine each day, which walks the roadmap and
+surfaces any Preparation Timeline rows dated for that day (or overdue).
+The file is updated by the operator, or by the agent on request (for
+example via the roadmap skill or `aitne run-now roadmap_maintenance`).
+
+The agent never edits the file directly. All writes go through the
+daemon's context endpoint — `PUT /api/context/plans/roadmap` (full
+replace) or `PATCH /api/context/plans/roadmap` (section op) — which is
+guarded by an exclusive roadmap write lock so two flows can't clobber
+each other.
 
 ## Where in the Dashboard
 
@@ -62,5 +104,6 @@ on request).
 
 ## Related
 
-- [Morning Routine](../routines/morning-routine.md)
-- [Projects](projects.md)
+- [Morning Routine](../../routines/morning-routine.md) — reads the roadmap each day.
+- [Projects](projects.md) — deeper, per-project context the roadmap links to.
+- [today.md](today.md) — the single-day plan the roadmap feeds into.