mishkan-harness 0.2.0 → 0.2.4

package/README.md

@@ -2,83 +2,49 @@
 
 # מִשְׁכָּן · MISHKAN
 
-**A virtual software-engineering organisation that lives inside Claude Code.**
+**A personal SWE R&D harness that lives inside Claude Code.**
 
-*Run a complex SDLC with AI as a disciplined, multi-agent team — design, spec,
-architecture, security, build, review, and docs — instead of a single chat.*
+45 specialist agents · six teams · one research pipeline · one growing knowledge graph
 
 </div>
 
 ---
 
-MISHKAN (*"dwelling place"* — the place where the work resides) turns Claude Code
-into a standing engineering org: **45 specialist agents** across **six teams**, led
-by a PM and a CTO, sharing one research pipeline and one growing knowledge graph.
-Quality and security aren't *requested* of the model — they're **enforced by the
-environment**: path-scoped rules, pre-write security hooks, and generation kept
-structurally separate from review.
+MISHKAN turns Claude Code into a standing engineering organisation. Quality and security aren't requested from the model — they're enforced by the environment: path-scoped rules, pre-write security hooks, structural separation of generation from review. The knowledge graph (Cognee) persists what you learn so sessions pick up where the last one stopped. A code-structure graph (Graphify) answers "who calls X, who depends on Y" at 88× less token cost than loading source files.
 
-It's personal, opinionated infrastructure built around one engineer's standards —
-and shared openly for anyone who wants to try working this way. To make it yours,
-replace one file (your profile) and re-sync; nothing else hardcodes the author.
+It's personal, opinionated infrastructure built around one engineer's standards. To make it yours, replace `docs/engineer/profile.md` and re-sync — nothing else hardcodes the author.
 
-> **Status:** v0.2.0 — early and evolving. The agent fleet, rules, hooks, and
-> installer are complete. The Cognee knowledge stack (work + curated stores) is
-> ready to bring up locally. Live observability (daemon + Textual TUI) ships as
-> an opt-in stack of two `uv tool install`-able Python packages.
+> **v0.2.4** — agent fleet, rules, hooks, installer are stable. Cognee knowledge stack ready to bring up locally. Observability stack (watchd + TUI) available as two `uv tool`-installable packages.
 
 ---
 
-## Three pillars
-
-MISHKAN rests on three things that work together. They are independent — you
-can use each without the others — but they compound:
-
-### 1. A disciplined multi-agent organisation
-
-Most "AI coding" is one model in one chat doing everything at once — generating,
-judging its own output, skipping the spec, drifting scope. MISHKAN refuses that:
+## Install
 
-- **Sequence before code.** PRD → SRS → Contract → Architecture → Threat model →
-  Modeling → implementation. Agents won't jump to code without the upstream artifacts.
-- **Generation ≠ evaluation.** The agent that writes is never the agent that reviews.
-  QA and reporters are structurally separate roles.
-- **Security & dependencies are first-class**, not an afterthought audit.
+Requires Claude Code + Node ≥ 18.
 
-### 2. Deterministic guardrails
+```bash
+npx mishkan-harness install
+mishkan status
+mishkan observability              # optional: daemon + TUI (needs uv)
+```
 
-Quality and security aren't *requested* of the model — they're **enforced by
-the environment**: path-scoped rules, pre-write security hooks, structural
-separation of generation from review. Secrets, injection, unsafe
-deserialization, disabled TLS, `:latest` tags, weak hashing — blocked by a
-hook *before* the write lands, not flagged after.
+Full guide: [`docs/usage/01-installation.md`](docs/usage/01-installation.md).
 
-### 3. A knowledge stack that grows
+## First session
 
-MISHKAN is built around **persisting what you learn**, so future sessions
-start where the last one stopped instead of from zero. Three complementary
-layers (see [D-008](docs/design/MISHKAN_decisions.md)):
+```bash
+cd <project>
+claude                    # starts in exploration mode — Nehemiah + Bezalel
+/mishkan-init             # scaffold: spec chain → docs/ → Cognee → Sprint S0
+```
 
-- **[Cognee work](payload/mishkan/cognee/) (`:7777`)** — per-project semantic
-  graph. ADRs, runbooks, decisions, resolved research — all ingested
-  selectively, then queryable by any agent that hits an unknown.
-- **[Cognee curated](payload/mishkan/cognee/) (`:7730`)** — cross-project
-  reference library. Read-mostly, seeded once, shared across every project on
-  the host.
-- **[Graphify](https://github.com/safishamsi/graphify) (planned, D-008
-  signed)** — deterministic code-structure graph for "who calls X, who depends
-  on Y", complementing Cognee's semantic layer.
+`/sprint-close` at a milestone. `/mishkan-resume` restores state next session. Details: [`docs/usage/02-project-init.md`](docs/usage/02-project-init.md).
 
-Plus a **live observability TUI** ([mishkan-watch](payload/mishkan/observability/))
-that shows every running agent, workflow, tool call, hook fire, token spend,
-and MCP/Cognee status — in real time, across every session, with no overload.
-See [`docs/design/MISHKAN_observability.md`](docs/design/MISHKAN_observability.md).
+---
 
 ## The teams
 
-Two orchestrators route everything: **Nehemiah** (PM — scope, delivery, sprint
-state) and **Bezalel** (CTO — architecture, standards, quality bar). Beneath them,
-six teams, each `Lead → Specialists → QA → Reporter`:
+**Nehemiah** (PM — scope, delivery, sprint) and **Bezalel** (CTO — architecture, standards, quality bar) route everything. Six teams, each `Lead → Specialists → QA → Reporter`:
 
 | Team | Hebrew | Domain |
 |------|--------|--------|
@@ -89,168 +55,138 @@ six teams, each `Lead → Specialists → QA → Reporter`:
 | **Migdal** | *tower* | Infrastructure & ops |
 | **Sefer** | *scroll* | Documentation (pull-based) |
 
-A shared **research pipeline** (Jakin → Ezra → Caleb → Shaphan → Shemaiah →
-Baruch) is invokable by any agent that hits an unknown — clarify, formulate,
-research, summarise, evaluate, report — and every call is logged. Names and their
-biblical sources: [`docs/design/MISHKAN_agent_aliases.md`](docs/design/MISHKAN_agent_aliases.md).
+A shared research pipeline (Jakin → Ezra → Caleb → Shaphan → Shemaiah → Baruch) is invokable by any agent that hits an unknown. All 45 names + biblical sources: [`docs/design/MISHKAN_agent_aliases.md`](docs/design/MISHKAN_agent_aliases.md).
 
-## Install
+---
 
-Requires Claude Code and Node ≥ 18. The installer has **zero npm dependencies**.
+## Knowledge stack
 
-```bash
-npx mishkan-harness install      # or: node bin/mishkan.js install  (from a clone)
-```
+Wired by `/mishkan-init` into each project's `.mcp.json`:
 
-Idempotent and non-destructive: it copies the harness into `~/.claude/mishkan`,
-symlinks agents/skills/commands for discovery, places a user-level `CLAUDE.md` and
-standards rule **only if absent**, and merges its hooks into `settings.json`
-without touching your existing hooks. Paths resolve from your home directory at
-install time — nothing machine-specific is baked in.
+**Cognee** — semantic knowledge graph. Per-project work store (`:7777`) + cross-project curated reference library (`:7730`). Docker-based, pinned, SOPS-managed secrets.
 
 ```bash
-npx mishkan-harness status                # what's installed
-npx mishkan-harness observability         # install/refresh just the daemon + TUI (needs `uv`)
-npx mishkan-harness uninstall             # remove harness; keep your CLAUDE.md & rules
-npx mishkan-harness uninstall --purge     # also remove the user-level rule
+mishkan configure-knowledge        # wizard: LLM provider + credentials + .env
+cd ~/.claude/mishkan/cognee
+docker compose -f docker-compose.yml -f docker-compose.hardening.yml up -d --build
+~/.claude/mishkan/scripts/seed-curated-library.sh
 ```
 
-The installer walks 7 phases with clear progress, asks once whether to install
-the observability stack at the end, and skips that step cleanly if `uv` isn't
-installed.
-
-## A first session
-
-1. Run `claude` anywhere. You're talking to **Nehemiah** and **Bezalel** in
-   *exploration mode* — free conversation, no ceremony.
-2. Think out loud. When intent is clear, run **`/mishkan-init`** to scaffold the
-   project: the spec chain, `docs/`, a seeded knowledge graph, and Sprint S0.
-3. Work the sprint. Every write is security-scanned; QA evaluates; reporters collect.
-4. **`/sprint-close`** at a milestone. **`/mishkan-resume`** next session restores
-   state and open blockers.
+Guide: [`payload/mishkan/cognee/README.md`](payload/mishkan/cognee/README.md) · [`docs/usage/04-memory-layer.md`](docs/usage/04-memory-layer.md).
 
-### Commands
+**Graphify** — deterministic code-structure graph (D-008 + D-009). Indexes a project's full AST into a queryable graph. For structural questions ("who calls X", "what depends on Y") it costs ~1.8k tokens per query — 88× cheaper than loading the source tree. Runs as a PreToolUse advisory: before every structural Read or Grep, agents see a palette of four surfaces (Graphify, Cognee work, Cognee curated, literal content) with token costs and staleness signals so they pick the cheap path first. Auto-detected and wired by `/mishkan-init`.
 
-| Command | Does |
-|---|---|
-| `/mishkan-init` | Scaffold a project; begin Sprint S0 |
-| `/mishkan-resume` | Restore sprint state + blockers |
-| `/sprint-close` | Reporters → aggregate → docs pull → graph promote |
-| `/dep-audit` | Cross-project dependency & supply-chain audit |
-| `/promote` | Promote knowledge by blast radius |
-| `/sefer-pull` | Trigger a documentation pull |
+```bash
+mishkan code-graph scan            # build/refresh for the current project
+mishkan code-graph status          # node/edge count, last scan time
+```
 
-## Make it yours
+## Observability
 
-The harness serves the engineer described in
-[`docs/engineer/profile.md`](docs/engineer/profile.md) — the single, replaceable
-source of truth. Swap in your own (keep the section structure), then:
+Two Python packages (`uv tool`-installable): a daemon (`mishkan-watchd`) that tails every session's event bus and a Textual TUI (`mishkan-watch`) with 8 tabs — Live, Agents, Workflows, Knowledge, Activity, Org-Ref, Usage, Skills. Cross-session, cross-project, near-zero overhead.
 
 ```bash
-~/.claude/mishkan/scripts/sync-profile.sh
+mishkan observability              # install both packages
+mishkan-watch                      # opens TUI, auto-starts daemon if absent
+mishkan-watchd start|stop|status   # manual daemon control
 ```
 
-That refreshes the runtime copy and audits references. **Seraiah** (the docs
-org-layer agent) owns re-deriving anything drawn from it. See
-[`docs/engineer/README.md`](docs/engineer/README.md).
+Guide + event schema: [`docs/design/MISHKAN_observability.md`](docs/design/MISHKAN_observability.md).
 
-## Dependency & supply-chain
+## Workflows
 
-- **Before adopting any package** — the `dependency-vetting` skill drives the
-  research pipeline through OSV/NVD CVEs, maintenance health, typosquatting, and
-  provenance, then gives a go/no-go.
-- **Across every project you own** — `/dep-audit` inventories all repos under your
-  workspace (discovery-based, no hardcoded paths), aggregates shared CVEs and
-  version drift, and produces a coordinated, vetted update plan.
+Beyond the agents, MISHKAN ships dynamic JavaScript workflows that orchestrate multiple subagents in parallel — fan-out/synthesize, pipeline, judge panel, adversarial verify, loop-until-X.
 
-## Knowledge stack
+**Org-level (10):** `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`.
 
-MISHKAN uses [Cognee](https://docs.cognee.ai) as its **two-store knowledge
-graph** that grows as you work. Cognee core is a Python library; the harness
-consumes it through the **`cognee-mcp`** server. Agents can still work without
-it — persistence is just deferred. Run the **cognee-quickstart** skill for
-guided setup, or the hardened Docker deployment under
-`~/.claude/mishkan/cognee/`:
+**Team-level (8):** `chosheb-feature-ship`, `panim-ds-rollout`, `yasad-data-migration-wave`, `yasad-schema-evolution`, `mishmar-security-gate`, `migdal-infra-change`, `migdal-dr-drill`, `sefer-release-notes`.
 
-```bash
-cd ~/.claude/mishkan/cognee
-cp .env.example .env          # set LLM_API_KEY + COGNEE_MCP_REF (pinned), SOPS-managed
-docker compose -f docker-compose.yml -f docker-compose.hardening.yml up -d --build
-nc -z localhost 7777 && echo up
-~/.claude/mishkan/scripts/seed-curated-library.sh      # 96 curated references
-```
+Governed by hard caps (10 org + 4 per team) and PM+CTO co-ownership per ADR D-010. Catalogue + cost expectations: [`payload/mishkan/workflows/README.md`](payload/mishkan/workflows/README.md).
 
-Agents reach the work store at `http://localhost:7777/mcp` and the curated
-store at `:7730`, both seeded by `/mishkan-init` into each project's
-`.mcp.json`. The deployment is pinned, SOPS-managed, hardening-overlay on
-every recreate, `127.0.0.1`-bound. Full guide:
-[`payload/mishkan/cognee/README.md`](payload/mishkan/cognee/README.md).
+---
 
-## Live observability (opt-in)
+## Slash commands (inside a Claude Code session)
 
-See **everything** that runs across your MISHKAN sessions in a single Textual
-TUI: active agents, workflows-in-flight, token spend ($), file changes, hook
-decisions, Cognee node counts, MCP server status. Cross-session,
-cross-project, near-zero overhead. Two `uv tool`-installable Python packages:
+| Command | Purpose |
+|---|---|
+| `/mishkan-init` | Scaffold a project — spec chain, docs, Cognee, Sprint S0 |
+| `/mishkan-resume` | Restore sprint state + open blockers |
+| `/sprint-close` | Team reporters → aggregate → docs pull → graph promote |
+| `/mishkan-org-reference` | Print the 45-agent org inline |
+| `/code-graph status\|open\|scan` | Inspect / open / refresh Graphify graph |
+| `/skills <task>` | Skill-discovery router (3-bucket result) |
+| `/mishkan-skills-reindex` | Rebuild skill index from disk |
+| `/mishkan-skills-misses` | Aggregate miss-log for threshold tuning |
+| `/eval-baruch` | Run Baruch contract eval |
+| `/dep-audit` | Cross-project dependency + supply-chain audit |
+| `/promote` | Promote a learning into Cognee by blast radius |
+| `/sefer-pull` | Trigger documentation pull |
+
+## CLI commands (from any terminal)
 
 ```bash
-# the installer offers this automatically; or run it standalone any time:
-npx mishkan-harness observability
-
-# then, in two tmux panes (or any two terminals):
-mishkan-watchd start                    # daemon — aggregates the bus
-mishkan-watch                           # TUI client — 5 tabs, status bar
+mishkan help                                        # full reference
+mishkan install                                     # install/refresh into ~/.claude
+mishkan uninstall                                   # remove harness (keeps CLAUDE.md + rules)
+mishkan uninstall --purge                           # also remove y4nn-standards.md
+mishkan configure-knowledge                         # wizard: LLM provider + Cognee .env
+mishkan observability                               # install daemon + TUI only (needs uv)
+mishkan status                                      # install state, profile, version
+mishkan org [--json]                                # print the 45-agent org
+mishkan code-graph [status|open|scan]               # inspect the project's Graphify graph
+mishkan-watch                                       # open observability TUI (auto-starts daemon)
+mishkan-watch --no-autostart                        # TUI only, no daemon fork
+mishkan-watchd start|stop|status                    # manual daemon lifecycle
 ```
 
-Full operator guide: [`docs/usage/10-observability.md`](docs/usage/10-observability.md).
-Design and event schema: [`docs/design/MISHKAN_observability.md`](docs/design/MISHKAN_observability.md).
+---
 
-## Token & context management
+## Customisation
 
-MISHKAN doesn't replace Claude's context handling — it **shapes the inputs** so
-the model's native behaviour works in your favour. Five mechanisms, each riding a
-Claude/Claude Code primitive:
+The harness serves the engineer described in [`docs/engineer/profile.md`](docs/engineer/profile.md). Swap in your own (keep the section structure), then:
 
-- **Prompt caching** — agents are ordered *static role/standards/rules first,
-  dynamic task last*, so the stable prefix caches and you pay full price only for
-  what changes.
-- **Subagent isolation** — heavy work runs in disposable child windows; only
-  summaries return, so the main thread stays lean (and disabling auto-compaction
-  stays low-risk).
-- **Tight tool grants** & **path-scoped rules** — agents carry only the tool
-  schemas and rules relevant to the file in hand.
-- **Cognee offloading** — full artifacts live in the graph; context holds
-  summaries.
+```bash
+~/.claude/mishkan/scripts/sync-profile.sh
+```
 
-Model tiering is the complementary cost axis (`config/model-routing.yaml`): Opus
-for orchestration/leads, Sonnet for anything that writes code, Haiku for
-evaluate/collect/advise.
+Refreshes the runtime copy and audits references. Nothing else hardcodes the author. See [`docs/engineer/README.md`](docs/engineer/README.md).
 
-→ Full operational detail, the cost model, and honest gaps:
-[`docs/design/MISHKAN_token_optimisation.md`](docs/design/MISHKAN_token_optimisation.md).
+---
 
 ## Repository layout
 
 ```
 bin/mishkan.js              installer (dependency-free)
-payload/                    what gets installed into ~/.claude
+payload/
   mishkan/                    agents, skills, rules, hooks, commands, templates, config, scripts, ontology
   user/                       user-level CLAUDE.md + standards rule (placed if absent)
   install/                    hook fragment merged into settings.json
 docs/
-  engineer/                   the canonical, replaceable engineer profile
-  design/
-    MISHKAN_harness_design.md       architecture (5 layers, 6 teams, knowledge model)
-    MISHKAN_agent_aliases.md        the 45 agents and their sources
-    MISHKAN_decisions.md            locked build decisions
-    MISHKAN_ontology.md             Cognee graph schema
-    MISHKAN_token_optimisation.md   how context/token use leverages Claude primitives
+  engineer/                   canonical engineer profile (replaceable)
+  design/                     architecture, decisions, ontology, token model, observability
+  usage/                      01-install … 12-skill-discovery
 ```
 
-## License
+---
 
-MIT — use it, fork it, make it serve your own engineering.
+## Key design docs
+
+| Doc | Covers |
+|---|---|
+| [Architecture](docs/design/MISHKAN_harness_design.md) | 5 layers, 6 teams, knowledge model |
+| [Agent aliases](docs/design/MISHKAN_agent_aliases.md) | 45 agents + biblical sources |
+| [Decisions](docs/design/MISHKAN_decisions.md) | Locked build decisions |
+| [Cognee ontology](docs/design/MISHKAN_ontology.md) | Knowledge graph schema |
+| [Token optimisation](docs/design/MISHKAN_token_optimisation.md) | Context cost model |
+| [Observability](docs/design/MISHKAN_observability.md) | Daemon + TUI event schema |
+| [Workflows](payload/mishkan/workflows/README.md) | Dynamic workflow catalogue |
+
+Usage guides: [`docs/usage/`](docs/usage/).
 
 ---
 
+## License
+
+MIT — use it, fork it, make it serve your own engineering.
+
 Built by **`>_theY4NN`** · [github.com/Y4NN777](https://github.com/Y4NN777)