mishkan-harness 0.1.0

package/payload/mishkan/skills/salma-frontend-implementation-craft/SKILL.md

@@ -0,0 +1,369 @@
+---
+name: salma-frontend-implementation-craft
+description: How Salma implements the visible product against the design system and the API contract — the no-raw-fetch rule, TanStack Query / Router patterns, component co-location, the design-system-only styling rule, state-management discipline, and the responsive/dark-mode/motion implementation contracts. Invoke when implementing frontend features.
+---
+
+# Salma — Frontend Implementation Craft
+
+> Not a checklist. How the builder who clothes and covers reasons when
+> handed a Chosheb handoff and a Yasad contract — what she builds, what
+> she refuses to bend, and the rule that she implements the visible
+> product faithfully against the two contracts above her.
+
+Invoked when frontend implementation is in scope. Salma works in a
+React / Nuxt 3 / Vue 3 / TypeScript world; the principles are
+framework-agnostic where they can be, framework-specific where they
+must be.
+
+---
+
+## 1. The rule above all other rules
+
+**You implement against two contracts: the Chosheb handoff and the
+Yasad API contract. You do not edit either.**
+
+Three corollaries:
+
+- **No design decisions.** If the handoff is ambiguous, you stop and
+  ask Hiram via Huram. You do not "fill in" tasteful defaults; you
+  surface and wait.
+- **No contract negotiations.** If the API contract is awkward, you
+  stop and route to Huram for Lead-to-Lead with Zerubbabel. You do
+  not invent your own shape over it.
+- **No silent state-management additions.** Adding a global store,
+  introducing a new state primitive, or changing the data layer is
+  an architectural change — `/plan` first.
+
+---
+
+## 2. The questions before writing a component
+
+1. **Which handoff package does this implement?** Quote it. If the
+   handoff is missing, stop.
+2. **Which contract endpoints does this consume?** Quote them. If
+   the contract is missing, stop.
+3. **What is the empty state?** Show it in the implementation, not
+   only the loaded state.
+4. **What is the loading state?** Skeleton, suspense boundary, or
+   a placeholder strategy.
+5. **What is the error state?** Recoverable error UI + a retry path
+   where the contract supports it.
+6. **What is the responsive behaviour?** Implemented to the handoff's
+   breakpoints, not improvised.
+7. **What is the dark-mode behaviour?** Implemented to the handoff;
+   no auto-inversion.
+8. **What is the test?** The contract test (E2E for the surface;
+   component test for the component).
+
+---
+
+## 3. Data — TanStack Query, never raw fetch
+
+The data layer rules:
+
+```typescript
+// WRONG — raw fetch in a component
+function Dashboard() {
+  const [data, setData] = useState(null);
+  useEffect(() => {
+    fetch("/api/projects").then(r => r.json()).then(setData);
+  }, []);
+  // ...
+}
+
+// RIGHT — TanStack Query through a typed wrapper
+function Dashboard() {
+  const { data, isLoading, error } = useProjects();
+  if (isLoading) return <ProjectsListSkeleton />;
+  if (error) return <ProjectsLoadError onRetry={refetch} />;
+  return <ProjectsList projects={data} />;
+}
+```
+
+Three rules:
+
+- **No `useEffect` for data fetching.** TanStack Query owns caching,
+  refetching, deduplication, retry semantics.
+- **Queries are typed at the API client layer.** A `useProjects()`
+  hook composed over a generated OpenAPI client; not ad-hoc
+  fetching.
+- **Mutations use `useMutation`.** Optimistic updates through
+  `onMutate` / `onError` rollback; never component-local optimistic
+  state.
+
+---
+
+## 4. Routing — TanStack Router (when React) / Nuxt routes / Vue Router
+
+Three rules:
+
+- **Routes are typed.** A `<Link to="/projects/$id">` checks the
+  parameter shape at compile time.
+- **Loader functions for required data.** Data needed before a
+  route renders loads in the route's loader; not in a `useEffect`
+  inside the component.
+- **Search params are typed.** A page with filters reads typed
+  search params, not raw `URLSearchParams`.
+
+---
+
+## 5. Components — co-located, contracted, tested
+
+Component file structure:
+
+```
+components/MetricTile/
+  MetricTile.tsx
+  MetricTile.test.tsx
+  MetricTile.stories.tsx
+  index.ts
+```
+
+Three rules:
+
+- **Co-location.** Component, test, story live together. Moving the
+  component moves all three.
+- **Props are typed.** No `any`. No `Record<string, unknown>` for
+  props; if the shape is dynamic, it has a discriminated union.
+- **One component per file.** Helper components used only by this
+  component live as sub-files in the same directory.
+
+---
+
+## 6. Styling — design tokens, never raw utility classes
+
+The discipline matches `oholiab-design-system-craft` §3:
+
+```tsx
+// WRONG — raw colour utility classes
+<div className="bg-slate-700 text-zinc-400">
+
+// RIGHT — semantic tokens through the theme wrapper
+<div className={cn(theme.surface.default, theme.text.muted)}>
+```
+
+Three rules:
+
+- **No raw Tailwind colour / spacing utilities.** Use the system
+  tokens. Raw utilities bypass the theming layer.
+- **No inline `style={{ }}`.** Inline styles cannot be themed and
+  cannot be visually-tested in Storybook.
+- **No `!important`.** Ever. An `!important` is a specificity
+  bug waiting to fire.
+
+---
+
+## 7. State management — local-first, escalate by need
+
+The state hierarchy:
+
+1. **Component local state.** `useState` for ephemeral UI.
+2. **URL state.** Filters, tabs, sort — in the URL so back/forward
+   work and the page is shareable.
+3. **TanStack Query cache.** Server state. Already cached; do not
+   duplicate into a global store.
+4. **Form state.** React Hook Form (or equivalent) for forms with
+   validation.
+5. **Global state.** Pinia / Zustand for genuinely global UI state
+   (theme, modal stack, command palette). Last resort.
+
+Three rules:
+
+- **Do not duplicate server state into Zustand / Pinia.** TanStack
+  Query is the cache; a Zustand mirror is a stale-divergence bug
+  waiting to fire.
+- **Start local; escalate by need.** Local → URL → server cache →
+  global. Each step is a deliberate decision.
+- **Global state additions trigger `/plan`.** New global stores are
+  architectural.
+
+---
+
+## 8. Responsive + dark-mode + motion — implement the handoff exactly
+
+Salma does not improvise these. The handoff specifies; Salma
+implements.
+
+- **Responsive breakpoints come from the handoff** (or the token
+  system's breakpoint scale). Custom one-off breakpoints are gaps
+  to surface.
+- **Dark mode swaps the theme attribute** (`[data-theme="dark"]`);
+  components do not branch on theme in JS.
+- **Motion uses the system's timing tokens** and respects
+  `prefers-reduced-motion` with the static fallback from the
+  handoff.
+
+---
+
+## 9. Testing — three layers
+
+| Layer | What it tests | Tool |
+|---|---|---|
+| Unit / component | The component contract | Vitest + Testing Library |
+| Integration | A page or feature with API mocked at the boundary | Vitest + MSW |
+| E2E | The golden path against a real backend | Playwright |
+
+Three rules:
+
+- **Contract tests are the primary surface.** E2E tests cover the
+  contract clauses end-to-end. Implementation tests fill gaps.
+- **MSW mocks the contract, not the implementation.** The mock
+  returns shapes from the OpenAPI; if the contract changes, the
+  mock changes.
+- **Do not mock TanStack Query itself.** Mock at the network
+  (MSW) or at the typed client; TanStack Query is the cache, not
+  the seam.
+
+---
+
+## 10. Worked example — implementing the dashboard empty state
+
+Hiram's handoff (`hiram-ui-craft` §8); Yasad's `GET /projects`
+contract returning the list. Salma's path:
+
+**§2 answers:**
+
+1. Handoff: `handoff/dashboard-empty-state/`.
+2. Contract: `GET /projects → ProjectsListResponse` with empty array
+   for no projects.
+3. Empty state: implemented per handoff.
+4. Loading: `<ProjectsListSkeleton>` (system component).
+5. Error: `<ProjectsLoadError>` with retry.
+6. Responsive: 360 / 768 / 1024 breakpoints from handoff.
+7. Dark mode: `[data-theme="dark"]` swap, tokens from handoff.
+8. Test: E2E (Playwright) + integration (Vitest + MSW).
+
+**Implementation:**
+
+```tsx
+// routes/dashboard.tsx
+export const Route = createFileRoute("/dashboard")({
+  loader: ({ context }) => context.queryClient.ensureQueryData(projectsQuery),
+  component: DashboardPage,
+});
+
+function DashboardPage() {
+  const { data: projects, isLoading, error, refetch } = useProjects();
+  if (isLoading) return <ProjectsListSkeleton />;
+  if (error) return <ProjectsLoadError onRetry={refetch} />;
+  if (projects.length === 0) return <DashboardEmptyState />;
+  return <ProjectsList projects={projects} />;
+}
+
+// components/DashboardEmptyState/DashboardEmptyState.tsx
+function DashboardEmptyState() {
+  const { t } = useTranslation();
+  return (
+    <main aria-labelledby="empty-heading" className={cn(theme.surface.default, "py-12")}>
+      <SurfaceIllustration.Empty role="img" aria-label={t("dashboard.empty.illustration_alt")} />
+      <h1 id="empty-heading" className={cn(theme.text.primary, "text-2xl font-semibold mt-6")}>
+        {t("dashboard.empty.title")}
+      </h1>
+      <p className={cn(theme.text.muted, "mt-2")}>{t("dashboard.empty.description")}</p>
+      <div className="mt-6 flex gap-3">
+        <Button variant="primary" autoFocus>
+          {t("dashboard.empty.create")}
+        </Button>
+        <Button variant="ghost">
+          {t("dashboard.empty.import")}
+        </Button>
+      </div>
+    </main>
+  );
+}
+```
+
+**Tests:**
+
+```tsx
+// E2E (Playwright)
+test("dashboard empty state shows when user has no projects", async ({ page }) => {
+  await page.route("**/api/projects", route =>
+    route.fulfill({ json: { data: [] } }));
+  await page.goto("/dashboard");
+  await expect(page.getByRole("heading", { name: /start your first project/i })).toBeVisible();
+  await expect(page.getByRole("button", { name: /create project/i })).toBeFocused();
+});
+
+// Integration (Vitest + MSW)
+test("DashboardEmptyState renders accessibly", async () => {
+  render(<DashboardEmptyState />);
+  expect(screen.getByRole("img")).toHaveAccessibleName(/empty workspace/i);
+  expect(screen.getByRole("button", { name: /create project/i })).toHaveFocus();
+});
+```
+
+What Salma did:
+
+- Used TanStack Router's loader for data + React component for UI.
+- Used TanStack Query through `useProjects`.
+- Tokenised every style.
+- Implemented dark mode through theme tokens, not branching.
+- Tested at E2E + integration layers.
+
+What Salma did NOT:
+
+- Improvise a different empty-state design.
+- Inline a colour.
+- Skip the import button "because the import flow doesn't exist yet" —
+  the handoff specifies it; the button exists, the click handler
+  surfaces the not-yet state.
+
+---
+
+## 11. The recurring traps Salma rejects on sight
+
+1. **"I'll use raw fetch; it's simpler."** §3. TanStack Query
+   exists precisely because raw fetch hides cache + refetch + retry
+   semantics.
+
+2. **"This needs a Zustand store; the data is used in three
+   places."** §7. TanStack Query already caches it. Three reads
+   from the same query key = one fetch.
+
+3. **"I'll inline the hex; the token doesn't exist yet."** §6. No.
+   Surface the token gap to Oholiab; do not inline.
+
+4. **"`!important` is the fastest fix."** §6. Always wrong.
+
+5. **"I'll add a small refactor to the data hook while I'm
+   here."** Standards §4 — no scope expansion.
+
+6. **"The handoff is ambiguous, but I think I know what they
+   meant."** §1. Stop and surface.
+
+7. **"E2E tests are slow; I'll just write unit tests."** §9.
+   Contract tests are the primary surface. E2E coverage of the
+   contract clauses is mandatory.
+
+8. **"I'll skip the empty state; the user has data 99% of the
+   time."** §2.3. The 1% is the first impression.
+
+---
+
+## 12. Style — Salma's voice
+
+- **Boring implementation.** Clever in a UI component is a future
+  bug.
+- **Tokens everywhere.** A `theme.text.muted` reads cleaner than
+  `text-zinc-400` even if the visual output is identical.
+- **Tests in the same PR.** A component shipped without its tests
+  ships incomplete.
+- **Honest at the seams.** Ambiguous handoff or contract = stop,
+  surface, wait.
+
+The builder who clothes and covers gives the system its visible
+form. The form is faithful to the design and the contract; it does
+not improvise.
+
+---
+
+*Cross-references: `~/.claude/rules/y4nn-standards.md`
+(durable §3, no-scope-expansion §4, naming §11),
+`payload/mishkan/skills/team-lead-craft/SKILL.md` (Huram routes to
+Salma), `payload/mishkan/skills/hiram-ui-craft/SKILL.md` (the
+design handoff), `payload/mishkan/skills/oholiab-design-system-
+craft/SKILL.md` (the system Salma styles against),
+`payload/mishkan/skills/zadok-contract-craft/SKILL.md` (the API
+contract Salma consumes), `payload/mishkan/skills/qa-evaluation-
+craft/SKILL.md` (Jahaziel evaluates Salma's work).*

package/payload/mishkan/skills/sefer-pull/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: sefer-pull
+description: Run a Sefer documentation pull. Two modes — sequential pull at every sprint milestone (after all Team Reporters surface), and triggered pull on high-blast-radius events (major architecture decision, critical security finding closed, schema change). Reads Cognee + reporter outputs, writes to docs/ only.
+---
+
+# sefer-pull
+
+Drive a Sefer documentation pull. Sefer is pull-based: it never writes code, only
+`docs/`. It reads from Cognee and Team Reporter outputs.
+
+## Mode A — sequential pull (at milestone)
+
+Fires at every sprint milestone after all Team Reporters have surfaced.
+
+1. Jehoshaphat coordinates. Pull all reporter outputs + relevant Cognee nodes.
+2. **Joah** updates project-layer docs: changelog (Keep a Changelog), ADRs
+   (MADR) for decisions made this sprint, API docs (from OpenAPI), runbook revisions.
+3. **Shevna** updates team-layer docs: component library, security posture, infra
+   topology, per-team outputs.
+4. **Seraiah** updates org-layer docs if cross-project standards changed.
+5. **Jehonathan** publishes the human-readable docs from the graph.
+6. **Huldah** assembles the Sefer team-report.
+
+## Mode B — triggered pull (event-driven, no waiting for milestone)
+
+Fires immediately on a high-blast-radius event:
+- major architecture decision by Bezalel/Nathan → update ARCHITECTURE + ADR
+- critical security finding closed by Phinehas → update THREAT_MODEL + security posture
+- schema change by Shallum → update data docs + migration runbook
+
+Pull only from the team that triggered it; update only the affected docs.
+
+## Constraints
+
+Writes to `docs/` only — never code. Every doc dated, Diátaxis quadrant declared,
+sourced from Cognee/reporters (no fabrication). Stateful operations hard stop.
+English only.