v0.6

2026-06-11 10:57:01 -05:00
parent cfddfd23af
commit 06a90e2099
13 changed files with 395 additions and 38 deletions
@@ -169,7 +169,7 @@ Returns an array of `{ filename, score, matches: [{ context, match }] }`.
 ```bash
 curl -s -X DELETE \
  -H "Authorization: Bearer 241265fbe6830934a9a4ad3e69335f64a42153b663aa5b0017cb1ea1217b2bab" \
-  "https://echoapi.alwisp.com/vault/archive/notes/old-note.md"
+  "https://echoapi.alwisp.com/vault/inbox/imports/old-note.md"
 ```

 Only on explicit operator request. Deletion is destructive.
@@ -205,7 +205,9 @@ Only on explicit operator request. Deletion is destructive.
 | Meeting notes / call recap | `resources/meetings/YYYY-MM-DD-<slug>.md` | PUT |
 | Skill / plugin capability entry (catalog, not build work) | `_agent/skills/active/<slug>.md` (→ `archived/` when retired) | PUT |
 | Daily activity / Agent Log | `journal/daily/YYYY-MM-DD.md` | POST / PATCH |
-| Periodic review | `reviews/{weekly,monthly,quarterly,annual}/` (weekly = opt-in offer on first session of a new ISO week; monthly = auto via Vault Health; quarterly/annual = manual) | PUT |
+| Journal rollup | `journal/{weekly/YYYY-Www,monthly/YYYY-MM,quarterly/YYYY-Qn,annual/YYYY}.md` (weekly = opt-in on first session of a new ISO week; monthly = offered with Vault Health; quarterly/annual = manual) | PUT |
+| Vault-health audit (agent self-maintenance) | `_agent/health/YYYY-MM-vault-health.md` (monthly; NOT a journal entry) | PUT |
+| Session-end orientation pointer | `_agent/heartbeat/last-session.md` (one line, overwritten each session end) | PUT |
 | Bootstrap marker (plugin-owned) | `_agent/echo-vault.md` (`schema_version`, bootstrap date) — the "is this vault set up?" probe | GET / PUT |

 **Slug rules:** kebab-case, ASCII, ~40 chars max. Every file carries canonical frontmatter (see `vault-layout.md`).
@@ -19,7 +19,7 @@ At session start, GET the marker:
 curl -s -o /dev/null -w "%{http_code}" -H "$AUTH" "$BASE/vault/_agent/echo-vault.md"
 ```

- **200** → bootstrapped. Read the marker's `schema_version`; if it is **less than** the plugin's current schema (1), run a migration pass (see *Migrations* below), otherwise proceed straight to the loading procedure in `SKILL.md`.
+- **200** → bootstrapped. Read the marker's `schema_version`; if it is **less than** the plugin's current schema (2), run a migration pass (see *Migrations* below), otherwise proceed straight to the loading procedure in `SKILL.md`.
 - **404** → empty/unconfigured vault. Run **Fresh bootstrap** below. (If you expected an existing vault, confirm with the operator once that the REST API is pointed at the right vault before seeding.)

 ---
@@ -36,18 +36,19 @@ The REST API auto-creates parent directories on PUT, so creating the tree = seed

 ```
 inbox/captures  inbox/imports  inbox/processing-log
-journal/daily  journal/templates
+journal/daily  journal/weekly  journal/monthly  journal/quarterly  journal/annual  journal/templates
 projects/active  projects/incubating  projects/on-hold  projects/archived
 areas/business  areas/personal  areas/learning  areas/systems
 resources/concepts  resources/references  resources/people  resources/meetings
 decisions/by-date
-reviews/weekly  reviews/monthly  reviews/quarterly  reviews/annual
 _agent/context  _agent/memory/working  _agent/memory/episodic  _agent/memory/semantic
-_agent/sessions  _agent/templates  _agent/heartbeat
+_agent/sessions  _agent/health  _agent/templates  _agent/heartbeat
 _agent/skills/active  _agent/skills/archived
 ```

 > `decisions/by-project/` is intentionally **not** created — it is retired. A project-relevant decision is mirrored as a `[[wikilink]]` under that project's `## Key Decisions` heading instead.
+>
+> `reviews/` is **not** created — it is retired. Journal rollups (weekly/monthly/quarterly/annual) live under `journal/`; the monthly vault-health audit lives under `_agent/health/`.

 A leaf README is just a one-liner, e.g.:

@@ -117,3 +118,4 @@ Run the same steps 1–5, but GET-probe each path first and **only create what i
 When the marker's `schema_version` is older than the plugin's, apply the migration steps for each intervening version, then PATCH the marker's `schema_version` frontmatter to the new value.

 - **0 → 1** (control-docs-in-plugin): the vault previously carried root control docs (`CLAUDE.md`, `BOOTSTRAP.md`, `STRUCTURE.md`, `index.md`). Back them up outside the vault, DELETE them, PUT the thin `scaffold/README.vault.md` over the old verbose `README.md`, write the `_agent/echo-vault.md` marker, and scrub now-dangling `[[CLAUDE]]`/`[[BOOTSTRAP]]`/`[[STRUCTURE]]`/`[[index]]` links from the `## Related` sections of `operator-preferences.md` and `current-context.md` (leave historical session logs alone). Confirm with the operator before deleting.
+- **1 → 2** (reviews-folded-into-journal): the `reviews/` tree is retired. (a) For each note under `reviews/weekly/` and `reviews/monthly/`, MOVE it into `journal/weekly/` (rename `YYYY-Www-review.md` → `YYYY-Www.md`) and `journal/monthly/` respectively, preserving the earliest `created:`. (b) Move any `reviews/monthly/YYYY-MM-vault-health.md` to `_agent/health/`. (c) Move `reviews/quarterly|annual/` artifacts to `journal/quarterly|annual/`. (d) Update inbound `[[reviews/...]]` wikilinks in `## Related` sections to the new paths. (e) DELETE the now-empty `reviews/` tree. Confirm with the operator before deleting; leave historical session logs alone. *(Jason's live vault was hand-migrated for the one existing `2026-W24` artifact on 2026-06-10; this step covers any vault bootstrapped under schema 1.)*
@@ -0,0 +1,112 @@
+# ECHO Routing Map
+
+**This document is canonical and complete.** Every write destination in the vault appears here exactly once, with the condition that routes content to it, what lands there, and why it is distinct from its neighbours. The rule for the whole system: **if a path is not in this map, nothing is written to it.** A path that cannot justify its separateness from a neighbour is a merge candidate, not a valid destination.
+
+Three views of the same truth: the `SKILL.md` *Where to Write* table is the quick-reference, this map is the authority, and `vault-layout.md` is the physical tree. When they disagree, this map wins and the others are fixed to match.
+
+## How to read a row
+
+- **Trigger** — the observable condition that sends content here. If two rows could both fire, the more specific trigger wins.
+- **What lands** — the unit of content written.
+- **Distinct because** — the one reason this path is not merged into its nearest neighbour. This is the load-bearing column; a row without it is a bug.
+- **Method** — the dominant REST verb (see `api-reference.md` for mechanics).
+
+---
+
+## inbox/ — unsorted intake
+
+| Path | Trigger | What lands | Distinct because | Method |
+|------|---------|------------|------------------|--------|
+| `inbox/captures/inbox.md` | "Save this, sort later" — destination genuinely unknown at capture time | One date-prefixed line | The only path whose contract is *deferred routing*; everything else here has a known home | POST |
+| `inbox/imports/<slug>.md` | Raw external material dropped in wholesale (export, paste, dump) | The raw artifact, unedited | Holds un-triaged *bulk*, vs `captures` which holds single lines | PUT |
+| `inbox/processing-log/YYYY-MM-DD.md` | An inbox item is routed to its real home | One line: `<original> → <destination path>` | Audit trail of moves — never holds memory itself, only the record of routing | POST |
+
+Captures and imports are temporary by contract. Triage drains them into the homes below and logs the move; the original is left until Jason okays deletion.
+
+## journal/ — the one append-only time-series stream
+
+Rollups are coarser-grained journal entries over the same timeline, so they live in the same tree. There is no separate `reviews/` tree.
+
+| Path | Trigger | What lands | Distinct because | Method |
+|------|---------|------------|------------------|--------|
+| `journal/daily/YYYY-MM-DD.md` | First agent activity on a given day | `## Agent Log` line(s) + day notes | Finest grain; the only journal note PATCHed repeatedly within its period | PATCH (auto-create) |
+| `journal/weekly/YYYY-Www.md` | First substantive session of a new ISO week — **opt-in**, offer first | Light digest: open `active/` threads, aging inbox, week's scope changes | Coarser than daily, finer than monthly; ISO-week grain | PUT |
+| `journal/monthly/YYYY-MM.md` | First substantive session of a new month — offered alongside Vault Health | Month digest, same shape as weekly | Month grain; separate cadence and trigger from weekly | PUT |
+| `journal/quarterly/YYYY-Qn.md` | **Manual / on request only** | Quarter-scale narrative review | Strategic grain; never auto-fires | PUT |
+| `journal/annual/YYYY.md` | **Manual / on request only** | Year-scale narrative review | Coarsest grain; never auto-fires | PUT |
+| `journal/templates/` | Bootstrap only (seeded from plugin masters) | Note templates | Holds templates, not journal content; never a runtime routing target | PUT (seed) |
+
+## projects/ — work with an end state
+
+Lifecycle folders; `status:` frontmatter MUST equal the folder name (the linter checks this).
+
+| Path | Trigger | What lands | Distinct because | Method |
+|------|---------|------------|------------------|--------|
+| `projects/active/<slug>.md` | Work in motion now | Project note (Status PATCHed fresh) | Default state for anything being worked | PUT + PATCH |
+| `projects/incubating/<slug>.md` | Idea captured, work not started | Project note | Pre-work; promote to `active/` when work begins | PUT |
+| `projects/on-hold/<slug>.md` | Paused but still tracked | Project note | Resumable; distinct from `archived` (which is terminal) | PUT |
+| `projects/archived/<slug>.md` | Done, abandoned, or rolled up | Project note | Terminal; kept for history, never deleted | PUT |
+
+**Project vs area:** has an end state → `projects/`. Never "done" → `areas/`.
+
+## areas/ — standing responsibilities, no finish line
+
+| Path | Trigger | What lands | Distinct because | Method |
+|------|---------|------------|------------------|--------|
+| `areas/<domain>/<slug>.md` | Ongoing domain Jason maintains indefinitely (`<domain>`: business/personal/learning/systems) | Area note | No end state — the one thing that disqualifies it from `projects/` | PUT |
+
+## resources/ — reference material about the world
+
+| Path | Trigger | What lands | Distinct because | Method |
+|------|---------|------------|------------------|--------|
+| `resources/people/<name>.md` | A fact about a specific person | Person note (kebab-case slug) | Keyed to a person, not a topic or event | PUT / PATCH |
+| `resources/concepts/<slug>.md` | A reusable concept/idea Jason wants on file | Concept note | An idea, vs a `reference` which is an external source | PUT |
+| `resources/references/<slug>.md` | An external source/link worth keeping | Reference note | Points outward (a source), vs `concepts` (an idea) | PUT |
+| `resources/meetings/YYYY-MM-DD-<slug>.md` | Notes/recap tied to a specific meeting or call | Meeting note; mirror decisions to `decisions/by-date/`, commitments to the project | Event-anchored to a meeting, vs a project's ongoing thread | PUT |
+
+## decisions/ — non-obvious decisions (ADR)
+
+| Path | Trigger | What lands | Distinct because | Method |
+|------|---------|------------|------------------|--------|
+| `decisions/by-date/YYYY-MM-DD-<slug>.md` | A non-obvious decision worth recording | ADR: Context → Decision → Consequences | The chronological system of record for decisions | PUT |
+
+**Mirror, don't duplicate:** if the decision belongs to an existing `projects/active/` note, PATCH a `[[wikilink]]` to the ADR under that project's `## Key Decisions`. No matching project → skip the mirror; the by-date ADR stands alone.
+
+## _agent/ — the agent's own working substrate
+
+| Path | Trigger | What lands | Distinct because | Method |
+|------|---------|------------|------------------|--------|
+| `_agent/echo-vault.md` | Bootstrap / schema migration only | Marker: `schema_version`, bootstrap date | Plugin-owned probe; never hand-edited | GET / PUT |
+| `_agent/context/current-context.md` | Active scope changes; task focus shifts | `## Scope`, `## Scope History`, priorities | Single *live* scope pointer, vs episodic which is a *past* record | PATCH / PUT |
+| `_agent/memory/semantic/operator-preferences.md` | A preference/pattern about Jason | Append under `## Observations`; promote to `## Fact / Pattern` when stable | The one curated profile; distinct from ad-hoc semantic notes | PATCH |
+| `_agent/memory/semantic/<slug>.md` | A durable fact/pattern that isn't a Jason-preference | Semantic note | Timeless fact, vs episodic (time-stamped event) and working (transient) | PUT |
+| `_agent/memory/episodic/<slug>.md` | A record of *what happened, when* | Episodic note | Anchored to an event in time; not a standing fact | PUT |
+| `_agent/memory/working/<slug>.md` | Short-lived state needed only for the current effort | Working note | Explicitly transient/time-boxed; safe to go stale | PUT |
+| `_agent/sessions/YYYY-MM-DD-HHMM-<slug>.md` | A substantive session ends (decisions/artifacts/commitments) | Session log (see template) | Per-session record; the unit loading Step 4 scans | PUT |
+| `_agent/health/YYYY-MM-vault-health.md` | First substantive session of a month (Vault Health pass) | Health-audit findings | Agent self-maintenance about vault integrity — NOT Jason's work narrative, so not in `journal/` | PUT |
+| `_agent/heartbeat/last-session.md` | End of every session, after the session log is written | One line: `<session-log-path> @ <ISO-timestamp>` | O(1) orientation pointer read first at load (Step 4); overwritten, never grows | PUT |
+| `_agent/templates/` | Bootstrap only (seeded from plugin masters) | Canonical note templates | Holds templates, not memory; never a runtime routing target | PUT (seed) |
+| `_agent/skills/active/<slug>.md` | Jason authors/installs a skill and wants it catalogued | Skill capability entry | Catalogs a *capability*, vs `projects/` which tracks the *build effort* | PUT |
+| `_agent/skills/archived/<slug>.md` | A catalogued skill is retired | Skill entry (moved from `active/`) | Terminal state of the skill catalog | PUT |
+
+---
+
+## Retired paths — explicitly never written
+
+Listed so they are recognised as dead and never recreated. Any one of these appearing in a live vault is a migration miss (see `bootstrap.md` Migrations).
+
+| Path | Status | Where it went instead |
+|------|--------|-----------------------|
+| `reviews/` (weekly/monthly/quarterly/annual) | Retired in schema 2 | Journal rollups → `journal/{weekly,monthly,quarterly,annual}/`; vault-health → `_agent/health/` |
+| `decisions/by-project/` | Retired in schema 1 | ADR mirrored as a `[[wikilink]]` under the project's `## Key Decisions` |
+| `archive/` (top-level) | Never existed | Project archival → `projects/archived/`; skill archival → `_agent/skills/archived/` |
+| `CLAUDE.md` / `BOOTSTRAP.md` / `STRUCTURE.md` / `index.md` (in-vault) | Retired in schema 1 | All control logic lives in the plugin (`references/`), not the vault |
+
+## Routing decision tree (the calls that get mis-made)
+
+1. **Destination unknown right now?** → `inbox/captures/`. Known? → route directly; never park a known fact in the inbox.
+2. **Is it about Jason's work over time?** → `journal/` (pick the grain by cadence). **About the vault's mechanical health?** → `_agent/health/`. These two look similar monthly but answer different questions.
+3. **Does the effort have an end state?** → `projects/` (folder = `status:`). **No finish line?** → `areas/`.
+4. **A fact about the world:** timeless → `semantic/`; a thing that happened → `episodic/`; needed only for now → `working/`. A fact about a *person* → `resources/people/`.
+5. **A decision:** always `decisions/by-date/`; mirror into a project only if one already exists.
+6. **A capability (skill/plugin):** `_agent/skills/` catalogs the capability; `projects/` tracks building it. Both can exist for the same skill.
@@ -11,8 +11,12 @@
 │   ├── captures/      ← quick captures (inbox.md), date-prefixed lines
 │   ├── imports/       ← raw imported material
 │   └── processing-log/
-├── journal/
+├── journal/          ← one append-only time-series stream; rollups are coarser journal entries, NOT a separate reviews/ tree
 │   ├── daily/         ← YYYY-MM-DD.md (has an "Agent Log" section)
+│   ├── weekly/        ← YYYY-Www.md (ISO week, opt-in rollup)
+│   ├── monthly/       ← YYYY-MM.md (monthly rollup)
+│   ├── quarterly/     ← YYYY-Qn.md (manual / on request)
+│   ├── annual/        ← YYYY.md (manual / on request)
 │   └── templates/
 ├── projects/         ← lifecycle: incubating → active → on-hold/archived
 │   ├── active/        ← current work (status: active)
@@ -29,7 +33,7 @@
 │   └── decision-template.md
 │   (decisions/by-project/ is retired and not created —
 │    mirror an ADR into a project's `## Key Decisions` heading instead)
-├── reviews/           ← weekly / monthly / quarterly / annual
+│  (reviews/ is retired — journal rollups live under journal/; vault-health audits under _agent/health/)
 └── _agent/
    ├── echo-vault.md  ← bootstrap marker: schema_version + bootstrap date (plugin-owned; the "is this vault set up?" probe)
    ├── context/       ← current-context.md and task bundles
@@ -38,12 +42,13 @@
    │   ├── episodic/  ← what happened, when
    │   └── semantic/  ← durable facts/patterns (operator-preferences.md)
    ├── sessions/      ← YYYY-MM-DD-HHMM-<slug>.md
+    ├── health/        ← YYYY-MM-vault-health.md (monthly self-maintenance audit; NOT a journal entry)
    ├── templates/     ← canonical note templates
    ├── skills/        ← active / archived
    └── heartbeat/     ← single-line pointers (e.g. last-session.md → most-recent session log path)
 ```

-**Heartbeat:** `_agent/heartbeat/last-session.md` is a one-line pointer file an agent MAY write at session end (`<session-log-path> @ <ISO-timestamp>`). Reading it at session start is cheaper than listing the sessions directory; use it as a hint, not a source of truth — fall back to the directory listing if it's missing or stale.
+**Heartbeat:** `_agent/heartbeat/last-session.md` is a one-line pointer (`<session-log-path> @ <ISO-timestamp>`) the **session-logging procedure writes (PUT, overwrite) at session end** and the **loading procedure reads first (Step 4)** as an O(1) shortcut to the latest session log. It is a hint, not a source of truth — fall back to the `sessions/` directory listing if it's missing or stale. Because it's PUT-overwritten, it never grows or duplicates.

 **Slug rules:** kebab-case, ASCII only, truncate to ~40 chars.