hypomnema 1.0.1 → 1.2.0

package/templates/hypo-guide.md

@@ -59,12 +59,23 @@ Over time, new sources *update* pages more than they *create* them — that's wh
 1. Read root `hot.md` → identify active project
 2. If `cwd` matches `projects/<name>/index.md`'s `working_dir:` field → read `projects/<name>/session-state.md` first
 3. Read `projects/<name>/hot.md` for background context
-4. Offer: "Continuing [X] from last session — shall we pick up?"
+4. **Your first response must lead with the resume**: a one-line summary of last session + the concrete next task(s) from `session-state.md`, then "Continuing [X] — shall we pick up?". Do not wait for the user to ask; this is mandatory whenever a project matched (not a soft offer).
 
 ### Session Close
 
 Trigger: explicit close mention, `/compact` request, or context limit approaching.
 
+**Auto-trigger rule**: when the user sends a natural-language close signal — "세션 마무리하자", "오늘 여기까지", "이만 종료", "wrap up", "signing off", or equivalent — run the session close checklist immediately without waiting for an explicit `/compact` or `/hypo:crystallize`. If the intent is ambiguous, confirm with a single question before proceeding.
+
+**Proactive close offer** (ADR 0022 Layer 1): even when the user gives no close signal, offer to wrap up once a task is truly done — don't make them remember to. Fire `AskUserQuestion` **at the end of the assistant turn in which you report a task complete or verified**, when both hold:
+
+1. The session did substantial work — file mutations or multi-step changes, not Q&A only.
+2. The current user request did not already include a next task or tell you not to close.
+
+Do **not** treat these as completion: plan approvals, clarification answers, permission grants, progress updates, partial findings, or mid-task checkpoints. A "좋아요" / "감사합니다" / "ok" following any of those is *not* a close signal — only offer after a genuine final completion/verification report.
+
+Ask: *"이 작업이 마무리되었나요? 세션을 정리(crystallize)할까요?"* with options **[세션 마무리 / 계속 작업]**. On **세션 마무리** → run the session close checklist (or invoke `/hypo:crystallize`). On **계속 작업** → continue and do not re-ask until the next task completes. Ask at most once per completed task; never loop. (Decline simply ends the turn — Layer 3's Stop-chain only blocks on an explicit close signal, so no repeated prompts occur.)
+
 1. Update `projects/<name>/session-state.md` (next tasks, overwrite)
 2. Update `projects/<name>/hot.md` (what was done, ≤500 words, overwrite)
 3. Append to `projects/<name>/session-log/YYYY-MM.md` (narrative entry, append-only)
@@ -74,6 +85,8 @@ Skip session close for: single bug fix, single-file edit, Q&A only.
 
 ### Ingest (external source → wiki)
 
+**Auto-trigger rule**: after any `WebFetch` / `WebSearch` that yields new knowledge relevant to the current task, run `/hypo:ingest` immediately — do not wait for the user to ask.
+
 1. Save raw source to `sources/<slug>.<ext>` (never edit after)
 2. Read and synthesize
 3. Update or create pages in `pages/` with frontmatter `source: <slug>`
@@ -85,6 +98,7 @@ Skip session close for: single bug fix, single-file edit, Q&A only.
 1. Read `index.md` first
 2. Cross-reference related pages
 3. Synthesize answer — cite `[[page-slug]]` links
+4. **On miss**: research externally (`WebFetch` / `WebSearch`), then auto-ingest — omitting `/hypo:ingest` after external research is a defect
 
 ---
 
@@ -111,6 +125,32 @@ projects/<name>/
 
 Add to root `hot.md` active projects table.
 
+#### Auto-project offer (ADR 0023)
+
+When SessionStart / CwdChanged injects a line like
+`[WIKI: cwd '<name>'에 매칭되는 프로젝트가 없습니다. 자동 생성할까요? (Y/n)]`,
+the current working directory is a real project (git repo + a project marker
+like `package.json`) that has no matching wiki project. **Act on it — do not
+ignore it:**
+
+1. Ask the user with `AskUserQuestion` (or a plain Y/n question) whether to
+   create the project.
+2. **On Yes** — run the scaffold helper once (it substitutes tokens, creates
+   the project files, adds the root `hot.md` row, and logs the entry):
+   ```
+   node <pkg-root>/scripts/lib/project-create.mjs --name <slug> --working-dir "$(pwd)"
+   ```
+   Then tell the user: "Created project `<name>` at
+   `~/hypomnema/projects/<name>/`. Edit `index.md` to refine." Do **not** hand-write
+   the five files — the helper keeps substitution and registration consistent.
+3. **On No** — record the refusal so this cwd is never offered again: append an
+   entry to `~/hypomnema/.cache/project-suggestions.json` under `skips`:
+   ```json
+   { "skips": [ { "cwd": "<absolute cwd>", "declined_at": "<ISO date>", "reason": "user_decline" } ] }
+   ```
+   (preserve any existing `skips` / `cooldowns` keys). The hook reads this and
+   stays silent for that cwd permanently.
+
 ### Close a project
 
 1. Write final `session-state.md` (mark as complete)
@@ -144,3 +184,25 @@ ADRs are immutable once accepted. Mark deprecated/superseded but never edit cont
 - **Weekly**: check `pages/open-questions.md` for resolved items
 - **Monthly**: review `log.md` for source-starved weeks (< 1 external source)
 - **On schema change**: bump `SCHEMA.md` version, update this guide if layout changed
+
+---
+
+## 8. Observability & citation convention
+
+Hypomnema v1.1.0 ships an **autonomy score** so you can see whether the wiki is actually being used per session, rather than just trusting that it is.
+
+- **Citation:** when a response uses a wiki page, link it inline as `[[page-slug]]`. The audit script counts citations as one signal of "the wiki was actually consulted".
+- **Tools that count:** `Grep`, `WebSearch`, `WebFetch`, and any `/hypo:query` / `/hypo:ingest` / `/hypo:feedback` invocation in the transcript.
+- **Classification (heuristic v0):**
+  - `normal` — at least one search, no missed URL ingests
+  - `search-0` — zero search/query in the session
+  - `search-many` — five or more searches (sign of heavy retrieval; may indicate missing synthesis)
+  - `ingest-missed` — URLs appeared in conversation but no `/hypo:ingest` ran
+  - `staleness-skip` — session older than the audit window (default 30d)
+- **Where it lives:**
+  - Per-session transcript index: `<hypo-root>/.cache/sessions/index.jsonl` (written by the Stop hook `hypo-session-record.mjs`).
+  - Fallback source: `~/.claude/projects/<encoded>/*.jsonl` (used when the index is empty — see ADR 0019 if present in your wiki).
+  - Reports: `journal/weekly/<YYYY-Www>.md` (spec §6.4 SoT), generated by `node scripts/weekly-report.mjs --write`.
+- **Definitions:** the 0% / 100% endpoints, the formal score sketch, and open questions live in `pages/observability/_index.md`.
+
+Use `/hypo:audit` for a quick read of recent sessions; pass `--write` to commit the weekly report into the wiki.

package/templates/hypo-help.md

@@ -38,7 +38,7 @@ Quick reference for all `/hypo:*` commands.
 
 | Command | Description |
 |---------|-------------|
-| `/hypo:crystallize` | Find synthesis candidates — tag clusters, unlinked pages, drafts |
+| `/hypo:crystallize` | Close a session (steps 1~6 hard gate) and, on request, surface synthesis candidates (steps 7~11) — tag clusters, unlinked pages, drafts |
 | `/hypo:verify` | Review overdue verify_by deadlines |
 | `/hypo:lint` | Validate frontmatter and `[[wikilinks]]` |
 | `/hypo:graph` | Generate link graph (json / mermaid / dot) |

package/templates/pages/observability/_index.md

@@ -0,0 +1,77 @@
+---
+title: Observability Index
+type: reference
+updated: YYYY-MM-DD
+tags: [observability, autonomy, wiki-health]
+---
+
+# Observability
+
+> Tracks how often and how well the wiki is used per session. Score = proxy for autonomous wiki engagement (not ground truth).
+
+---
+
+## 1. Data flow
+
+```
+Stop hook (hypo-session-record.mjs)
+    │  appends one JSONL entry per session
+    ▼
+.cache/sessions/index.jsonl
+    │
+    ▼
+scripts/session-audit.mjs   ← per-session metrics + classification
+    │
+    ▼
+scripts/weekly-report.mjs   ← weekly autonomy score
+    │
+    ▼
+journal/weekly/<YYYY-Www>.md   (spec §6.4 SoT)
+```
+
+---
+
+## 2. Session classification
+
+| Class | Rule |
+|---|---|
+| `staleness-skip` | `recorded_at` older than `--max-age-days` (default 30) |
+| `ingest-missed` | `urls >= 2` and `ingest_count == 0` |
+| `search-many` | `search_count >= 5` |
+| `search-0` | `search_count == 0` |
+| `normal` | otherwise |
+
+Counted tools: `Grep`, `WebSearch`, `WebFetch`. Counted commands: `/hypo:query`, `/hypo:ingest`, `/hypo:feedback`.
+
+---
+
+## 3. Autonomy score formula (heuristic v0)
+
+Score is clamped to `[0, 100]`. `staleness-skip` sessions are excluded.
+
+```
+numerator   = Σ min(search_count, 3) + ingest_count × 3 + feedback_count × 2
+denominator = Σ 1 + (urls > 0 ? min(urls, 5) × 2 : 0)
+score       = clamp(round(numerator / denominator × 100), 0, 100)
+```
+
+- Each real session contributes 1 to denominator (baseline expectation).
+- URLs raise the bar: each external URL is a missed-ingest opportunity (weight 2, capped at 5).
+- Ingest (weight 3) and feedback (weight 2) are the strongest positive signals.
+- Search (weight 1, capped at 3) is a weaker signal.
+
+---
+
+## 4. Four-week baseline plan
+
+Capture v0 scores for 4 weeks before introducing LLM-judge classification or changing formula weights. Goal: establish a baseline before tuning.
+
+| Week | Score | Notes |
+|---|---|---|
+| <!-- YYYY-Www --> | <!-- % --> | <!-- first run --> |
+
+---
+
+## 5. Privacy
+
+Weekly reports emit only `session_id` plus aggregate counts — no transcript content, no URLs, no tool inputs. Transcripts live under `~/.claude/projects/` or `.cache/sessions/`, excluded by `.hypoignore`.

package/templates/projects/_template/index.md

@@ -2,9 +2,9 @@
 title: <project-name> — Index
 type: project-index
 status: active
-started: YYYY-MM-DD
+started: <started>
 updated: YYYY-MM-DD
-working_dir: ~/path/to/project
+working_dir: <working_dir>
 tags: [project]
 ---
 

package/templates/projects/_template/prd.md

@@ -2,7 +2,7 @@
 title: <project-name> — PRD
 type: prd
 status: active
-started: YYYY-MM-DD
+started: <started>
 updated: YYYY-MM-DD
 tags: [project, prd]
 ---