mishkan-harness 0.2.0 → 0.2.4

package/docs/design/MISHKAN_decisions.md

@@ -298,11 +298,16 @@ introduced to protect.
 
 ### Out of scope (explicitly not decided here)
 
-1. **Token-saving measurement POC.** Whether Graphify saves Nx tokens on a
-   representative agent workload is a separate, instrumented experiment with
-   its own success criteria. The 71.5× figure circulating in third-party write-ups
-   is **not** verified by this ADR and must not be cited as a MISHKAN claim
-   until measured.
+1. ~~**Token-saving measurement POC.**~~ **CLOSED 2026-06-07** —
+   POC executed on the MISHKAN harness with Graphify v0.8.33: **88.1×
+   average reduction** across the 5 canonical structural questions
+   (range 69.4× to 141.8×). The third-party 71.5× claim is **verified**
+   in spirit — MISHKAN's actual measurement is +23 % higher (likely
+   driven by Python-heavy AST shape vs the mixed TS corpora of the
+   third-party benchmark). Full method, query-by-query results, and
+   honest gaps in `docs/research/graphify-token-saving-poc.md`. The 88.1×
+   figure may be cited as a MISHKAN claim. The 71.5× figure may be cited
+   as a third-party point reference within the observed range.
 2. **Refactor of the Explore agent / Hiram's exploration playbook.** Whether
    Hiram should consult Graphify before grep is a downstream agent change,
    not decided here.
@@ -353,7 +358,7 @@ discipline.
 
 ## D-009 — Graph-first PreToolUse gate for the five code-writing specialists (added 2026-06-05)
 
-**Decision:** introduce a MISHKAN PreToolUse hook — `pre-tool-graphify-nudge.py` —
+**Decision:** introduce a MISHKAN PreToolUse hook — `pre-tool-knowledge-route.py` —
 that, for **exactly the five code-writing specialist agents** (Hizkiah, Salma,
 Oholiab, Nathan, Zadok), runs alongside the existing security (D-004) and
 model-routing hooks and **advises** — does not block — when a `Read` or `Grep`
@@ -481,10 +486,10 @@ enforcement. If it does not, a future ADR can revisit hardening.
 
 ### Integration
 
-- **Hook file.** `payload/mishkan/hooks/pre-tool-graphify-nudge.py`,
+- **Hook file.** `payload/mishkan/hooks/pre-tool-knowledge-route.py`,
   registered alongside `pre-tool-security.sh` and `model-route.py` in the
   PreToolUse chain. Order: security (deny on violation) → model-route
-  (inject model) → graphify-nudge (advise). Each is independent and
+  (inject model) → knowledge-route (advise). Each is independent and
   fail-open; chain order is for clarity, not correctness.
 - **Subagent detection.** Reuses the same `subagent_type` field
   `model-route.py` already reads from `tool_input`. When the field is
@@ -567,6 +572,443 @@ providing the runtime mechanism D-008 explicitly deferred (D-008 Out of
 Scope #4). Composes with D-004 (existing PreToolUse Bash chain) without
 modifying it.
 
+## D-010 — Workflow portfolio discipline: four anti-patterns, two caps, PM+CTO co-ownership (added 2026-06-07)
+
+**Decision:** the dynamic-workflow portfolio is governed by an explicit
+discipline rather than ad-hoc accretion. Three rules together: (a) **hard
+caps** — 10 top-level (org) workflows + 4 team workflows per team; (b) **four
+named anti-patterns** that disqualify a candidate; (c) **PM + CTO joint
+ownership** — every addition, retirement, or substitution goes through
+Nehemiah and Bezalel together, never through a single agent's unilateral push.
+A fire-count rule retires workflows that fire < 2× across 3 sprints, gated by
+the same PM+CTO review.
+
+### Force-tension
+
+**What pushes toward accretion.** Workflows are the most powerful primitive
+the harness exposes — typed contracts, parallel fan-out, adversarial verify
+panels. Every recurring task looks like a candidate. Each team has 5–7
+specialists, so "one workflow per team's main shipping flow" feels natural.
+Six team-ship workflows × six teams + the 10 org-level = a portfolio of 46.
+Without a cap, that is the asymptote: most workflows fire once, contribute
+nothing, and add maintenance debt.
+
+**What pushes against.** Workflow runtime cost is real (Bun-shape migrations
+hit hundreds of agents and thousands of subagent-tokens per run). Each
+workflow carries a contract surface that must be kept correct as agents
+evolve. Workflows that fire rarely cannot pay back their codification cost.
+Worse, workflows that look load-bearing but encode skill-shape (linear
+sequence, no panel, no termination predicate) blur the distinction between
+workflow and skill, eroding the discipline that makes the workflow tool
+worth reaching for.
+
+### Adopted shape
+
+**(a) Hard caps.**
+
+- **10 org-level workflows.** Current: `mishkan-sprint-close`,
+  `mishkan-deep-research`, `mishkan-codebase-audit`, `mishkan-migration-wave`,
+  `mishkan-architecture-panel`, `mishkan-release-readiness`, `mishkan-init`,
+  `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
+  per team are deliberately left open — candidates compete for them at
+  PM+CTO review, not on a team lead's word.
+
+**(b) Four anti-patterns.** A candidate that exhibits any of these is rejected
+or reworked, regardless of fit:
+
+1. **Skill-in-workflow-clothing.** Linear sequence, no parallelism, no
+   termination predicate, no panel. That shape is a skill, not a workflow.
+   If the cost-to-fan-out gain is < 2× wall-clock vs Task delegation, it
+   does not earn the workflow tool.
+2. **Workflow calling workflow without a contract.** Nested workflows are
+   valid (cf. `release-readiness` → `codebase-audit`) **only** when the
+   inner workflow's output schema is consumed structurally by the outer.
+   Free-form nesting hides token cost, breaks retry semantics, and produces
+   an opaque blob of subagent transcript that the orchestrator cannot
+   reason over.
+3. **Judge panels with non-orthogonal reviewers.** If two reviewers in a
+   panel share ≥ 70% of their evaluation criteria, the panel is theatre —
+   redundant votes from correlated judges. Each lens must be load-bearing
+   and distinct (the canonical example is `mishkan-blast-radius`'s
+   caller-side / data-contract / runtime-behavior triad).
+4. **Workflow-as-status-page.** Orchestration that fans out to gather state
+   without synthesis is a dashboard query, not a workflow. The synthesis
+   stage is the workflow's reason to exist; if it is missing or trivial,
+   the work belongs in observability, not in `Workflow()`.
+
+**(c) PM + CTO joint ownership.** New workflow proposals are written as a
+brief (problem, fan-out shape, termination predicate, expected fire-count,
+anti-pattern self-check). Nehemiah owns delivery / recurrence justification;
+Bezalel owns orchestration shape / schema contracts. Joint approval lands
+the workflow under `payload/mishkan/workflows/`; unanimous rework lands it
+under `payload/mishkan/workflows/proposed/` with the rework note; rejection
+returns the brief to its proposer with the failing anti-pattern named.
+
+**Soft-retirement rule.** A workflow that fires < 2 times across 3 consecutive
+sprints surfaces in the next `/sprint-close` for PM+CTO review. The default
+disposition is retirement to `proposed/`; the rebuttal is a concrete
+upcoming-use justification.
+
+### Alternatives considered
+
+1. **No cap; allow accretion.** *Rejected.* This is the default state of every
+   ungoverned workflow portfolio in the wild. The reference cases (OneRedOak,
+   Bun-shape) show that production teams converge on 3–6 workflows after
+   accretion; the cap codifies that ceiling rather than letting the harness
+   relearn it under load.
+
+2. **Per-team unilateral additions, no PM+CTO review.** *Rejected.* Without
+   a joint gate the four anti-patterns reappear — every team adds the
+   workflow that feels load-bearing from their vantage point, and the
+   harness ends up with six near-identical feature-ship orchestrations.
+   The June 2026 portfolio review surfaced exactly this drift (Sefer
+   proposed two doc-generation workflows; both folded into skills under
+   the gate).
+
+3. **Workflow router that auto-selects per task.** *Deferred.* Selecting
+   among 18 workflows by task description is the same problem as skill
+   discovery (cf. `mishkan-skill-discovery`). Layering a router on top of
+   workflows duplicates that infrastructure. Wait for the skill-discovery
+   layer's telemetry before deciding whether workflows need their own
+   router or can be discovered through the same surface.
+
+4. **Cap of 6 org-level + 6 team workflows.** *Rejected after PM/CTO split
+   verdict.* Bezalel preferred 6 load-bearing org-level; Nehemiah preferred
+   10 with retirement-based pruning. Adopted 10 because the existing
+   portfolio already contains 10 that pass the anti-pattern check; cutting
+   to 6 would retire workflows that clear the bar by lottery, not by
+   discipline. The retirement rule is the steady-state pressure.
+
+### Invariants of the discipline
+
+- **Org-level cap = 10.** Always. To add, retire.
+- **Team-level cap = 4 per team.** Always. To add, retire from that team.
+- **Anti-pattern self-check** is part of the proposal brief — proposer
+  must name how the workflow avoids each of the four.
+- **No solo additions.** Even Bezalel cannot land a workflow alone; the
+  rules-rollout workflow exists precisely to prevent that drift.
+- **`proposed/` is not a parking lot.** Workflows there carry a written
+  promotion criterion (concrete fire-count, named use case).
+
+### Consequences
+
+**Positive.**
+- The portfolio stays legible. An engineer (or new agent) can read all 18
+  in an afternoon and know what each is for.
+- The cost ceiling is bounded. Worst-case spend is the sum of 18 known
+  shapes, not an unbounded sprawl.
+- The anti-pattern catalogue gives proposers concrete language for self-
+  review before bringing a brief, shortening the loop.
+- The PM+CTO gate replays the same discipline used for architecture (D-002,
+  D-007) — consistency across the harness's governance surfaces.
+
+**Negative.**
+- Some legitimate one-off orchestrations will fail the cap and have to wait
+  for a retirement slot. The escape valve is `proposed/` — the work is not
+  lost, just not active.
+- The fire-count rule is approximate; a workflow that fires 1× per sprint
+  but is genuinely load-bearing (e.g. quarterly audit) will trip the
+  retirement default and need to argue itself back each time. Tuned by
+  raising the window from 3 sprints to N if false-retirements appear.
+- "Anti-pattern self-check" relies on the proposer's honesty about their
+  candidate; a determined push can word-paint around it. Mitigation: the
+  CTO half of the gate has explicit authority to reject on shape.
+
+**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.
+
+## D-011 — Universal skill-discovery layer (added 2026-06-07)
+
+**Status:** adopted, Phase 1 canary.
+
+**Context — the tension.** The harness now ships 40+ MISHKAN craft skills,
+and the user surface adds dozens more (`~/.claude/skills/`, plugin-bundled,
+project-local). When a task arrives, the main session cannot reliably
+remember which skill applies — the list itself does not fit in working memory
+without bloating context. Two failure modes compete:
+
+1. **Reinvention.** The model improvises work that a skill already encodes,
+   because the right skill was never surfaced. This is the silent failure —
+   no error, just degraded output.
+2. **Context bloat.** The model loads too many skills "just in case",
+   spending tokens on dormant guidance that crowds out the work itself.
+
+The tension is not "should we make skills discoverable" — it is *who* decides
+which skills surface and *how much context* that decision consumes. D-010
+governed workflow portfolio discipline by cap + anti-pattern self-check; the
+same discipline applies one layer down, but the right instrument is a router,
+not a cap (we *want* the long tail of installed skills, we just don't want to
+pay for all of them at once).
+
+### Alternatives considered
+
+1. **TUI-only browsing.** *Rejected.* A `mishkan-skills browse` TUI is
+   useful, but it puts the discovery cost on the engineer's reading time
+   for every task. The model still wouldn't know which skill to mention
+   in the first place, so the silent-reinvention failure mode persists.
+   Kept as a Phase 2 nice-to-have, not the primary surface.
+
+2. **Embedding-based matching.** *Rejected.* Local sentence-embedding
+   model + cosine similarity would give better recall than TF-IDF on
+   ambiguous queries. But: (a) it pulls in a model dependency (200MB+ at
+   minimum) for a layer that runs in every session, (b) the inference
+   latency is non-trivial at session boot, (c) the trigger-phrase match
+   on `Use when…` lines already covers the common case because skill
+   descriptions are written *for* matching. TF-IDF is the right fallback
+   for the long tail. Revisit if miss-log analysis shows recurring
+   semantic misses that token overlap cannot recover.
+
+3. **MCP server.** *Rejected for Phase 1.* An MCP server for skill
+   discovery would let other tools query the same index, but it adds a
+   process to manage and a network surface. The Python-script + flat-file
+   index has the same data shape with zero process overhead, and an MCP
+   wrapper around it remains a free Phase 2 option once the index format
+   stabilises.
+
+4. **No discovery layer; keep the implicit reach.** *Rejected.* The
+   forty-skill surface already exceeds what the model reaches reliably.
+   The reinvention rate observed in sessions (anecdotal but consistent)
+   was the trigger for this decision.
+
+### Adopted shape
+
+- **Universal indexer** (`payload/mishkan/scripts/skill-discovery-indexer.py`).
+  Stdlib-only Python, scans four roots in precedence order:
+  `~/.claude/mishkan/skills/` → `~/.claude/skills/` →
+  `~/.claude/plugins/*/skills/` → `<repo>/.claude/skills/`.
+  Output: single flat JSON at
+  `~/.claude/mishkan/skill-discovery/index.json`.
+  Each entry: `{name, source_path, origin, description, triggers,
+  category, frontmatter_raw, sha256, indexed_at, mtime}`.
+  Refresh triggers: install/update (full rebuild), session boot
+  (`--stat-only` mtime sweep against `meta.last_scan`), manual
+  `/mishkan-skills-reindex`. Stale entries (source_path gone) are dropped
+  at routing time.
+
+- **Router** (`payload/mishkan/scripts/skill-discovery-router.py`). Three
+  matching mechanisms layered: (a) trigger-phrase weighted match
+  (trigger = 3.0, description keyword = 1.0), (b) category prior
+  (×1.5 multiplier when invoked from a workflow declaring
+  `relevant_skill_categories`), (c) TF-IDF fallback when trigger pass
+  yields < 3 results. Output: 3 buckets capped at 13 total —
+  `must_load` ≤ 3, `should_consider` ≤ 5, `adjacent` ≤ 5.
+
+- **Skill** (`payload/mishkan/skills/skill-discovery/SKILL.md`).
+  Main-session-side. Tells the model how to interpret the 3 buckets
+  and the trust asymmetry (mark, never auto-load, non-mishkan entries
+  for stateful operations).
+
+- **Slash commands.** `/skills` (invoke router on current task);
+  `/mishkan-skills-reindex` (manual rebuild).
+
+- **Phase 1 canary integration.** `mishkan-init` workflow declares
+  `relevant_skill_categories` and runs a `SkillRouter` phase before PRD.
+  Result is advisory and folded into Bezalel's signoff context. No
+  other workflow is wired in Phase 1.
+
+### Risks
+
+1. **Context bloat from over-trusting `must_load`.** Mitigation: cap of 3,
+   bias-rule in the skill (prefer should_consider over padding must_load),
+   miss-log surfaces over-firing.
+2. **Name collisions across roots.** Mitigation: precedence order at
+   index time (mishkan wins); collisions recorded in
+   `meta.collisions` rather than silently dropped.
+3. **Trust asymmetry violations.** Mitigation: every non-mishkan entry
+   carries an explicit `trust` warning; skill rule forbids auto-load
+   of non-mishkan skills for stateful operations (D-002 / y4nn-§5).
+4. **Stale index hiding real skills.** Mitigation: session-boot
+   `--stat-only` sweep + drop-at-routing-time for dead `source_path`.
+5. **Fail-closed makes the harness brittle.** Mitigation: the layer is
+   fail-open end-to-end — indexer errors are per-skill skips, router
+   exceptions return empty buckets, every miss is logged to
+   `~/.claude/mishkan/skill-discovery/misses.jsonl` for tuning.
+
+### Phase 1 → Phase 2 path
+
+Phase 1 ships indexer + router + skill + slash commands + canary in
+`mishkan-init`. Promotion to Phase 2 requires:
+
+- **2 sprints of miss-log signal.** If the misses file shows recurring
+  patterns the trigger-match cannot catch, tune `description` text on
+  the implicated skills *before* reaching for embeddings.
+- **Threshold validation.** Default thresholds (`high=4.0, mid=1.5`) are
+  guesses on Phase 1 data; revisit at sprint close with the actual
+  score distribution from the miss log and successful routings.
+- **Broader workflow integration.** Once thresholds settle, add the
+  `relevant_skill_categories` field + SkillRouter phase to the other
+  org-level workflows that benefit (codebase-audit, release-readiness,
+  knowledge-gap-discovery).
+- **TUI browse surface** (optional). A `mishkan-skills` CLI that wraps
+  the same index for cold-browsing without a task.
+- **MCP wrapper** (optional). Exposes the router as an MCP tool so
+  agents in other contexts (project-local subagents) can query the
+  same surface.
+
+**Supersedes / amends:** none. Layers under D-010 (workflow portfolio
+discipline) one level down — the same discipline (cap + anti-pattern +
+miss-log feedback) applied to the skill surface rather than the workflow
+surface.
+
+### Amendment 2026-06-07: Phase 2 shipped
+
+Phase 1 ended at "the router exists." Phase 2 turns that into "agents
+auto-discover skills without being asked," through three injection
+mechanisms — none of them blocking, all fail-open.
+
+1. **Install-time rebuild.** `bin/mishkan.js` install phase 1 spawns the
+   indexer in `--rebuild` mode after the payload copy so
+   `~/.claude/mishkan/skill-discovery/index.json` lands seeded before the
+   first session boots. Fail-open: a missing `python3` or an indexer
+   error logs a warning and the install continues; recovery path is
+   `/mishkan-skills-reindex`.
+
+2. **SessionStart drift check.** `hooks/session-start-skill-index.sh`
+   runs the indexer in `--stat-only` mode on session boot. The indexer
+   compares each SKILL.md mtime against `meta.last_scan` and rebuilds
+   only on drift (or if the index file is missing). p95 budget: 200 ms,
+   well within the SessionStart budget shared with the other boot hooks.
+   Fail-open: any error → exit 0 silently.
+
+3. **PreToolUse auto-injection on Task / Agent.**
+   `hooks/pre-tool-task-skill-route.sh` reads the Task payload from
+   stdin, extracts `tool_input.prompt`, runs the router in
+   `--format injection` mode, and returns the resulting compact markdown
+   block via `hookSpecificOutput.additionalContext` (the documented
+   Claude Code PreToolUse field for prepending advisory context). Hard
+   caps: ≤ 3 `must_load` + ≤ 3 `should_consider` entries, ≤ 600 tokens
+   of prepended markdown, `adjacent` dropped at injection time
+   (awareness-only doesn't justify its tokens here). Skip injection
+   entirely on empty buckets — never pollute with "no skills found".
+   p95 budget: 100 ms (worst-case timeout: 1.5 s as a hard floor). The
+   `mishkan-init` Phase 1 canary stays in place; this becomes the
+   dominant path for every other Task call.
+
+**Trust marker.** The injection renderer suffixes every non-`mishkan`
+entry with `(community)`. The skill-discovery skill's existing rule —
+non-`mishkan` skills are never auto-loaded for stateful operations
+(D-002 / y4nn-§5) — applies unchanged.
+
+**Telemetry.** Every Task hook invocation emits a `hook_fire` event on
+the observability bus (decision = `allow` with injection, `ok` without).
+Every empty-bucket routing continues to land in
+`~/.claude/mishkan/skill-discovery/misses.jsonl`. A new aggregator
+script `scripts/skill-discovery-misses.py` (and `/mishkan-skills-misses`
+slash command) clusters misses by sorted-keyword signature and surfaces
+top-N patterns + by-reason breakdown.
+
+**Threshold-tuning process.** The mid + high thresholds remain
+`mid=1.5, high=4.0` from Phase 1. Tuning is now data-driven:
+
+- After each sprint, run `/mishkan-skills-misses --top 10`.
+- For any pattern with count ≥ 5 *and* a clearly-applicable skill that
+  should have matched, **edit the skill's description** to include the
+  pattern's keywords. Description tuning is free and bounded; it should
+  exhaust before threshold tuning.
+- If a recurring pattern still misses after description tuning, *and*
+  the scores are clustering just under the `must_load` boundary, lower
+  `--threshold-high` to 3.5; if `must_load` is over-firing on
+  marginally-relevant skills, raise it to 4.5. Move in 0.5 steps and
+  one sprint at a time. Same recipe applies to `--threshold-mid`.
+- `router_exception:*` reasons are bugs — escalate to Bezalel; never
+  tune around an exception.
+
+The Phase 1 → Phase 2 promotion gate ("2 sprints of miss-log signal")
+applied to broadening to Phase 2 hook mechanics; the same 2-sprint gate
+now applies to threshold tuning before any default is moved in the
+shipped router.
+
+## D-009 — Amendment 2026-06-07: Phase 2 advisory injection shipped
+
+**Original D-009 §6.2** scoped Phase 1 to telemetry-only, with the
+advisory injection deferred until "the baseline rate is measured." The
+phase-2 promotion has happened.
+
+**Why Phase 2 now.** The skill-discovery PreToolUse router (D-011
+Phase 2) injects skill suggestions based on the Task prompt — it
+matches "implement payment" to implementation skills, not to
+`graphify-query-craft` whose triggers describe structural questions.
+The router will not surface graphify for the vast majority of agent
+dispatches; only a runtime hook on the specific tool calls Graphify
+can answer (Read on source / Grep on bare identifier) closes that
+gap. Without Phase 2, the carrier-set expansion in the §6 amendment
+below has no enforcement path.
+
+**Mechanism.** `pre-tool-knowledge-route.sh` now emits an
+`hookSpecificOutput.additionalContext` advisory in addition to the
+telemetry event:
+
+- **Read** on a source extension → "about to Read `<file>`. For
+  structural questions, `graphify query` is cheaper."
+- **Grep** on a bare identifier → "`graphify query \"who calls X\"`
+  or `graphify affected X --depth 2` is the dispatch-aware
+  alternative."
+
+Suppressed when the project has no `graphify-out/` directory (no graph,
+no recommendation). Never sets `permissionDecision` — purely advisory,
+the tool call proceeds whether the agent acts on it or not.
+
+**Invariants preserved.**
+- Fail-open everywhere (missing jq, missing bus, malformed input → silent exit 0).
+- ≤ 50 ms p95 — bash hot path, single jq subprocess, no Python.
+- Telemetry event still fires (the Knowledge tab's Graphify activity counter is unchanged).
+- Trigger surface unchanged from Phase 1 — same source extensions, same bare-identifier Grep pattern.
+
+**What this changes.** A Hizkiah / Salma / Joah / Ira / etc. who Reads
+source or Greps an identifier now gets, in the tool-call context, a
+specific `graphify` command to consider. The advisory is structurally
+precise (suggests the right Graphify subcommand for Read vs Grep) and
+project-aware (suppressed where graphify-out/ doesn't exist), so it
+doesn't add noise on projects that don't use Graphify.
+
+## D-009 — Amendment 2026-06-07: scope expanded to all code-touching dev agents
+
+**Original D-009** scoped the Graphify advisory nudge to **exactly five
+agents** (Hizkiah, Salma, Oholiab, Nathan, Zadok) — the highest token
+consumers writing code. Empirical use since the POC made the original
+"five only" boundary read narrower than the actual benefit space.
+
+**Amended scope** — **20 code-touching dev agents** carry
+`graphify-query-craft` and are reached by the PreToolUse nudge when
+they hit `Read`/`Grep` on source:
+
+- **Yasad backend (5):** Hizkiah, Nathan, Zadok, Shallum, Uriah
+- **Panim frontend (4):** Salma, Oholiab, Asaph, Jahaziel
+- **Chosheb UI (1):** Hiram
+- **Mishmar code-security (3):** Ira, Joab, Hushai
+- **Migdal infra-code (4):** Palal, Meshullam, Meremoth, Hanun
+- **Sefer code-documentation (3):** Joah, Shevna, Jehonathan
+
+**Why the broadening.** Graphify answers "who calls X" / "what depends
+on Y" / "where is the entry point" — structural questions useful to any
+agent reading code, not just writing it. A security reviewer auditing a
+payment flow benefits from the call graph as much as Hizkiah
+implementing it; a documentation specialist (Joah / Shevna) writing
+module docs benefits from knowing its surroundings. Restricting to
+writers left readers' queries — typically grep + Read — on the expensive
+path.
+
+**What did not change.**
+- The hook stays **advisory**, never blocks (D-009 invariant preserved).
+- Fail-open on missing/stale graph preserved.
+- `--context` discipline in the craft skill body preserved.
+- The hook's trigger predicate (Read on source ext / Grep on bare
+  identifier) is agent-independent — adding agents to the carrier set is
+  what changes coverage, the hook itself stays the same.
+- The two orchestrators, the research pipeline, the QA reporters who
+  don't read source, and the team reporters remain out of scope —
+  adding them would add noise without changing behaviour.
+
+**Implication for D-010 (workflow portfolio).** The
+`mishmar-security-gate` and `sefer-release-notes` workflows now invoke
+agents carrying the skill — their structural-query phases will be
+served by Graphify where before they would have grep+Read. Token
+savings carry through to those workflows.
+
 ---
 
 *Decisions locked May 2026. Revisit only with a dated amendment below.*

package/docs/design/MISHKAN_harness_design.md

@@ -159,7 +159,7 @@ milestones. Sefer pulls at milestones and on trigger events.
 │  Each team: Lead → Specialists → QA/Advisor → Reporter           │
 │                                                                  │
 │  Collaboration model:                                            │
-│  Chosheb  ──→  Panim       design handoff · unidirectional       │
+│  Chosheb  →  Panim       design handoff · unidirectional       │
 │  Panim    ↔    Yasad       API contracts · bidirectional         │
 │  Yasad    ↔    Mishmar     audit + remediation · bidirectional   │
 │  Mishmar   →   Migdal      security gates infrastructure         │
@@ -780,38 +780,6 @@ already solved well.
 
 ---
 
-## 20. Open Design Questions
-
-Not blockers — next design layer.
-
-| Question | Status |
-|----------|--------|
-| SessionStart hook — what it loads · Cognee query on wake | Pending Claude Code feature validation |
-| ACI per team — how each team interacts with its environment | Next layer |
-| Cross-sprint knowledge compression — sprint memory → project graph | Next layer |
-| Self-improvement loop — frequency · who acts on outputs | Next layer |
-| Curated library bootstrap — how each team's library gets seeded | Next layer |
-| Sefer trigger events — full list of what fires an immediate pull | Next layer |
-
----
-
-## 21. What Is Not Yet Designed
-
-Explicitly out of scope — to be designed before building:
-
-- Agent specs (system prompts · input/output contracts · failure behavior)
-- Prompt engineering per agent
-- CLAUDE.md templates (user-level · project-level)
-- Rules files content per team
-- Hooks implementation (scripts)
-- Skills implementation (SKILL.md content)
-- Curated library initial content per team
-- Cognee graph schema (entity types · relationship types · ontology)
-- Observability pipeline (log aggregation · improvement layer queries)
-- Model routing configuration
-
----
-
 *MISHKAN Design Document — May 2026*
 *Living document. Claude Code-first. Cognee locked. Hebrew naming locked.*
 *Six teams including Sefer. Init flow locked. Sequential execution locked.*

package/docs/design/MISHKAN_observability.md

@@ -22,9 +22,10 @@ foundation with:
 2. **A daemon (`mishkan-watchd`)** — tails every session's NDJSON, polls a few
    synchronous sources (git worktrees, Cognee stats), keeps a live snapshot of
    harness state, and exposes a UNIX-socket NDJSON protocol.
-3. **A TUI client (`mishkan-watch`)** — Textual app. 5 tabs, key-driven, no
+3. **A TUI client (`mishkan-watch`)** — Textual app. 8 tabs, key-driven, no
    overload. Reads the daemon snapshot+delta stream, renders the view, never
-   touches files directly.
+   touches files directly. Tabs 1-5 are live; tabs 6-8 (Org-Ref · Usage ·
+   Skills) are reference/analytical views added at v0.2.3.
 
 The TUI runs in any terminal (tmux pane, standalone window, attached over SSH).
 It is a passive observer — it never writes to harness state, never alters
@@ -62,8 +63,11 @@ directory paths. Nothing has to be registered in a config file.
 ### 3.4 No overload in the UI
 
 The TUI defaults to ONE view that answers "what is happening right now?". All
-historical depth lives behind explicit key presses. The 5-tab layout is a hard
-upper bound; if a sixth dimension matters we replace, not add.
+historical depth lives behind explicit key presses. v0.2.0 shipped with a
+5-tab layout (Live · Agents · Workflows · Knowledge · Activity); v0.2.3
+added three reference/analytical tabs (Org-Ref · Usage · Skills) for
+recall and analysis without disturbing the live view. The 8-tab layout
+is the new upper bound; if a ninth dimension matters we replace, not add.
 
 ## 4. Event schema
 
@@ -498,7 +502,7 @@ CSS classes + `set_timer` cover every effect below.
 ╠════════════════════════════════════════════════════════════════════════════════════════╣
 ║ ⏵ 02h14m · 142.4k in · 18.2k out · 89.1k cached · est. $2.40 · 2 active · 1 wf        ║
 ╠════════════════════════════════════════════════════════════════════════════════════════╣
-║ 1-5 tabs · / filter · enter detail · q quit · ? help · t time-order · r refresh       ║
+║ 1-8 tabs · / filter · enter detail · q quit · ? help · t time-order · r refresh       ║
 ╚════════════════════════════════════════════════════════════════════════════════════════╝
 ```
 
@@ -534,7 +538,7 @@ CSS classes + `set_timer` cover every effect below.
 ╠════════════════════════════════════════════════════════════════════════════════════════╣
 ║ ⏵ 02h14m · 142.4k in · 18.2k out · 89.1k cached · est. $2.40 · 2 active · 3 wf        ║
 ╠════════════════════════════════════════════════════════════════════════════════════════╣
-║ 1-5 tabs · enter detail · ←/→ select wf · ▸/▾ expand · / filter · q quit · ? help     ║
+║ 1-8 tabs · enter detail · ←/→ select wf · ▸/▾ expand · / filter · q quit · ? help     ║
 ╚════════════════════════════════════════════════════════════════════════════════════════╝
 ```
 
@@ -562,7 +566,7 @@ CSS classes + `set_timer` cover every effect below.
 ╠════════════════════════════════════════════════════════════════════════════════════════╣
 ║ ⏵ 02h14m · 142.4k in · 18.2k out · 89.1k cached · est. $2.40 · 2 active · 1 wf       ║
 ╠════════════════════════════════════════════════════════════════════════════════════════╣
-║ 1-5 tabs · enter detail · j/k row · tab pane · / filter · q quit · ? help            ║
+║ 1-8 tabs · enter detail · j/k row · tab pane · / filter · q quit · ? help            ║
 ╚════════════════════════════════════════════════════════════════════════════════════════╝
 ```
 
@@ -609,7 +613,7 @@ empty state dim-centered.
 ╠════════════════════════════════════════════════════════════════════════════════════════╣
 ║ ⏵ 02h14m · 142.4k in · 18.2k out · 89.1k cached · est. $2.40 · 2 active · 1 wf       ║
 ╠════════════════════════════════════════════════════════════════════════════════════════╣
-║ 1-5 tabs · enter detail · j/k row · tab pane · / filter · q quit · ? help            ║
+║ 1-8 tabs · enter detail · j/k row · tab pane · / filter · q quit · ? help            ║
 ╚════════════════════════════════════════════════════════════════════════════════════════╝
 ```
 
@@ -651,7 +655,7 @@ green / red / yellow / dim. `⟳` for STALE (poll deadline missed, not down).
 ╠════════════════════════════════════════════════════════════════════════════════════════╣
 ║ ⏵ 02h14m · 142.4k in · 18.2k out · 89.1k cached · est. $2.40 · 2 active · 1 wf       ║
 ╠════════════════════════════════════════════════════════════════════════════════════════╣
-║ 1-5 tabs · / filter focus · t order · End auto · j/k scroll · enter detail · q quit  ║
+║ 1-8 tabs · / filter focus · t order · End auto · j/k scroll · enter detail · q quit  ║
 ╚════════════════════════════════════════════════════════════════════════════════════════╝
 ```