@aitne-sh/aitne 0.1.7 → 0.1.9

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,157 @@ 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-05-28
 keywords:
   - journal
   - retros
   - decisions
   - reflection
+  - append-only
 related:
+  - features/routines/morning-routine
   - features/routines/evening-review
   - features/routines/weekly-review
   - 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
   - /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; the monthly retro distills them into trend notes.
+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*.
 
-## When It Runs / How It Is Triggered
+Each entry carries:
 
-- **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.
-
-## 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 timestamp (the routine stamps an `Appended at:` line).
+- 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 / monthly).
+The file lives at `~/.personal-agent/context/journal/agent.md` and
+grows forever. 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
+
+- **Connections → Journal** (`/connections/journal`) is the read view
+  of the file.
+- **Settings → Journal** (`/settings/journal`) controls retention and
+  which routines contribute.
 
 ## 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.
+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
+## 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.
+- **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
+  can re-append rather than overwrite; the weekly review has an
+  idempotency check for its own section, but it is best-effort — a
+  manual prune is fine.
 
 ## 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.
+- [Memory model](../../concepts/memory-model.md) — how the journal fits
+  the wider context vault.

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

@@ -1,56 +1,116 @@
 ---
 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
   - projects
+  - core
 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-05-28
+keywords:
+  - projects
+  - project file
+  - 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 dashboard's project
+view filters on it, and the morning routine only surfaces projects
+whose `state` is active.
+
+```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,21 +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-05-28
+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
@@ -37,19 +49,51 @@ 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.
+- 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 "T-7 days: book hotel" surface in
-  the morning routine on the right day.
+  the morning routine on the day each offset lands — 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
+## Conference talk — 2026-06-20
+
+Goal: deliver the keynote in Tokyo.
+
+Preparation Timeline:
+- T-14 days: finalize slide deck
+- T-7 days: book hotel
+- T-2 days: dry run with the team
+- T-0: travel day
+```
+
+On 2026-06-06 the morning routine sees the `T-14` offset 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 whose offset fires that day.
+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
 
@@ -57,5 +101,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.