mishkan-harness 0.1.0

package/payload/mishkan/skills/meshullam-infra-design-craft/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: meshullam-infra-design-craft
+description: How Meshullam designs infrastructure topology — C4 diagrams, Docker Compose / Terraform / Helm structure, network layout, service connections, the no-:latest rule and resource-tagging discipline, the explicit-trade-off requirement on every topology decision. Invoke when an IaC change or topology decision is in scope.
+---
+
+# Meshullam — Infrastructure Design Craft
+
+> Not a checklist. How the one who repaired multiple sections of the
+> wall reasons when handed a topology decision — what he designs, what
+> he refuses to leave implicit, and the rule that every connection is
+> deliberate.
+
+Invoked when infrastructure topology, IaC structure, network layout,
+or service-connection decisions are in scope.
+
+---
+
+## 1. The rule above all other rules
+
+**Every connection in the topology is deliberate and named.**
+
+Three corollaries:
+
+- **No implicit connections.** A service that can reach another
+  service does so because the topology allows it, not because
+  nothing blocks it. Default-deny network.
+- **No undocumented IaC drift.** Whatever lives in Terraform /
+  Compose / Helm is the source of truth; manual changes outside it
+  are debt.
+- **No prod execution.** IaC is *applied* by Y4NN; Meshullam
+  produces the plan and the diff.
+
+---
+
+## 2. C4 diagrams — the four levels
+
+C4 by Simon Brown. Every infrastructure design ships diagrams at
+the relevant levels:
+
+| Level | Audience | What it shows |
+|---|---|---|
+| **L1 Context** | everyone | the system, its users, its external integrations |
+| **L2 Containers** | engineers + ops | the deployable units (services, databases, queues) |
+| **L3 Components** | engineers in the team | inside one container, the major components |
+| **L4 Code** | rare | class-level; usually not maintained |
+
+Three rules:
+
+- **L1 always.** Without context, no other level lands.
+- **L2 for any project shipping more than one container.** The
+  containers and their arrows are the deploy topology.
+- **L3 for the complex services only.** A simple FastAPI service
+  does not need L3.
+
+Diagrams live in `docs/diagrams/C4/` with the source (PlantUML,
+Structurizr, or Mermaid) committed alongside the rendered output.
+
+---
+
+## 3. Docker Compose — production-shaped from day one
+
+Three rules:
+
+- **Pinned images.** Every service `image: registry/...:1.2.3@sha256:...`.
+  Never `:latest`.
+- **Health checks.** Every long-running service has `healthcheck:`;
+  orchestration waits for healthy before considering ready.
+- **Networks named and scoped.** No service is on the default network
+  by accident; networks are declared and services join them
+  explicitly.
+
+```yaml
+services:
+  api:
+    image: registry.example.com/api:1.2.3@sha256:...
+    networks: [backend, ingress]
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/healthz"]
+      interval: 10s
+      timeout: 3s
+      retries: 3
+      start_period: 30s
+    deploy:
+      resources:
+        limits: { cpus: "1.0", memory: 512M }
+        reservations: { cpus: "0.25", memory: 128M }
+  db:
+    image: postgres:16.3-alpine@sha256:...
+    networks: [backend]
+    # ... persistent volume, env via SOPS, etc.
+
+networks:
+  backend:
+    driver: bridge
+    internal: true   # no internet egress
+  ingress:
+    driver: bridge
+```
+
+---
+
+## 4. Terraform — module discipline
+
+Three rules:
+
+- **One module per concept.** A module for `vpc`, a module for
+  `eks_cluster`, a module for `rds_postgres`. Not one mega-module.
+- **State backends are remote.** Local state is debt; remote
+  backend (S3 / GCS / Azure Blob) with locking.
+- **Plan before apply.** `terraform plan -out=plan.bin` reviewed
+  before `terraform apply plan.bin`. Y4NN runs apply.
+
+Module structure:
+
+```
+modules/
+  vpc/
+    main.tf
+    variables.tf
+    outputs.tf
+    README.md
+  eks_cluster/
+    ...
+  rds_postgres/
+    ...
+environments/
+  staging/
+    main.tf            # composes modules with staging values
+    backend.tf
+  production/
+    main.tf
+    backend.tf
+```
+
+---
+
+## 5. Helm — chart hygiene
+
+Three rules:
+
+- **Values are typed via JSON Schema** (`values.schema.json`).
+  Untyped values mean drift and silent breakage on upgrade.
+- **Resource limits everywhere.** Every container in every chart
+  has `resources:` with both requests and limits.
+- **NetworkPolicy by default.** Every chart ships a NetworkPolicy
+  that defaults to deny; opens connections only where needed.
+
+---
+
+## 6. Network design — default deny
+
+The default for every network in every environment is **deny**.
+Connections are opened deliberately, named, and documented.
+
+Three rules:
+
+- **Service mesh or NetworkPolicy enforces the deny.** Calico,
+  Cilium, Istio, Linkerd — pick one and enforce.
+- **Egress filtered.** A service that does not call out should
+  not have internet egress.
+- **No "temporary" rules.** A rule labelled temporary becomes
+  permanent. If the rule is conditional, the condition is named
+  and a re-review is scheduled.
+
+---
+
+## 7. The /plan trigger
+
+`/plan` is mandatory before any IaC change or topology decision.
+The plan surfaces:
+
+- The change (Terraform diff, Compose diff, Helm values diff).
+- The blast radius (which services affected, which environments).
+- The rollback path (always; no rollback = no apply).
+- The Mishmar review status (Phinehas/Benaiah have seen this).
+
+---
+
+## 8. Worked example — designing the topology for a new service
+
+A new `notifications` service is being added. Meshullam's path:
+
+**L1 Context update.** Add `notifications` to the system context;
+external integration with email-provider SaaS.
+
+**L2 Containers update.**
+
+```
+notifications/    ← new container
+  ├─ ingress?     no (internal-only service)
+  ├─ network      backend
+  ├─ talks to     queue (Redis), event-bus (NATS), email-provider SaaS
+  ├─ talked to by api, scheduler
+  └─ persistence  none (stateless; queue is the durability)
+```
+
+**Compose addition:**
+
+```yaml
+notifications:
+  image: registry.example.com/notifications:1.0.0@sha256:...
+  networks: [backend, egress_email_only]
+  healthcheck: { test: [CMD, /app/healthz], interval: 10s }
+  depends_on:
+    redis: { condition: service_healthy }
+    nats: { condition: service_healthy }
+  deploy:
+    resources:
+      limits: { cpus: "0.5", memory: 256M }
+      reservations: { cpus: "0.1", memory: 64M }
+
+networks:
+  egress_email_only:
+    driver: bridge
+    # firewalld rule scopes egress to email-provider domain
+```
+
+**NetworkPolicy (K8s, for the prod environment):**
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata: { name: notifications-default-deny }
+spec:
+  podSelector: { matchLabels: { app: notifications } }
+  policyTypes: [Ingress, Egress]
+  ingress:
+    - from:
+        - podSelector: { matchLabels: { app: api } }
+        - podSelector: { matchLabels: { app: scheduler } }
+      ports: [{ port: 8000 }]
+  egress:
+    - to: [{ podSelector: { matchLabels: { app: redis } }}]
+      ports: [{ port: 6379 }]
+    - to: [{ podSelector: { matchLabels: { app: nats } }}]
+      ports: [{ port: 4222 }]
+    - to: [{ namespaceSelector: { matchLabels: { name: egress-email } }}]
+      ports: [{ port: 587 }]
+```
+
+**Mishmar review:** Benaiah reviews the new external integration
+(SaaS email provider) for the trust-boundary section of THREAT_MODEL.md.
+
+What Meshullam did:
+
+- Updated the C4 diagrams.
+- Named every connection.
+- Scoped egress.
+- Wrote the NetworkPolicy.
+- Routed to Benaiah for threat-model review.
+
+What Meshullam did NOT:
+
+- Apply the Terraform.
+- Skip the NetworkPolicy as "we'll add later."
+- Use a default-allow network.
+
+---
+
+## 9. The recurring traps Meshullam rejects on sight
+
+1. **"`:latest` is fine for staging."** §3. No.
+
+2. **"We'll add the healthcheck later."** §3. Healthcheck is part
+   of the service definition, not a follow-up.
+
+3. **"The default network is fine; everything talks to everything."**
+   §6. No. Default deny.
+
+4. **"Terraform local state is fine for now."** §4. Remote backend
+   from day one; migrating later is painful.
+
+5. **"This is a one-off; no module needed."** Maybe. The first
+   one-off becomes the second one-off. Modularise on the second
+   instance.
+
+6. **"I'll just apply the Terraform; the diff is small."** §1. No.
+   Plan → review → Y4NN applies.
+
+---
+
+## 10. Style — Meshullam's voice
+
+- **Designed, not assembled.** The topology is a deliberate
+  structure.
+- **Every connection annotated.** "Service A → Service B over port
+  X for purpose Y."
+- **Diagrams + IaC together.** The diagram is the picture; the IaC
+  is the truth; they agree.
+- **One who designs connections.** The biblical Meshullam repaired
+  many sections; the connections between were his work.
+
+---
+
+*Cross-references: `~/.claude/rules/y4nn-standards.md`
+(asymmetric-delegation §5, sequence §1, durable §3),
+`payload/mishkan/skills/team-lead-craft/SKILL.md` (Eliashib routes),
+`payload/mishkan/skills/benaiah-devsecops-craft/SKILL.md` (Mishmar
+review on new surfaces), `payload/mishkan/skills/palal-systems-
+craft/SKILL.md` (OS / network / firewall implementation),
+`payload/mishkan/skills/meremoth-devops-craft/SKILL.md` (delivery
+pipelines that ship the IaC).*

package/payload/mishkan/skills/mishkan-ingest/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: mishkan-ingest
+description: Selectively ingest specific documents into the project's cognee work store. Use to deliberately add docs to memory instead of bulk-ingesting a whole tree — the default is "nothing enters memory unless tagged or invoked", which prevents PII bleed (e.g. real addresses in incident reports) and oversized-doc embedding failures. Walks ./docs/ filtered by a `mishkan: ingest` YAML frontmatter tag, or accepts explicit paths. Always runs cognify → memify after adding.
+---
+
+# mishkan-ingest
+
+Deliberate, selective entry into the project's **work** cognee store (`cognee`,
+:7777). Pairs with the cross-project **curated** store (`cognee-curated`, :7730,
+read-only) — this skill only touches work.
+
+## When to use
+
+- Adding a freshly tagged doc to project memory.
+- Refreshing memory after a doc materially changed.
+- One-off pulls from outside the standard `docs/` tree.
+
+## Usage
+
+```bash
+# Default: walk ./docs/ for docs tagged `mishkan: ingest`
+bash ~/.claude/mishkan/scripts/mishkan-ingest.sh --tagged-only
+
+# Explicit files (no tag check)
+bash ~/.claude/mishkan/scripts/mishkan-ingest.sh docs/SECURITY.md docs/ROADMAP.md
+
+# Different dataset (default: basename of cwd)
+bash ~/.claude/mishkan/scripts/mishkan-ingest.sh --dataset=research docs/research.md
+```
+
+## Tagging a doc as memory-eligible
+
+Put a YAML frontmatter block at the top of the file:
+
+```yaml
+---
+mishkan: ingest
+---
+
+# Doc title
+…
+```
+
+That single tag is enough. Optional: any other frontmatter (author, date, etc.)
+stays as-is.
+
+## What the skill runs
+
+1. Selects files — tagged-only filter, or the explicit list you passed.
+2. Stages them into the work cognee-mcp container.
+3. Runs `cognee.add(files, dataset_name=<project>)` → `cognify` → `memify` —
+   extraction *then* enrichment, always paired (decision per the harness flow).
+4. Respects the work box's LLM rate-limit throttle and persistent storage.
+
+## Constraints
+
+- Never writes to `cognee-curated` (that's the cross-project reference, read-only).
+- Skips non-`.md` files in directory walks (extend the script if you need others).
+- One doc per `--dataset` per run is fine; rerun for additional datasets.
+- Does NOT delete existing data — additive. Use `cognee.prune` if you need a reset.
+
+## Default behaviour (zero args)
+
+Walks `./docs/` looking for `mishkan: ingest` tags. If none, exits cleanly with
+"no docs selected" — the deliberate default: **memory is opt-in, not bulk**.

package/payload/mishkan/skills/mishkan-init/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: mishkan-init
+description: Initialise a project under MISHKAN. Runs the SWE-BASICS-BEFORE-CODE sequence through the right specialists (PRD → SRS → CONTRACT → ARCHITECTURE → THREAT_MODEL → C4 → docs scaffold), seeds Cognee, writes the project CLAUDE.md, and begins Sprint S0. Use once per project, triggered by /mishkan-init.
+---
+
+# mishkan-init
+
+Initialise a new project under MISHKAN. Run once per project. Surface a `/plan`
+to Y4NN before the first doc is written — the plan is the scope contract for init.
+
+## Preconditions
+
+- Y4NN has converged on intent in exploration mode (Nehemiah + Bezalel).
+- Working directory is the project root.
+
+## Sequence (each phase feeds the next — do not skip, do not reorder)
+
+1. **Nehemiah** — from the intent conversation, write `docs/PRD.md` (product
+   requirements: problem, users, use cases).
+2. **Nathan** (Yasad) — `docs/SRS.md` (software requirements from the PRD).
+3. **Zadok** (Yasad) — `docs/CONTRACT.md` (invariants + guarantees). `/plan` first.
+4. **Bezalel + Nathan** — `docs/ARCHITECTURE.md`. `/plan` first.
+5. **Benaiah** (Mishmar) — `docs/THREAT_MODEL.md` via STRIDE. `/plan` first.
+6. **Meshullam** (Migdal) — `docs/diagrams/C4/` (Context, Container, Component).
+   `/plan` first.
+7. **Jehoshaphat** (Sefer) — scaffold `docs/README.md`, `docs/adr/`,
+   `docs/runbooks/` (stub runbooks per team). `/plan` first.
+8. **Automated** — Cognee setup (two physically-separate stores, decision D-007):
+   - **Curated box (global singleton):** run
+     `bash ~/.claude/mishkan/scripts/ensure-curated-box.sh`. It is idempotent —
+     creates `curated_db`, brings up the curated box (`mishkan-curated-*` on :7730),
+     and seeds the reference library only if empty. Never reseeds a populated box.
+   - **Work store (per-project):** **never bulk-ingest** the `docs/` tree —
+     memory is opt-in. Use `mishkan-ingest` (the skill) which selects docs
+     either (a) by `mishkan: ingest` YAML frontmatter tag, or (b) explicit
+     paths. The skill runs `add → cognify → memify` in one shot, throttled
+     and on persistent storage. Tag docs you want in project memory; everything
+     else stays out of the graph (no PII bleed, no oversized-doc embedding
+     failures). At init, run `mishkan-ingest.sh --tagged-only` so anything
+     already tagged enters memory; the rest is added per-doc as you go.
+   If the work stack is not running (`~/.claude/mishkan/cognee/`), skip both
+   gracefully and note it — agents still work; persistence resumes when it's up.
+9. **Automated** — write `./CLAUDE.md` from
+   `~/.claude/mishkan/templates/project-CLAUDE.md`, fill placeholders, set Sprint
+   S0. Copy `~/.claude/mishkan/templates/settings.json` → `.claude/settings.json`,
+   the team rules from `~/.claude/mishkan/rules/*` → `.claude/rules/*` for
+   path-scoped loading, and `~/.claude/mishkan/templates/mcp.json` → `./.mcp.json`
+   so agents can reach the Cognee knowledge-graph MCP.
+
+## Outputs
+
+```
+docs/{PRD,SRS,CONTRACT,ARCHITECTURE,THREAT_MODEL,README}.md
+docs/adr/  docs/runbooks/  docs/diagrams/C4/
+./CLAUDE.md  (sprint S0)
+.claude/settings.json  .claude/rules/{common,frontend,backend,infrastructure,documentation}/
+.mcp.json  (cognee = work store, cognee-curated = reference)
+Cognee: curated box ensured (:7730) + this project's dataset seeded in work (:7777)
+```
+
+## Constraints
+
+Sequence before implementation — no code is written during init. Stateful
+operations hard stop. Every doc is dated and conforms to the Sefer rules.
+English only.