From 2146b909f81caa0f5141c4f9eb750ef2f457230d Mon Sep 17 00:00:00 2001
From: Markus Fritsche <mfritsche@reauktion.de>
Date: Wed, 13 May 2026 04:47:01 +0000
Subject: [PATCH] =?UTF-8?q?docs/PHASE4:=20analyze=20=E2=80=94=20surface=20?=
 =?UTF-8?q?confirmed,=20counter=20strategy=20locked?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A1. history.lua surface lines up cleanly for the memory additions —
    no structural refactor; pure additive functions mirroring the
    session pattern.

A2. Counter persistence: scan at open, cache next_id in handle.
    O(n) load (n bounded by curation, ~hundreds), no sidecar file.
    Persisted ids let forget-tombstones target items even across
    restarts.

A3. System-prompt suffix order locked: DEFAULT (carrying Phase 2 MCP
    block baked in) → Phase 4 [background] → Phase 3 NORRIS. Token
    cost measured: default ~174 toks, +NORRIS ~364 toks, +NORRIS+2KB
    background ~865 toks. Well within typical context budgets.

No manifest amendments needed — §3/§5 already match. Findings recorded
inline as Phase 7 anchors.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/PHASE4.md | 35 ++++++++++++++++++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/docs/PHASE4.md b/docs/PHASE4.md
index 98d6beb..8da394c 100644
--- a/docs/PHASE4.md
+++ b/docs/PHASE4.md
@@ -2,9 +2,42 @@
 
 **Project:** aish — AI-augmented conversational shell
 **Document:** Phase 4 Requirements, Architecture & Design Decisions
-**Status:** Formulate (pre-analyze)
+**Status:** Analyze (formulate complete; current tree at `bea7175` probed)
 **Date:** 2026-05-13
 
+**Analyze findings (2026-05-13):**
+
+A1. **history.lua surface is clean** — `M.open`/`Session:append`/
+    `Session:close`/`M.load`/`M.list_sessions`. The memory functions
+    can mirror this exactly: `M.open_memory`/`memory:add`/
+    `memory:forget`/`memory:close`/`M.load_memory`. No structural
+    refactor needed; pure additions.
+
+A2. **Counter persistence — scan at open, cache in handle.** Phase 1's
+    session log writes a `{"meta":{...}}` header on first creation but
+    doesn't track entry-id (turns aren't numbered). For memory, the
+    monotonic id is needed for forget-targeting. Cheapest correct
+    approach: on `M.open_memory`, read all lines once, find the max
+    `id` field present (skipping the meta header if any), cache as
+    `handle.next_id`. Subsequent `add` calls increment in-memory and
+    persist on the next append. O(n) at open is acceptable since n is
+    bounded by user curation (~hundreds, not millions). No sidecar.
+
+A3. **System-prompt suffix order, post-analyze**: actual current
+    composition is `DEFAULT_SYSTEM_PROMPT` (which has Phase 2 MCP
+    guidance already baked-in as a static block) → optional `NORRIS`
+    dynamic suffix. The Phase 2 MCP block is NOT computed dynamically
+    — it's part of DEFAULT_SYSTEM_PROMPT. So Phase 4's `[background]`
+    block lives between DEFAULT and NORRIS. Token cost measured:
+    - DEFAULT: 697 chars (~174 tokens)
+    - DEFAULT + NORRIS: 1458 chars (~364 tokens)
+    - DEFAULT + 2KB background + NORRIS: ~3460 chars (~865 tokens)
+    Within typical 4-8K context budgets.
+
+These findings don't require manifest changes — the §3 module-changes
+table and §5 injection mechanism already match. Recording the
+measurements here so verify (Phase 7) has anchors.
+
 PHASE0 is the locked substrate; PHASE1, PHASE2, PHASE3 are layered on top.
 This manifest specifies what Phase 4 adds — **cross-session memory** — and
 the user-facing surface for managing it.