docs/PHASE9: formulate — project-local config overlay (.aish.lua)

Phase 9 formulate manifest + PHASE0 §11 amendment (adds Phase 9 row)
+ PHASE0 §10 amendment (config resolution order now references Phase
9's overlay step). Substrate-touch lands same commit per CLAUDE.md §3.

Four pillars:

  1. .aish.lua walk-up from cwd; stops at $HOME or filesystem root.
     First found file becomes the project layer. Absence = no-op.

  2. Shallow merge over user config: project top-level keys REPLACE
     user keys. Predictable; deep merge surprises with array/table
     semantics. Users compose full blocks explicitly.

  3. Trust prompt + sha256-pinned persistence in ~/.aish/trusted-
     projects (JSONL, mode 0600). First encounter prompts; subsequent
     startups load only if recorded sha matches. Content change ->
     re-prompt. Matches direnv-allow security posture.

  4. :config show meta — lists each source path with the top-level
     keys it contributed + sanitized effective config dump
     (token-bearing fields masked).

Key design decisions documented:

  - Trust mechanism is explicit (not default-trust-all-cwds) —
    .aish.lua runs arbitrary Lua via dofile; hostile cloned-repo
    case is a real concern.
  - $HOME boundary on walk-up — don't search /tmp or /. Repos
    outside $HOME get no project layer.
  - Reload on cd: NO. Config resolved at startup only.
  - sha256 via shelled `sha256sum` (POSIX-portable; avoid
    vendoring a Lua impl).

§9 risk table covers: hostile repo (trust prompt), corrupted trust
file (best-effort skip), updated repo (sha mismatch re-prompts),
dofile errors (pcall-protected), walk-up safety ($HOME boundary).

6 open questions for analyze:
  Q-P1 — trust prompt before/after startup status
  Q-P2 — sha256sum vs openssl dgst (baseline)
  Q-P3 — log walk-up path?
  Q-P4 — rl.readline safe at startup?
  Q-P5 — :config show full vs top-level
  Q-P6 — project-set secrets.vault security

Scope confirmed via AskUserQuestion: project-local overlay (chosen
over cost preflight enforcement and cross-session cost persistence,
both deferred as Phase 10 candidates per §11).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/PHASE0.md

@@ -296,6 +296,12 @@ Config path resolution order:
 3. `~/.config/aish/config.lua`
 4. `./config.lua` (development fallback)
 
+Phase 9 adds a project-local overlay step AFTER the user config resolves:
+walks up from cwd looking for `.aish.lua` (stops at `$HOME` or `/`),
+prompts to trust on first encounter, sha256-pins the trust record, and
+shallow-merges the project's top-level keys onto the user config. See
+`docs/PHASE9.md`.
+
 **Cwd-relative module resolution.** Phase 0 prepends `./?.lua;./vendor/?.lua`
 to `package.path`, so `luajit main.lua` must be invoked with the repo
 root as cwd. Cwd-independent resolution (relative to the script's own
@@ -318,6 +324,7 @@ from somewhere else.
 | **6** | Tree-sitter syntax highlighting hooks, diff-aware code injection, project-level context (file tree summary) |
 | **7** | Cost / usage observability: broker captures `usage` + `cost`; per-session accumulator on ctx; `:cost` reporter; optional warn thresholds |
 | **8** | Accurate tokenization: per-endpoint `/tokenize` probe (cached); `broker.token_count`; `Context:estimate_tokens` widened; `:cost detail` est-vs-actual annotation |
+| **9** | Project-local config overlay (`.aish.lua` walk-up from cwd to $HOME, sha256-pinned trust prompt, shallow merge over user config); `:config show` meta |
 
 ---