mishkan-harness 0.2.5 → 0.2.7

package/docs/design/MISHKAN_decisions.md

@@ -35,14 +35,19 @@ runtime selection — for no benefit given the target. Removing it simplifies th
 build materially.
 
 **Implications:**
-- Three tiers only: Opus, Sonnet, Haiku.
+- Tier *values* the hook accepts: Fable, Opus, Sonnet, Haiku — but **Fable is
+  dormant** (0 agents) since its 2026-06-12 suspension (amendment below). Live
+  distribution is Opus 9 · Sonnet 22 · Haiku 14.
+  - **Fable (0 — dormant):** briefly the producing specialists of Mishmar + Migdal
+    (2026-06-11 amendment), reverted to Sonnet on 2026-06-12 (suspension amendment).
+    The value stays valid so the tier can be re-enabled if access is restored.
   - **Opus (9):** Nehemiah, Bezalel, all Team Leads, Jehonathan.
-  - **Sonnet (22):** every agent that **writes code/config into the codebase**
-    (precision matters on Y4NN's code) + senior specialists + research
-    clarify/formulate/research. Includes all implementation specialists —
-    Hizkiah, Salma, Hiram, Obed, Asaph, Palal, Meremoth, Hanun — plus Nathan,
-    Zadok, Shallum, Ira, Benaiah, Joab, Hushai, Oholiab, Meshullam, Seraiah,
-    Joah, Jakin, Ezra, Caleb.
+  - **Sonnet (22):** every agent that **writes code/config into the
+    codebase** (precision matters on Y4NN's code) + senior specialists + research
+    clarify/formulate/research. Includes implementation specialists Hizkiah,
+    Salma, Hiram, Obed, Asaph, Palal, Meremoth, Hanun — plus Nathan, Zadok,
+    Shallum, Ira, Benaiah, Joab, Hushai, Oholiab, Meshullam, Seraiah, Joah,
+    Jakin, Ezra, Caleb.
   - **Haiku (14):** agents that do **not** write code — QA (Uriah, Jahaziel),
     all Team Reporters, pure advisors (Deborah, Rehum), Sefer team-layer docs
     (Shevna), research summarise/evaluate/report (Shaphan, Shemaiah, Baruch).
@@ -50,6 +55,42 @@ build materially.
 **Amendment 2026-05-27:** original split put implementation specialists on
 Haiku for cost. Revised on Y4NN's preference — Sonnet writes his code more
 precisely. Haiku retained only where no code is written (evaluate/collect/advise).
+
+**Amendment 2026-06-11 (four-tier — Fable 5 for Migdal + Mishmar specialists):**
+the eight producing specialists of the infrastructure (Migdal) and security
+(Mishmar) teams move from Sonnet to **Fable 5** (`claude-fable-5`). Fable 5 is
+positioned for complex, long-horizon work — threat modelling, infra topology,
+hardening — which is exactly these agents' load. Note the selector here is
+**reasoning load, not code-writing**: that is why Hushai (a security *advisor* that
+writes no code) qualifies for Fable on the strength of its analysis depth, whereas
+the Sonnet tier's selector is *code-writing precision on Y4NN's code* and the Haiku
+tier's is *no reasoning or code at all* (collect/evaluate/advise-lite). The two
+"advisor" agents split on exactly this axis — Hushai (reasoning-heavy security
+counsel) → Fable; Rehum (health/SRE advice-lite) → Haiku. Scope is deliberate: team
+**leads** (Phinehas, Eliashib) stay Opus (orchestration/judgement), and the
+**reporters** (Maaseiah, Zaccur) stay Haiku (collect only). This amends "three tiers
+only" to four; the "Claude Code models only" decision is unchanged (Fable 5 is a
+Claude model). Cost: Fable 5 is **$10 / $50 per MTok** — above Opus-tier — and is
+covered by plan limits until **2026-06-22**, then usage credits (an accepted cost).
+Verified before rollout: `fable` is a valid bare subagent alias resolving to
+`claude-fable-5` (confirmed against the API-recorded model field in a subagent
+transcript). The `model-route.py` hook's `VALID` set, the `observability-log` schema
+`model_tier` enum, and the `usage_parser.py` price table were extended for the new
+tier in the same change.
+
+**Amendment 2026-06-12 (Fable suspended — reverted to Sonnet):** less than a day
+after the four-tier amendment landed, Anthropic disabled Claude Fable 5 (and Mythos 5)
+for **all customers** under a US export-control directive
+(anthropic.com/news/fable-mythos-access, 2026-06-12 17:21 ET) — `claude-fable-5` now
+hard-errors on spawn (verified: a subagent routed to it returns "model … may not
+exist or you may not have access", 0 tokens). The eight Migdal+Mishmar specialists are
+therefore **reverted to Sonnet** (frontmatter + `model-routing.yaml`), restoring the
+pre-amendment distribution (Opus 9 · Sonnet 22 · Haiku 14). The four-tier **mechanism
+is kept dormant** — `fable` stays in the hook's `VALID` set, the telemetry enum, and
+the price table — so re-enabling is a one-line routing change if Anthropic restores
+access ("working to restore access as soon as possible"). This episode is the concrete
+motivation for D-017 (user-editable dynamic tier routing): model availability can
+change abruptly, and routing should adapt without a code change + reinstall.
 - Tier declared per-agent in frontmatter `model:` field.
 - Overridable centrally via `~/.claude/mishkan/config/model-routing.yaml`.
 - Cost discipline lives entirely in tier assignment + prompt caching +
@@ -167,6 +208,8 @@ small extra Neo4j. The curated library is small and regenerable
 bulk seeding bursts embedding calls and cloud free-tier embeddings 429
 (RESOURCE_EXHAUSTED).
 
+*(Superseded on the work-store axis by D-012: per-project physical isolation. The `cognee` MCP alias now points to a per-project Ladybug store, not port `:7777`. Port `:7777` is repurposed as `cognee-memory`, holding only `claude_code_memory`.)*
+
 ## D-008 — Three-layer memory epistemology: structure / project semantics / curated cross-project (added 2026-06-05)
 
 **Decision:** MISHKAN's knowledge surface is split into **three physically
@@ -356,6 +399,8 @@ introduced to protect.
 (curated vs work split) by adding a third epistemic layer on the same
 discipline.
 
+*(The "Cognee work (`:7777`)" row in the table above describes the model as of D-008. Superseded on the work-store axis by D-012: the `cognee` MCP alias now points to a per-project Ladybug store on its own port; `:7777` is repurposed as `cognee-memory`, session memory only.)*
+
 ## D-009 — Graph-first PreToolUse gate for the five code-writing specialists (added 2026-06-05)
 
 **Decision:** introduce a MISHKAN PreToolUse hook — `pre-tool-knowledge-route.py` —
@@ -612,7 +657,7 @@ worth reaching for.
   `mishkan-blast-radius`, `mishkan-knowledge-gap-discovery`,
   `mishkan-standards-rollout`. Adding an 11th forces a retirement vote.
 - **4 team-level workflows per team.** Current shipped count varies by team
-  (Chosheb 1, Panim 1, Yasad 2, Mishmar 1, Migdal 2, Sefer 1). Spare slots
+  (Chosheb 1, Panim 2, Yasad 3, Mishmar 1, Migdal 2, Sefer 1). Spare slots
   per team are deliberately left open — candidates compete for them at
   PM+CTO review, not on a team lead's word.
 
@@ -717,6 +762,52 @@ upcoming-use justification.
   candidate; a determined push can word-paint around it. Mitigation: the
   CTO half of the gate has explicit authority to reject on shape.
 
+### Amendment (2026-06-10) — loop-until-QA-passes feature-ship workflows
+
+**Trigger.** The engineer observed that the designed Lead → Specialist → QA
+collaboration was not enforced in practice — the main session dispatched
+specialists directly and self-graded, bypassing the chain, with no loop driving
+work to a QA-clean state. The remedy is two-layer: a cross-cutting discipline in
+`team-lead-craft` §6.1 (all six teams), and a deterministic, unskippable workflow
+form where stakes justify it.
+
+**Portfolio change (PM + CTO joint brief).**
+
+- **Two NEW team workflows:** `yasad-feature-ship`, `panim-feature-ship`.
+- **Three AMENDED workflows** gain a bounded retry loop in place (no new slot):
+  `chosheb-feature-ship` (loop-until-ready), `mishmar-security-gate` and
+  `migdal-infra-change` (conservative — one remediation-proposal cycle then
+  escalate). Sefer is covered by the discipline layer only (no product to gate —
+  a workflow there would be anti-pattern #4).
+
+**Brief, per the proposal format.**
+
+- *Problem.* The chain is bypassable; QA convergence is not enforced.
+- *Fan-out shape.* `route → implement → parallel orthogonal QA panel →
+  loop-until-zero-blockers (cap 3; 1–2 conservative for security/infra) →
+  escalate`. ≥6 agents across panel × cycles.
+- *Termination predicate.* Zero `blocker`-severity findings (keys off the
+  existing structured QA verdicts — Uriah/Jahaziel agent contracts and the
+  existing workflow `{ready}`/`{decision}`/`{safe}` fields; no new contract).
+- *Expected fire-count.* High — once per shipped feature on the active team;
+  comfortably clears the ≥10/quarter bar.
+- *Anti-pattern self-check.* #1 cleared (termination predicate + parallel panel,
+  not a linear skill); #2 cleared (no nesting); #3 cleared (panels are
+  orthogonal — contract/tests/data; a11y/DS/QA; the panel excludes the
+  implementer so no lens self-reviews); #4 cleared (synthesis is a QA-clean
+  artifact or a structured escalation).
+
+**Caps after this amendment.** Team-level total 8 → 10. Per-team: Yasad 3/4,
+Panim 2/4; Chosheb/Mishmar/Migdal/Sefer unchanged (amendments use no new slot).
+All within the 4/team cap.
+
+**Loop-until-X is no longer single-use.** This supersedes the earlier framing
+(`workflows/README.md`) that `knowledge-gap-discovery` was the only legitimate
+loop-until-X. Bounded QA-convergence is now a sanctioned second case; the bound
+(hard cycle cap + mandatory escalation, never silent settle) is what keeps it
+inside the discipline. Security and infra loops are deliberately conservative:
+no stateful op runs inside the loop (asymmetric delegation, rules §5).
+
 **Supersedes / amends:** none. Codifies the discipline implicit in D-002
 (Claude Code models only — capability discipline) and D-007 (separate stores
 — epistemic discipline) onto the orchestration layer.
@@ -1011,4 +1102,303 @@ savings carry through to those workflows.
 
 ---
 
+## D-012 — Per-project isolation of the cognee work store (added 2026-06-10)
+
+**Status:** adopted (per-project physical isolation); engine **resolved** to
+embedded Ladybug (Benaiah-vetted, see below); the provisioning migration is a
+follow-on plan. Co-owned by Bezalel (CTO) + Phinehas (security).
+
+**Decision:** each project gets its **own physically-separate cognee work store**,
+instead of all projects sharing the single work box on `:7777`. Isolation is by
+**topology** (separate process + separate data), never by cognee's `datasets=`
+filter. This extends D-007's physical-separation principle from *curated vs work*
+to *project vs project* within work. The curated store (`:7730`) is unchanged —
+one corpus, no projects to isolate from each other.
+
+**Why (the assumption that broke):** D-007 separated curated from work but assumed
+`datasets=` would scope projects *within* the work store. It does not. Verified
+against cognee v1.1.0 source + issue #1023: with `ENABLE_BACKEND_ACCESS_CONTROL=
+false` (required because cognee's access control is Neo4j-incompatible), the
+`datasets=` filter is **advisory only** — search runs against the whole graph.
+cognee's only real isolation is a physical per-dataset DB created in access-control
+mode, and Neo4j is not a supported backend for it. A `datasets=["wisemoney"]`
+query returned aiobi-mail content **including a live Gemini API key** — a
+cross-tenant confidentiality failure (Phinehas: CRITICAL), not a latent weakness.
+
+**Engine (resolved — Benaiah dependency vet against cognee v1.1.0):** **embedded
+Ladybug.** `GRAPH_DATABASE_PROVIDER=ladybug` is cognee's *default* at v1.1.0 —
+`ladybug==0.16.0` is a core (non-optional) dependency with a fully-implemented
+adapter (`infrastructure/databases/graph/get_graph_engine.py`; the `kuzu` token
+aliases to the same `LadybugAdapter`). Each project = **one cognee-mcp container
+(the already-patched `mishkan/cognee-mcp` image) on its own port + own volume, with
+`GRAPH_DATABASE_PROVIDER=ladybug` and a per-project `GRAPH_FILE_PATH`** → physical
+isolation by container + volume + on-disk graph file, no Neo4j (embedded), no N×4g
+memory floor, no reliance on the failed `datasets=` filter. The Neo4j-per-project
+fallback is **not needed**.
+
+*Implementation note — container, not stdio (2026-06-10).* Bezalel proposed
+evaluating a host **stdio** cognee-mcp (zero container) as the default. Evaluated and
+rejected: the recall fix (`cognee-mcp-recall-user.py` + `cognee-mcp-core-align.py`)
+lives only in the **built Docker image**, so a host checkout (`_src/cognee`, unpatched
++ core not version-aligned) would reintroduce the recall bug and require maintaining
+the patches in two places. The container path reuses the image where recall is
+*proven* working — physical isolation is identical (separate container + volume), the
+only loss vs stdio is one lightweight container per active project (no Neo4j, so far
+cheaper than today's shared Neo4j-backed store). Revisit stdio if/when cognee-mcp
+ships the #2855 fix upstream and the patches can be dropped. Supply-chain:
+Ladybug is a credible MIT fork of the Apple-archived Kuzu (founder ex-FB/Google),
+actively maintained (v0.17.1, Jun 2026), no known CVEs, version-pinned — acceptable
+for an embedded local store with no network exposure; **re-vet at 12 months** (watch
+items: ~8-month-old fork, PyPI `ladybug` namespace recently reclaimed from an
+unrelated tools suite).
+
+**Provisioning:** lazy, per project at `/mishkan-init` — `ensure-work-store.sh`
+brings up the project's own Ladybug container and prints its port, substituted into
+the rendered `.mcp.json`. **Three aliases per project** (the alias is the doorway;
+the backend behind each differs):
+- **`cognee`** → this project's own Ladybug store — isolated project knowledge.
+- **`cognee-memory`** → a single **shared** session-memory store: the **kept** Neo4j
+  box on `:7777`, holding **`claude_code_memory`** only. Per-client session memory
+  is one continuous thing across all work and is **not re-derivable** from docs, so
+  it stays a shared pillar rather than fragmenting per project. (Session memory is
+  cross-project by nature; it must be kept scrubbed of project secrets/PII.)
+  *Mechanism (verified, cognee v1.1.0):* two distinct layers — the **session
+  conversational cache** (env `CACHING`) and the **`claude_code_memory` graph
+  dataset** (env `COGNEE_MCP_AGENT_SCOPED`). Per-project stores set `CACHING=false`
+  so the session cache accumulates only in `cognee-memory`; `CACHING=false` disables
+  only that cache (not embedding/LLM/query caching, recall/cognify unaffected). The
+  permanent `claude_code_memory` dataset is independent of `CACHING` — it is kept
+  central by routing `remember()`/memory writes to the `cognee-memory` alias.
+- **`cognee-curated`** → the shared reference library (`:7730`, D-007).
+
+Isolation rides on the per-project `cognee` instance; the dataset name becomes
+cosmetic. The old shared Neo4j *work* graph (project data) is **discarded** — it is
+re-derivable from tagged docs — but the **box itself is kept and repurposed** as
+`cognee-memory`; `claude_code_memory` is never pruned (D-007). So the migration
+does not delete the Neo4j box, it narrows its job to session memory.
+
+**Security posture (Phinehas, gating):** the boundary must be physical and
+verifiable by topology; an application-layer filter whose enforcement just failed
+(#1023) is rejected *as the boundary* (acceptable only as defense-in-depth on top).
+**Interim controls, mandatory until per-project stores land:** the shared `:7777`
+is a **single trust domain** — no secrets, no PII; ingest opt-in + scrubbed only;
+a loud advisory-only warning at the boundary; and the already-leaked Gemini key is
+**revoked (engineer) then purged from the graph (engineer-run, Mishmar-specified)**.
+
+**Alternatives considered:**
+1. *Re-enable access control on Neo4j.* Rejected — `multi_user_support_possible()`
+   raises `EnvironmentError` for Neo4j; needs a backend migration first.
+2. *Neo4j Enterprise multi-DB (one DB per project).* Rejected as primary — standing
+   license liability for a single-engineer harness; still N cognee-mcp instances;
+   one Neo4j process still spans tenants. Last-resort fallback only.
+3. *Wrapper-side post-filter on the shared graph.* Rejected — no reliable per-node
+   dataset tag to filter on; a non-durable workaround (rule 3).
+
+**Consequences.** *Positive:* per-project confidentiality by construction, no
+reliance on cognee's filter, bounded per-project cost (embedded ≈ free; fallback ≈
+one small Neo4j). *Negative:* loses the work-store Neo4j browser (static-HTML
+`visualize_graph` export is the fallback); existing work graphs are re-ingested
+against the new backend (cheap, idempotent via `mishkan-ingest`); a dependency on
+Ladybug's maintenance health (Benaiah-vetted; Kuzu is archived).
+
+**Supersedes / amends:** extends **D-007** (physical store separation) to a
+per-project axis within work — D-007 stands unchanged. Touches **D-008**'s Cognee
+work store. The provisioning migration (`mishkan-init` rework, per-project store
+creation, re-ingest) is a follow-on `/plan` routed to Migdal, gated on the engine
+vet + Y4NN ratification.
+
+---
+
+## D-013 — Attach the MISHKAN ontology to ingested documentation (added 2026-06-11)
+
+**Status:** accepted · **Drivers:** Y4NN · **Authors:** drafted by the harness, ratify with Nathan + Bezalel.
+
+**Context.** `mishkan-ingest` ran `cognee.cognify(datasets=[…])` with **no ontology** — the live
+log says *"No ontology file provided. No owl ontology will be attached to the graph. [OntologyAdapter]"*,
+and ingested nodes carry `ontology_valid: false`. The harness already defines a schema in
+`payload/mishkan/ontology.md` (14 entity types, 16 edges, `blast_radius`), but it was a **markdown
+convention for agent-authored nodes** (`cognee-promote`, `context-compress`, Baruch) — never a
+machine ontology fed to cognify. So ingested documentation was graphed by unconstrained LLM
+extraction, with no link to the MISHKAN type system.
+
+**Decision.** Ship a machine ontology and attach it at every `mishkan-ingest` cognify.
+- `payload/mishkan/ontology.ttl` — **Turtle/OWL**, the 1:1 machine mirror of `ontology.md` (14
+  `owl:Class`, 16 `owl:ObjectProperty` with `rdfs:domain`/`range` via `owl:unionOf`, `blast_radius`
+  as `owl:DatatypeProperty`). Turtle over RDF/XML for reviewability; hand-authored because the schema
+  is "locked v1." `ontology.md` stays the canonical human source; `ontology.ttl` is its machine form.
+- cognee v1.1.0 reads the ontology from the **environment** (Pydantic `OntologyEnvConfig`), **not** a
+  cognify kwarg (verified live — the kwarg lands in `**kwargs` and is silently ignored).
+  `docker-compose.work.yml` sets `ONTOLOGY_RESOLVER=rdflib` · `MATCHING_STRATEGY=fuzzy` (already the
+  defaults) · `ONTOLOGY_FILE_PATH=/home/cognee/ontology.ttl`; `ensure-work-store.sh` stages the ttl to
+  that path at provision (idempotent). **Fail-open:** missing file → cognee warns, ingests
+  ontology-free. So the ontology applies to *every* cognify in the work store, not just `mishkan-ingest`.
+- ONE shared ontology for all projects (the MISHKAN schema is global), even though work stores are
+  per-project (D-012).
+
+**Caveat (sets expectations).** cognee's resolver marks `ontology_valid=true` and adds parent/object-
+property edges **only where the LLM-extracted entity *type names* match ontology class names**. The
+default `KnowledgeGraph` extraction assigns free-form types; it will not emit `Decision` /
+`ResearchOutput` / `Incident` unless steered. So this pass gives **validation + enrichment of matches**,
+not full retyping of prose into MISHKAN classes. Forcing the taxonomy (custom prompt / graph_model)
+is a **Phase 2**, opened only if Phase-1 `ontology_valid` coverage proves too thin.
+
+**Alternatives considered.** (1) *markdown→ttl generator* — rejected for now: a locked v1 schema does
+not justify the build step (revisit if it starts churning). (2) *RDF/XML* — rejected: far less
+reviewable than Turtle for a hand-authored, versioned artifact.
+
+**Consequences.** *Positive:* ingested docs are linked to the type system where they match; the
+`CuratedResource`/`CaseNode`/etc. classes become real, queryable types; sets up the D-014 research→
+curated feed. *Negative:* a second artifact (`ontology.ttl`) to keep in sync with `ontology.md`
+(guarded by a label-coverage check); ontology benefit is partial until Phase-2 extraction steering.
+
+**Refs:** extends **D-008** (knowledge surfaces) and rides on **D-012** (per-project store). Mechanism
+confirmed against the installed cognee v1.1.0 source (`modules/ontology/ontology_env_config.py` +
+`get_ontology_resolver_from_env`): env-config only, requires resolver `rdflib` + strategy `fuzzy` +
+a file path (resolver/strategy already default to those values). Out of scope: agent-write paths
+(already convention-bound); the **curated** store (its nodes are pre-typed by the structured seed —
+`add_data_points`, no cognify extraction — so no ontology needed there); back-filling existing graphs.
+
+---
+
+## D-015 — Unified semantic `mishkan` control surface for the knowledge stack (added 2026-06-11)
+
+**Status:** accepted · **Drivers:** Y4NN · **Authors:** drafted by the harness, ratify with Bezalel.
+
+**Context.** The engineer drove every stateful cognee op by hand across scattered compose files and
+scripts (a 3-file `docker compose` incantation, `ensure-work-store.sh`, manual `docker rm -f`/`volume
+rm`, `ensure-curated-box.sh`, ad-hoc `docker ps`). High friction, high recall load. Two robustness gaps
+also surfaced this session: a docker rename/orphan race (fixed, `a9cf950`) and a TUI daemon-probe that
+mis-read a *wedged* `watchd` as healthy.
+
+**Decision.** Extend the `mishkan` CLI into one control surface, governed by a strict naming rule and
+the asymmetric-delegation boundary (D-005).
+
+- **Naming rule (semantic, object-first):** a command must name *what it operates on*.
+  - **Bare verb IFF the object is the tool itself** — `mishkan install | uninstall | status`. (Not
+    `harness install`: the npm pkg is `mishkan-harness`, so `npx mishkan-harness harness install`
+    doubles "harness".)
+  - **`mishkan <object> <verb>` for every subsystem** — `knowledge configure|ingest`,
+    `knowledge-stack up|down|restart|status`, `project-work-store [<slug>] up|down|reset`,
+    `code-graph status|open|scan`, `observability install|open`, `org show`. Descriptive compound
+    objects (`knowledge-stack`, `project-work-store`) are preferred over brevity — a bare `start`
+    ("start *what*?") or a topology noun the user must decode (`stack`/`memory`/`foundation`) are both
+    rejected. `knowledge-stack` = infra lifecycle (`up`); `project-work-store` = data lifecycle (`reset`).
+- **Rule-5 boundary (the crux):** the CLI **executes** because the *human* invokes it — D-005 forbids
+  *agents* running stateful ops, and they still can't (the bin is never in an agent tool set); the TUI
+  still can't either (it only *surfaces* the command, never runs it). Destructive ops (`stop`, `reset`)
+  gate on a confirm.
+- **Guided bring-up, not a thin wrapper:** `knowledge-stack up` preflights config (docker present,
+  `.env`, `COGNEE_MCP_REF`) and, on a gap, prints the exact fix and stops — never a cryptic docker
+  error. `project-work-store up` warns if the stack is down. `/mishkan-init` composes the two:
+  `knowledge-stack up` (ensure infra, confirm-if-down) + `project-work-store up` (this project).
+- **TUI hardening:** `_probe_socket` now reads the daemon's on-connect `{"type":"snapshot"}` frame and
+  validates it, so a *wedged* watchd is replaced rather than adopted (client-side only).
+
+**Alternatives considered.** (1) bare `start`/`stop` — rejected (object-less). (2) `stack`/`memory`
+nouns — rejected (require decoding internal topology). (3) start/stop *buttons* in the TUI — rejected,
+moves stateful control into a tool (breaks D-005). (4) the CLI re-implementing the scripts — rejected;
+it *wraps* them so the scripts stay the single source of truth.
+
+**Consequences.** *Positive:* one low-recall surface; preflight/guide kills cryptic failures; the TUI
+points at the fix without executing it; daemon self-heals on wedge. *Negative:* renames published
+commands (`configure-knowledge`→`knowledge configure`, `observability`→`observability install`,
+`org`→`org show`) — old flat names kept as hidden working aliases so nothing breaks mid-migration; help,
+install sign-off, docs/usage, README, and the org-reference command updated in the same pass.
+
+**Refs:** rides on D-005 (asymmetric delegation), D-008 (knowledge surfaces), D-012 (per-project store).
+
+---
+
+## D-016 — Engineer-gated promotion of research findings into the curated library (added 2026-06-11)
+
+**Context.** The curated library (`cognee-curated`, :7730) is the org-wide reference surface (D-007),
+but it was **seed-only**: `ingest-curated.py` *prunes then writes*, so it cannot grow additively without
+wiping curated. The research pipeline writes `ResearchOutput`/`CaseNode` to the per-project **work** store
+(D-012), never curated; and **no agent has a curated-write tool** — curated is read-only at the agent layer
+by design. So a reusable resource Caleb finds (a vendor doc, a spec, a primary reference) dies in one
+project. The ontology already ships `CuratedResource` + `CuratedLibraryHit` for exactly this growth — only
+the wire was missing.
+
+**Decision.** Add an **engineer-gated** path to grow curated, additive and deduped, with the human as the
+library's editor:
+1. **Shemaiah** (evaluate) emits a structured `curated_promotion_candidate` (name, url, problem_class,
+   team, source_tier, why) **only when** `verdict=resolved` + `confidence≥medium` +
+   `curated_library_agreement=not_covered` + real cross-project reuse. It nominates; it writes nothing.
+2. **Baruch** (report) copies the candidate into the research-log **and** appends it to an engineer queue
+   `~/.claude/mishkan/curated-candidates.jsonl`. Baruch has `Write` but still **no** curated-write tool —
+   the boundary holds. The research-log schema is `additionalProperties:false`, so the new optional field
+   was added to **both** `templates/research-log.schema.json` and `scripts/validate-research-log.sh`
+   (with a bash-layer shape check so a malformed candidate fails without ajv).
+3. **The engineer** runs `mishkan knowledge curate` — it lists pending candidates, asks per candidate, and
+   on approval runs `scripts/promote-curated.sh` → `cognee/promote-curated.py`: an **additive** write
+   (`CuratedResource` DataPoint + `add_data_points`, **no prune**), deduped by url against the seed manifest
+   and a promoted ledger, via `docker exec` into `mishkan-curated-mcp`. Stateful — the human runs it, never
+   an agent, never automatic.
+4. **Telemetry.** Ezra's curated short-circuit records the matched resource (a `CuratedLibraryHit` signal),
+   so a promoted resource's usefulness is measurable and dead weight is auditable.
+
+**Why engineer-gated, not auto.** Auto-promotion was rejected: the curated surface is shared across every
+project, so an unvetted write pollutes it for all, and (per D-012) research output can carry PII/secrets —
+a human scrub before a shared write is the safety boundary. Phinehas reviews PII/secret-scrub on a
+candidate; Bezalel ratifies the additive-write design; Nathan authored the ADR.
+
+**Consequences.** *Positive:* curated grows from real work without a re-seed; the prune-based seed stays
+intact for bootstrap; the agent-layer read-only boundary is preserved end-to-end; dedup keeps the library
+clean; the hit signal makes promotions falsifiable. *Negative:* one more human-gated step (the engineer
+must run `mishkan knowledge curate`); the dedup ledger assumes these scripts own curated writes (a manual
+out-of-band write to curated would not be in the ledger — documented boundary).
+
+**Out of scope:** auto-promotion (rejected); the seed (`ensure-curated-box.sh` / `seed-curated-library.sh`
+unchanged); work-store promotion (`cognee-promote` work tiers unchanged); any agent curated-write tool
+(stays read-only).
+
+**Refs:** rides on D-005 (asymmetric delegation — the write is the engineer's hands), D-007 (curated
+library), D-008 (knowledge surfaces), D-012 (per-project store / PII boundary), D-013 (ontology types
+`CuratedResource` + `CuratedLibraryHit`), D-015 (the `mishkan knowledge curate` control surface).
+
+---
+
+## D-017 — User-editable model-tier routing via a preserved overlay (added 2026-06-13)
+
+**Context.** D-002 made `model-routing.yaml` the central tier map and the `model-route.py` hook reads it
+live, so a tier change takes effect on the next delegation with no reinstall. But two gaps made re-tiering
+impractical for the engineer: (1) it is developer-facing YAML with no friendly surface, and (2)
+`mishkan install` overwrites `model-routing.yaml` (it sits inside the `copyDir(payload/mishkan,…)` tree),
+so a hand edit is clobbered on the next update. The Fable suspension (D-002 amendment 2026-06-12) made
+this urgent: a tier can vanish overnight, and the engineer needs to adapt routing — for availability,
+cost, or preference — without editing source and reinstalling.
+
+**Decision.** Add a `mishkan model` control surface backed by a **preserved overlay file**:
+- **`model-routing.local.yaml`** holds the engineer's per-agent overrides. The hook reads the shipped
+  default, then overlays local (local wins per-agent); fail-open is preserved (absent or malformed
+  overlay → behaves exactly as the single-file routing). The installer **places it once and preserves
+  it** — and because `copyDir` ships no such file and never deletes destination extras, a refresh can
+  never clobber it (the same place-once philosophy as `engineer-standards.md`). This is an **overlay**,
+  not a preserve-the-whole-file scheme: the shipped default keeps flowing on every update (new agents,
+  baseline changes), while the engineer's deltas persist on top — no drift.
+- **`mishkan model show | set <agent|team|all> <tier> | reset [target]`** edits ONLY the overlay — never
+  the shipped default, never the 45 frontmatter files. `team` expands via `org/org.json` (the same source
+  as `mishkan org show`). `set` validates the tier and, for a **dormant** tier (`fable`, currently
+  suspended), warns and confirms. `show` flags any agent routed to a dormant tier.
+
+**Why overlay over preserve-the-file (Bezalel ratified).** Preserving a user-edited `model-routing.yaml`
+would freeze it: future baseline changes (the Fable revert, a new agent, a re-tier) would never reach an
+engineer who once edited it — the installed-runtime-vs-source drift trap. The overlay keeps the two
+concerns separate: harness owns the default, engineer owns the deltas.
+
+**Consequences.** *Positive:* routing is now the engineer's to change at will, instantly (hook reads live)
+and durably (survives updates); responds to abrupt availability changes without a code change; no
+45-frontmatter churn. *Negative:* two files now express routing (default + overlay) — mitigated by
+`mishkan model show` rendering the effective merge; an overlay entry set equal to the default is harmless
+redundancy.
+
+**Out of scope:** named profiles (`thrifty`/`max`) — `set`/`reset` cover edit-by-intent; profiles are a
+thin future follow-up over the same overlay. No auto-detection of model availability (the dormant warning
+is static). Agent frontmatter `model:` stays the shipped fallback used only if the hook is absent.
+
+**Refs:** rides on D-002 (the tier model + the routing hook), D-005 (the CLI is human-run), D-015 (the
+semantic `mishkan <object> <verb>` surface this extends with `model`).
+
+---
+
 *Decisions locked May 2026. Revisit only with a dated amendment below.*

package/docs/design/MISHKAN_observability.md

@@ -583,14 +583,14 @@ empty state dim-centered.
 ║ ○1 Live  ○2 Agents  ○3 Workflows  ●4 Knowledge  ○5 Activity       2 sessions  12:03 ║
 ╠══ COGNEE STORES ═══════════════════════════════════════════════════════════════════════╣
 ║                                                                                        ║
-║   ╭─ work :7777 ────────────────╮   ╭─ curated :7730 ──────────────╮                  ║
-║   │ ● UP  · 02h14m              │   │ ● UP  · 43h12m               │                  ║
-║   │                             │   │                              │                  ║
-║   │ 1,247 nodes                 │   │   96 nodes                   │                  ║
-║   │ ▁▁▂▃▃▅▆█  +12 last 5min     │   │ ▁▁▁▁▂▂▃▃  +0  last 30min     │                  ║
-║   │ last ingest  12:02:14       │   │ last seed   2026-05-29       │                  ║
-║   │ embeddings: gemini  3072d   │   │ embeddings: ollama  768d     │                  ║
-║   ╰─────────────────────────────╯   ╰──────────────────────────────╯                  ║
+║   ╭─ cognee-memory :7777 ──────────╮   ╭─ curated :7730 ──────────────╮                ║
+║   │ ● UP  · 02h14m                │   │ ● UP  · 43h12m               │                ║
+║   │ session memory only           │   │                              │                ║
+║   │ 1,247 nodes                   │   │   96 nodes                   │                ║
+║   │ ▁▁▂▃▃▅▆█  +12 last 5min       │   │ ▁▁▁▁▂▂▃▃  +0  last 30min     │                ║
+║   │ last ingest  12:02:14         │   │ last seed   2026-05-29       │                ║
+║   │ embeddings: gemini  3072d     │   │ embeddings: ollama  768d     │                ║
+║   ╰───────────────────────────────╯   ╰──────────────────────────────╯                ║
 ║                                                                                        ║
 ╠══ RECENT OPS ═════════════════════════════════════════════════════════════════════════╣
 ║ time      store    op      query / path                       ms      Δnodes          ║