mishkan-harness 0.2.0 → 0.2.3

package/payload/mishkan/workflows/panim-ds-rollout.js

@@ -0,0 +1,83 @@
+// panim-ds-rollout — propagate a design token change across all consumers.
+//
+// A token change (color, spacing, font, radius) is decided at the DS level.
+// This workflow finds every component that consumes it, applies the change
+// per-component (worktree isolation), verifies a11y contrast post-change,
+// runs visual regression snapshots, and gates merge on a 2-reviewer panel.
+//
+// Pattern: pipeline (discover → transform → verify) + worktree + judge panel.
+// ADR D-010 check:
+//   - parallelism: per-component fan-out (≥6 components typical).
+//   - panel orthogonality: Oholiab (DS consistency) + Asaph (a11y contrast)
+//     are distinct lenses, not 70%-overlapping.
+//   - termination predicate: judge accepts/rejects per component.
+//   - synthesis: rollout report with per-component verdict.
+
+export const meta = {
+  name: "panim-ds-rollout",
+  description: "Propagate a design token change across consumers (per-component worktree + a11y + visual regression).",
+  whenToUse: "When a design token changes and the impact spans multiple components.",
+  phases: [{ title: "Discover" }, { title: "Transform" }, { title: "Review" }],
+};
+
+const tokenChange = args?.token_change;
+const project = args?.project ?? ".";
+if (!tokenChange) throw new Error("args.token_change is required (e.g. {token: 'color.primary', from: '#1A73E8', to: '#0B5FCC'})");
+
+const DISCOVERY_SCHEMA = {
+  type: "object", required: ["components"],
+  properties: { components: { type: "array", items: { type: "object", required: ["file", "name"], properties: { file: {type:"string"}, name: {type:"string"}, usage: {type:"string"} } } } },
+};
+const VERDICT_SCHEMA = {
+  type: "object", required: ["accept", "rationale"],
+  properties: { accept: {type:"boolean"}, rationale: {type:"string"}, findings: {type:"array", items:{type:"string"}} },
+};
+
+phase("Discover");
+const discovery = await agent(
+  `Token change: ${JSON.stringify(tokenChange)}. Project: ${project}. Find every component that consumes this token (CSS/SCSS/JS/TS). Return the schema with file paths + component names.`,
+  { schema: DISCOVERY_SCHEMA, label: "discover-consumers", agentType: "oholiab" },
+);
+
+const components = discovery?.components ?? [];
+log(`Discovered ${components.length} consumers of ${tokenChange.token}.`);
+if (!components.length) {
+  return { token_change: tokenChange, components: [], summary: "No consumers found. Token change is safe to merge at the DS level only." };
+}
+
+phase("Transform");
+const transformed = await parallel(components.map(c => () =>
+  agent(
+    `Token change: ${JSON.stringify(tokenChange)}. Component: ${c.file} (${c.name}). Apply the change. Return a short diff summary + any test updates needed.`,
+    { label: `transform:${c.name}`, agentType: "salma", isolation: "worktree", phase: "Transform" },
+  ).then(diff => ({ component: c, diff }))
+));
+
+phase("Review");
+const REVIEWERS = [
+  { key: "ds-consistency", agent: "oholiab", prompt: "DS consistency: does the post-change component still match the DS pattern? Any inconsistency vs other consumers?" },
+  { key: "a11y-contrast",  agent: "asaph",   prompt: "A11y contrast: post-change WCAG contrast ratio compliance, focus-visible, color-only-meaning checks." },
+];
+const reviewed = await parallel(transformed.filter(Boolean).map(t => () =>
+  parallel(REVIEWERS.map(R => () =>
+    agent(
+      `Token change: ${JSON.stringify(tokenChange)}. Component: ${t.component.file}. Diff summary: ${t.diff}. Your lens: ${R.prompt} Default accept=false if uncertain.`,
+      { schema: VERDICT_SCHEMA, label: `review:${R.key}:${t.component.name}`, agentType: R.agent, phase: "Review" },
+    )
+  )).then(verdicts => {
+    const valid = verdicts.filter(Boolean);
+    const accepts = valid.filter(v => v.accept).length;
+    return { component: t.component, diff: t.diff, verdicts: valid, accepted: accepts >= 2 };
+  })
+));
+
+const accepted = reviewed.filter(r => r.accepted);
+const rejected = reviewed.filter(r => !r.accepted);
+
+return {
+  token_change: tokenChange,
+  total_consumers: components.length,
+  accepted: accepted.map(r => r.component.file),
+  rejected: rejected.map(r => ({ file: r.component.file, findings: r.verdicts.flatMap(v => v.findings ?? []) })),
+  summary: `${accepted.length}/${components.length} components accepted by 2/2 reviewers. ${rejected.length} need rework.`,
+};

package/payload/mishkan/workflows/sefer-release-notes.js

@@ -0,0 +1,85 @@
+// sefer-release-notes — assemble release notes from git log per category.
+//
+// Given a tag range (or commit range), categorise commits, summarise per
+// category in parallel by Sefer specialists, then Jehoshaphat (lead) applies
+// the doc style guide and produces RELEASE_NOTES.md.
+//
+// Pattern: pipeline (collect → per-category fan-out → style synthesis).
+// ADR D-010 check:
+//   - parallelism: 4 categories in parallel (feat/fix/breaking/security).
+//   - panel orthogonality: each specialist handles a distinct content layer
+//     (Seraiah org-wide, Joah project-level, Shevna team-level,
+//     Jehonathan publication style).
+//   - synthesis: final markdown produced by Jehoshaphat.
+
+export const meta = {
+  name: "sefer-release-notes",
+  description: "Assemble release notes from git log: per-category summaries, style-guide application, ready-to-publish markdown.",
+  whenToUse: "Every release tag, before publishing to GitHub Releases or npm.",
+  phases: [{ title: "Collect" }, { title: "Summarise" }, { title: "Publish" }],
+};
+
+const fromRef = args?.from_ref;
+const toRef = args?.to_ref ?? "HEAD";
+const project = args?.project ?? ".";
+const releaseTag = args?.release_tag;
+if (!fromRef) throw new Error("args.from_ref is required (previous tag e.g. 'v0.2.0')");
+if (!releaseTag) throw new Error("args.release_tag is required (e.g. 'v0.2.3')");
+
+const COMMITS_SCHEMA = {
+  type: "object", required: ["commits"],
+  properties: { commits: { type: "array", items: { type: "object", required: ["sha", "type", "subject"], properties: { sha:{type:"string"}, type:{type:"string"}, scope:{type:"string"}, subject:{type:"string"}, breaking:{type:"boolean"} } } } },
+};
+const CATEGORY_SCHEMA = {
+  type: "object", required: ["entries"],
+  properties: { entries: { type: "array", items: { type: "object", required: ["title", "description"], properties: { title:{type:"string"}, description:{type:"string"}, references:{type:"array", items:{type:"string"}} } } } },
+};
+
+phase("Collect");
+const collected = await agent(
+  `Project: ${project}. Run \`git log ${fromRef}..${toRef} --pretty=format:'%H|%s'\` and parse commits using conventional-commit format (type(scope) subject). Detect breaking changes (subject contains '!' or body has BREAKING CHANGE). Return the schema.`,
+  { schema: COMMITS_SCHEMA, label: "collect-commits", agentType: "joah" },
+);
+
+const commits = collected?.commits ?? [];
+log(`${commits.length} commits between ${fromRef} and ${toRef}.`);
+
+const byCategory = {
+  feat:     commits.filter(c => c.type === "feat" && !c.breaking),
+  fix:      commits.filter(c => c.type === "fix"),
+  breaking: commits.filter(c => c.breaking),
+  security: commits.filter(c => c.type === "fix" && (c.scope === "security" || /CVE|secur/i.test(c.subject))),
+};
+
+phase("Summarise");
+const CATEGORIES = [
+  { key: "feat",     label: "Features",            agent: "seraiah",    items: byCategory.feat },
+  { key: "fix",      label: "Fixes",               agent: "joah",       items: byCategory.fix },
+  { key: "breaking", label: "Breaking changes",    agent: "shevna",     items: byCategory.breaking },
+  { key: "security", label: "Security",            agent: "jehonathan", items: byCategory.security },
+];
+
+const summaries = await parallel(CATEGORIES.map(C => () =>
+  C.items.length === 0
+    ? Promise.resolve({ category: C.key, label: C.label, entries: [] })
+    : agent(
+        `Release ${releaseTag}. Category: ${C.label}. Commits: ${JSON.stringify(C.items.map(c => ({sha: c.sha.slice(0,7), subject: c.subject})))}. Summarise each into a user-facing entry: title (action verb), description (1-2 sentences, why it matters), commit refs. Return the schema.`,
+        { schema: CATEGORY_SCHEMA, label: `summarise:${C.key}`, agentType: C.agent, phase: "Summarise" },
+      ).then(s => ({ category: C.key, label: C.label, entries: s.entries ?? [] }))
+));
+
+phase("Publish");
+const releaseNotes = await agent(
+  `Release ${releaseTag}. Apply the project's documentation style guide. Summaries by category: ${JSON.stringify(summaries.filter(Boolean))}. Produce RELEASE_NOTES.md with: title line, date, intro paragraph (1-3 sentences), sections per non-empty category (## Features / ## Fixes / ## Breaking changes / ## Security), each entry as a bullet with link to commit. Markdown only — no preamble.`,
+  { label: "publish-notes", agentType: "jehoshaphat", phase: "Publish" },
+);
+
+return {
+  release_tag: releaseTag,
+  from_ref: fromRef,
+  to_ref: toRef,
+  commit_count: commits.length,
+  category_counts: Object.fromEntries(CATEGORIES.map(C => [C.key, C.items.length])),
+  release_notes: releaseNotes,
+  summary: `Release notes for ${releaseTag} assembled: ${commits.length} commits across ${CATEGORIES.filter(C => C.items.length > 0).length} non-empty categories.`,
+};

package/payload/mishkan/workflows/yasad-data-migration-wave.js

@@ -0,0 +1,78 @@
+// yasad-data-migration-wave — per-table DB migration with 4-reviewer panel.
+//
+// A migration plan (one or more tables) goes in; each table is independently
+// reviewed by 4 orthogonal lenses (contracts, perf, security, tests), then
+// verified by running the migration in a worktree against a fresh snapshot.
+//
+// Pattern: pipeline (analyze → per-table review → verify) + judge panel.
+// ADR D-010 check:
+//   - parallelism: tables × 4 reviewers.
+//   - panel orthogonality: Nathan (contracts), Zadok (perf/index),
+//     Shallum (data security/PII), Uriah (tests) — distinct domains.
+//   - synthesis: per-table go/no-go + rollback plan.
+
+export const meta = {
+  name: "yasad-data-migration-wave",
+  description: "Wave of DB migrations, per-table reviewed by 4 orthogonal lenses (contracts/perf/security/tests).",
+  whenToUse: "Before applying a migration that touches multiple tables or has invariant impact.",
+  phases: [{ title: "Analyze" }, { title: "Review" }, { title: "Verify" }],
+};
+
+const migrationPlan = args?.migration_plan;
+const project = args?.project ?? ".";
+const verifyCmd = args?.verify_command;
+if (!migrationPlan) throw new Error("args.migration_plan is required (array of {table, change, reason})");
+
+const REVIEW_SCHEMA = {
+  type: "object", required: ["safe", "rationale"],
+  properties: { safe: {type:"boolean"}, rationale: {type:"string"}, blockers: {type:"array", items:{type:"string"}}, mitigations: {type:"array", items:{type:"string"}} },
+};
+
+phase("Analyze");
+log(`Migration wave: ${migrationPlan.length} tables to review.`);
+
+phase("Review");
+const REVIEWERS = [
+  { key: "contracts", agent: "nathan",  prompt: "API contracts: does this migration break any consumer of this table (endpoints, events, projections)?" },
+  { key: "perf",      agent: "zadok",   prompt: "Performance: index implications, lock duration, table-scan risk, query plan changes for downstream queries." },
+  { key: "security",  agent: "shallum", prompt: "Data security: PII handling, encryption-at-rest changes, RLS impact, audit trail." },
+  { key: "tests",     agent: "uriah",   prompt: "Tests: what tests exist for this table, which break, which are missing. Test plan for the migration itself." },
+];
+
+const reviewed = await parallel(migrationPlan.map(M => () =>
+  parallel(REVIEWERS.map(R => () =>
+    agent(
+      `Migration: table=${M.table}, change=${M.change}, reason=${M.reason}. Project: ${project}. Your lens: ${R.prompt} Default safe=false if uncertain.`,
+      { schema: REVIEW_SCHEMA, label: `review:${R.key}:${M.table}`, agentType: R.agent, phase: "Review" },
+    )
+  )).then(verdicts => {
+    const valid = verdicts.filter(Boolean);
+    const safeCount = valid.filter(v => v.safe).length;
+    const blockers = valid.flatMap(v => v.blockers ?? []);
+    return { migration: M, lens_verdicts: valid, safe_count: safeCount, all_safe: safeCount === REVIEWERS.length, blockers };
+  })
+));
+
+const allSafe = reviewed.filter(r => r.all_safe);
+const blocked = reviewed.filter(r => !r.all_safe);
+log(`${allSafe.length}/${migrationPlan.length} migrations cleared 4/4 lenses.`);
+
+phase("Verify");
+let verifyResult = null;
+if (verifyCmd && allSafe.length === migrationPlan.length) {
+  verifyResult = await agent(
+    `Run \`${verifyCmd}\` to verify the migration applies cleanly against a fresh snapshot. Report stdout/stderr/exit code summary.`,
+    { label: "verify-migration", agentType: "hizkiah", phase: "Verify" },
+  );
+}
+
+return {
+  migration_plan: migrationPlan,
+  reviewed: reviewed.map(r => ({ table: r.migration.table, safe_count: r.safe_count, all_safe: r.all_safe, blockers: r.blockers })),
+  blocked_tables: blocked.map(b => b.migration.table),
+  verify_result: verifyResult,
+  decision: blocked.length === 0 ? "ship" : "block",
+  summary: blocked.length === 0
+    ? `All ${allSafe.length} migrations cleared 4/4 lenses. Verify: ${verifyResult ? "ran" : "skipped"}.`
+    : `${blocked.length} migrations BLOCKED. Address blockers per-table before re-running.`,
+};

package/payload/mishkan/workflows/yasad-schema-evolution.js

@@ -0,0 +1,76 @@
+// yasad-schema-evolution — zero-downtime multi-release schema change orchestration.
+//
+// A schema change that requires phased rollout (dual-write, backfill,
+// switch-read, drop-old) goes in; the workflow plans the phases, validates
+// each phase against zero-downtime invariants, and produces a per-phase
+// runbook with rollback for each step.
+//
+// Pattern: pipeline (plan → per-phase validate) + barrier + judge panel.
+// Differs from yasad-data-migration-wave: this is a SINGLE schema change
+// across MULTIPLE releases, not multiple migrations in one wave.
+
+export const meta = {
+  name: "yasad-schema-evolution",
+  description: "Phase a single schema change across multiple releases with zero-downtime invariants and per-phase rollback.",
+  whenToUse: "Schema change that can't ship atomically — needs dual-write / backfill / switch / drop sequence.",
+  phases: [{ title: "Plan" }, { title: "Validate" }, { title: "Runbook" }],
+};
+
+const change = args?.change;
+const project = args?.project ?? ".";
+if (!change) throw new Error("args.change is required (e.g. {from: 'users.email_text', to: 'users.email_normalized', rationale: '...'})");
+
+const PLAN_SCHEMA = {
+  type: "object", required: ["phases"],
+  properties: { phases: { type: "array", items: { type: "object", required: ["name", "actions", "invariants"], properties: { name: {type:"string"}, actions: {type:"array", items:{type:"string"}}, invariants: {type:"array", items:{type:"string"}}, rollback: {type:"array", items:{type:"string"}}, release: {type:"string"} } } } },
+};
+const VALIDATE_SCHEMA = {
+  type: "object", required: ["safe", "rationale"],
+  properties: { safe: {type:"boolean"}, rationale: {type:"string"}, risks: {type:"array", items:{type:"string"}} },
+};
+
+phase("Plan");
+const plan = await agent(
+  `Schema change: ${JSON.stringify(change)}. Project: ${project}. Plan the phased rollout (typically: add-new-column → dual-write → backfill → switch-read → drop-old). Each phase: actions, invariants that MUST hold during the phase, rollback steps, target release. Return the schema.`,
+  { schema: PLAN_SCHEMA, label: "plan-phases", agentType: "shallum" },
+);
+
+const phases = plan?.phases ?? [];
+log(`Plan: ${phases.length} phases.`);
+
+phase("Validate");
+const REVIEWERS = [
+  { key: "consumer-safety", agent: "nathan",  prompt: "Consumer safety: at every phase boundary, can every existing consumer keep working without code change? Identify breakage windows." },
+  { key: "data-integrity",  agent: "shallum", prompt: "Data integrity: backfill correctness, dual-write consistency, race conditions, idempotency." },
+  { key: "rollback",        agent: "zadok",   prompt: "Rollback: from each phase, is there a clean rollback that doesn't lose data? Identify points of no return." },
+];
+
+const validations = await parallel(phases.map((ph, i) => () =>
+  parallel(REVIEWERS.map(R => () =>
+    agent(
+      `Schema change overall: ${JSON.stringify(change)}. Phase ${i+1}/${phases.length}: ${JSON.stringify(ph)}. Your lens: ${R.prompt} Default safe=false if uncertain.`,
+      { schema: VALIDATE_SCHEMA, label: `validate:${R.key}:${ph.name}`, agentType: R.agent, phase: "Validate" },
+    )
+  )).then(verdicts => {
+    const valid = verdicts.filter(Boolean);
+    const safeCount = valid.filter(v => v.safe).length;
+    return { phase: ph, verdicts: valid, all_safe: safeCount === REVIEWERS.length, risks: valid.flatMap(v => v.risks ?? []) };
+  })
+));
+
+phase("Runbook");
+const runbook = await agent(
+  `Schema change: ${JSON.stringify(change)}. Validated phases: ${JSON.stringify(validations.map(v => ({phase: v.phase.name, safe: v.all_safe, risks: v.risks})))}. Produce a per-phase runbook: pre-checks, exact commands, post-checks, rollback. Markdown.`,
+  { label: "produce-runbook", agentType: "shallum", phase: "Runbook" },
+);
+
+const blocked = validations.filter(v => !v.all_safe);
+return {
+  change,
+  phases: validations.map(v => ({ name: v.phase.name, release: v.phase.release, all_safe: v.all_safe, risks: v.risks })),
+  runbook,
+  decision: blocked.length === 0 ? "ship" : "block",
+  summary: blocked.length === 0
+    ? `Schema evolution validated across ${phases.length} phases by 3/3 reviewers. Runbook produced.`
+    : `${blocked.length}/${phases.length} phases BLOCKED. Address risks before next release.`,
+};

package/payload/mishkan/templates/user-CLAUDE.md

@@ -1,62 +0,0 @@
-# MISHKAN — User-Level Harness Identity
-
-> מִשְׁכָּן — *dwelling place*. The persistent place where engineering work lives.
-> This file installs to `~/.claude/CLAUDE.md`. It loads on every session.
-> Keep it lean — detailed standards live in the rules files it points to.
-
-You are operating inside **MISHKAN**, a personal virtual software engineering
-organisation built around one engineer. Who that engineer is — their identity,
-stack, standards, and how they work — is defined in
-`~/.claude/mishkan/profile.md`. Load it as canonical context.
-
-## Default mode
-
-Sessions start in **exploration mode**: free conversation. **Nehemiah** (PM) and
-**Bezalel** (CTO) lead. Other agents are available on demand and do not interject
-unless called. No structure is imposed until intent is clear or `/mishkan-init`
-runs. Shift to **execution mode** when a spec converges or a project initialises.
-
-## The non-negotiables
-
-> Full detail in two layers: `~/.claude/rules/y4nn-standards.md` (harness-maintained
-> defaults) and `~/.claude/rules/engineer-standards.md` (your customizable layer,
-> which overrides the defaults on conflict). The digest below is drawn from them.
-
-- **Asymmetric AI delegation.** Generative work (UI, config, boilerplate) may be
-  done freely. Stateful operations — `git push`, SSH to production, `docker exec`
-  on production, `sudo`, schema migration execution, log forensics execution —
-  are **never executed by AI**. Analyse; Y4NN runs.
-- **Sequence before implementation.** PRD → SRS → CONTRACT → ARCHITECTURE →
-  MODELING → implementation. Never skip to code without prior spec artifacts.
-- **Verify before fix.** No guess-based reasoning. Exact stacktrace / status /
-  log line before any proposed solution. Two root causes on non-trivial failures.
-- **Durable solutions only.** No workarounds. If it won't work in production from
-  landing, it does not land.
-- **No scope expansion.** The fix is the fix. Refactoring is a separate scoped
-  decision. The approved plan is the scope contract.
-- **No fabricated facts.** State uncertainty explicitly; invoke the research
-  pipeline when unknown.
-- **Explanations before implementation.** Surface trade-offs; gate on approval
-  for consequential decisions.
-- **Stop pending actions immediately when Y4NN speaks** mid-task.
-- **Commit format:** `type(scope) short description` + 5–15 line body. No emojis.
-  No `Co-Authored-By`. Lowercase subject. No terminating period.
-- **Language:** English for all artifacts, code, commands. Do not imitate French.
-
-## Layout
-
-- Agents: `~/.claude/mishkan/agents/` (45 agents — orchestration, research, 6 teams)
-- Rules: `~/.claude/rules/y4nn-standards.md` + `~/.claude/mishkan/rules/`
-- Skills: `~/.claude/mishkan/skills/`
-- Commands: `/mishkan-init`, `/mishkan-resume`, `/sprint-close`, `/promote`, `/sefer-pull`
-- Engineer profile: `~/.claude/mishkan/profile.md` (runtime copy of the canonical `docs/engineer/profile.md`; loaded as engineer context)
-- Knowledge graph: Cognee (local Docker), grows through working sessions
-
-## Routing
-
-Everything routes through Nehemiah (scope, delivery, sprint state) and Bezalel
-(technical standards, architecture, quality bar). Team Leads coordinate within
-teams. QA and Team Reporters are structurally separate from the agents producing
-work — no agent judges its own output.
-
-<!-- Project-specific state is injected below by ./CLAUDE.md when a project is initialised. -->