mishkan-harness 0.1.0 → 0.2.3

package/README.md

@@ -2,54 +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:** early and evolving. Used daily, not yet battle-hardened for everyone.
-> The agent fleet, rules, hooks, and installer are complete; the Cognee knowledge
-> graph is opt-in (bring up a local container) and some integration points are
-> marked as such below.
+> **v0.2.1** — 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.
 
 ---
 
-## Why
+## Install
+
+Requires Claude Code + Node ≥ 18.
+
+```bash
+npx mishkan-harness install
+mishkan status
+mishkan observability              # optional: daemon + TUI (needs uv)
+```
+
+Full guide: [`docs/usage/01-installation.md`](docs/usage/01-installation.md).
 
-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:
+## First session
 
-- **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.
-- **Deterministic guardrails.** Secrets, injection, unsafe deserialization, disabled
-  TLS, `:latest` tags, weak hashing — blocked by a hook *before* the write lands,
-  not flagged after.
-- **Security & dependencies are first-class**, not an afterthought audit.
-- **It learns.** Resolved research and decisions become nodes in a knowledge graph
-  (Cognee) that grows through use.
+```bash
+cd <project>
+claude                    # starts in exploration mode — Nehemiah + Bezalel
+/mishkan-init             # scaffold: spec chain → docs/ → Cognee → Sprint S0
+```
+
+`/sprint-close` at a milestone. `/mishkan-resume` restores state next session. Details: [`docs/usage/02-project-init.md`](docs/usage/02-project-init.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 |
 |------|--------|--------|
@@ -60,146 +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
+---
+
+## Knowledge stack
+
+Wired by `/mishkan-init` into each project's `.mcp.json`:
 
-Requires Claude Code and Node ≥ 18. The installer has **zero npm dependencies**.
+**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 install      # or: node bin/mishkan.js install  (from a clone)
+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
 ```
 
-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.
+Guide: [`payload/mishkan/cognee/README.md`](payload/mishkan/cognee/README.md) · [`docs/usage/04-memory-layer.md`](docs/usage/04-memory-layer.md).
+
+**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`.
 
 ```bash
-npx mishkan-harness status                # what's installed
-npx mishkan-harness uninstall             # remove harness; keep your CLAUDE.md & rules
-npx mishkan-harness uninstall --purge     # also remove the user-level rule
+mishkan code-graph scan            # build/refresh for the current project
+mishkan code-graph status          # node/edge count, last scan time
 ```
 
-## A first session
+## Observability
 
-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.
+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.
 
-### Commands
+```bash
+mishkan observability              # install both packages
+mishkan-watch                      # opens TUI, auto-starts daemon if absent
+mishkan-watchd start|stop|status   # manual daemon control
+```
 
-| 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 |
+Guide + event schema: [`docs/design/MISHKAN_observability.md`](docs/design/MISHKAN_observability.md).
 
-## Make it yours
+## Workflows
 
-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:
+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.
 
-```bash
-~/.claude/mishkan/scripts/sync-profile.sh
-```
+**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`.
 
-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).
+**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`.
 
-## Dependency & supply-chain
+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).
 
-- **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.
+---
 
-## Knowledge graph (optional)
+## Slash commands (inside a Claude Code session)
 
-MISHKAN uses [Cognee](https://docs.cognee.ai) as the knowledge graph that grows as
-you work. Cognee core is a Python library; the harness consumes it through the
-**`cognee-mcp`** server. Optional at first run — agents work without it; only
-persistence is deferred. Run the **cognee-quickstart** skill for guided setup, or
-the hardened Docker deployment under `~/.claude/mishkan/cognee/` (HTTP transport,
-port 7777):
+| 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
-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
+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
+```
+
+---
+
+## Customisation
+
+The harness serves the engineer described in [`docs/engineer/profile.md`](docs/engineer/profile.md). Swap in your own (keep the section structure), then:
+
+```bash
+~/.claude/mishkan/scripts/sync-profile.sh
 ```
 
-Agents reach it via each project's `.mcp.json` (seeded by `/mishkan-init`): the
-default is HTTP transport to `http://localhost:7777/mcp`, with a zero-container
-stdio alternative included. The deployment follows the infra rules — built from a
-pinned `Dockerfile` (no `:latest`), SOPS secrets, hardening overlay on every
-recreate, `127.0.0.1`-bound. Pin `COGNEE_MCP_REF` to a release and confirm details
-against [Cognee's docs](https://docs.cognee.ai/cognee-mcp/mcp-local-setup).
-Full guide: [`payload/mishkan/cognee/README.md`](payload/mishkan/cognee/README.md).
-
-## Token & context management
-
-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:
-
-- **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.
-
-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.
-
-→ Full operational detail, the cost model, and honest gaps:
-[`docs/design/MISHKAN_token_optimisation.md`](docs/design/MISHKAN_token_optimisation.md).
+Refreshes the runtime copy and audits references. Nothing else hardcodes the author. See [`docs/engineer/README.md`](docs/engineer/README.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)