@hecer/yoke 0.2.0 → 0.8.0

package/docs/superpowers/specs/2026-07-02-baustein-m-flow-smoke-proofs-design.md

@@ -0,0 +1,155 @@
+# Baustein M — `yoke flow-smoke`: built-in browser gate with screenshot/video proofs
+
+Date: 2026-07-02
+Status: approved (design delegated by user; proof concept approved in conversation: screenshots
+always, video on failure, `.yoke/proof/` storage, loop links proofs to stories)
+
+## Problem
+
+The verify gate is code-only unless an agent hand-rolls a Playwright smoke (the
+`visual-verification` skill teaches it, but nothing enforces or standardizes it). A story can
+pass unit tests and design-scan yet ship a blank page, an unwired route, or a runtime console
+error. And when a story IS done, there is no visual evidence — "done with a photo" is the answer
+to the loudest agentic-coding pain point ("agent says done, but it isn't").
+
+## Goal
+
+A built-in, mechanical browser gate that any project can add to `verify.command`:
+
+```
+yoke flow-smoke [dir] [--url=<baseUrl>] [--label=<name>]
+```
+
+For every configured flow: load the route, optionally wait for a landmark selector, assert zero
+console/page errors, and **always** save a screenshot to `.yoke/proof/<label>/<flow>.png`.
+Record video per flow but **keep it only on failure** (`<flow>.webm`). Exit 0 = all flows green
+(chainable in `verify.command`), 1 = failures, 2 = not runnable (no config / no playwright).
+
+## Part 1: Config schema
+
+Extend `YokeConfigSchema` (src/retrofit/config.ts) with an optional `smoke` section:
+
+```yaml
+smoke:
+  baseUrl: http://localhost:3000
+  flows:
+    - name: home
+      path: /
+      landmark: "main h1"        # optional CSS selector
+    - name: login
+      path: /login
+```
+
+Zod: `smoke: z.object({ baseUrl: z.string().min(1), flows: z.array(z.object({ name: z.string().min(1), path: z.string().min(1), landmark: z.string().optional() })).min(1) }).optional()` and the matching optional field on the `YokeConfig` interface. Existing configs (no `smoke`) stay valid.
+
+## Part 2: `runFlowSmoke` (src/smoke/command.ts)
+
+`export async function runFlowSmoke(targetDir: string, opts: FlowSmokeOptions = {}): Promise<number>`
+
+Sequence:
+1. Load config. No config file or no `smoke` section → print guidance (example YAML above) and
+   exit **2**. `--url` overrides `baseUrl`.
+2. Resolve Playwright **from the target project** (never a Yoke dependency):
+   `createRequire(join(targetDir, 'package.json')).resolve('playwright')`, then dynamic
+   `import(pathToFileURL(resolved).href)`. Resolution failure → print
+   `Playwright not found in <dir>. Install it: npm i -D playwright && npx playwright install chromium`
+   and exit **2**.
+3. Proof dir: `.yoke/proof/<label>/` where label = `opts.label` ?? `process.env.YOKE_STORY` ??
+   `'latest'`. Wipe the label dir before the run (`rmSync(recursive, force)` + mkdir) — each run
+   is fresh evidence, no stale screenshots.
+4. Launch chromium headless once; per flow, create a **new context** with
+   `recordVideo: { dir: <proofDir>/.video-tmp }` and a page. Collect errors: `page.on('console')`
+   with `type() === 'error'`, and `page.on('pageerror')`.
+5. Per flow, in order (fail-fast per flow, continue to the next flow):
+   - `page.goto(baseUrl + path, { waitUntil: 'load', timeout: 30_000 })`; a non-OK response
+     (`!response.ok()`) is a failure (`HTTP <status>`).
+   - if `landmark`: `page.waitForSelector(landmark, { timeout: 10_000 })`; timeout → failure
+     (`landmark "<sel>" not found`).
+   - collected errors non-empty → failure (`N console error(s): <first, truncated 200 chars>`).
+   - **always** `page.screenshot({ path: <proofDir>/<flow.name>.png, fullPage: true })` — also on
+     failure (the failure screenshot IS the evidence), inside try/catch (a crashed page must not
+     mask the original failure).
+   - close context; then: flow failed → move its video to `<proofDir>/<flow.name>.webm`
+     (`page.video().path()` after close); flow passed → delete the video file. Remove
+     `.video-tmp` at the end.
+6. Report per flow: `✔ home (screenshot: .yoke/proof/latest/home.png)` /
+   `✘ login — 2 console error(s): ... (screenshot + video saved)`. Summary line
+   `Flow-smoke: N/M flows green — proof: .yoke/proof/<label>/`.
+7. Close the browser in a `finally`. Exit 0 all green, 1 any failure.
+
+Injectable seam for tests: `opts.browser?: () => Promise<SmokeBrowser>` — a minimal structural
+interface defined in the module:
+
+```ts
+export interface SmokePage {
+  goto(url: string, opts?: object): Promise<{ ok(): boolean; status(): number } | null>
+  waitForSelector(sel: string, opts?: object): Promise<unknown>
+  screenshot(opts: { path: string; fullPage?: boolean }): Promise<unknown>
+  on(event: 'console' | 'pageerror', handler: (arg: any) => void): void
+  video(): { path(): Promise<string> } | null
+}
+export interface SmokeContext { newPage(): Promise<SmokePage>; close(): Promise<void> }
+export interface SmokeBrowser {
+  newContext(opts?: object): Promise<SmokeContext>
+  close(): Promise<void>
+}
+```
+
+The real path adapts Playwright's chromium to this interface; tests inject fakes (no Playwright
+in Yoke's devDependencies — an fs-level fake writes marker files for "screenshot"/"video").
+
+## Part 3: Loop linkage — proofs per story
+
+- In `src/loop/loop.ts`, both verify call sites set `process.env.YOKE_STORY = story.id` before
+  `opts.verify(...)` and delete it in a `finally`. A `yoke flow-smoke` inside `verify.command`
+  then writes to `.yoke/proof/<story-id>/` automatically — every completed story has visual
+  evidence, every blocked story has failure evidence (screenshot + video).
+- `.yoke/proof/` joins `YOKE_IGNORE_LINES` (runtime artifact; must not break the clean-tree gate).
+
+## Part 4: CLI + async main
+
+- `main()` in src/cli.ts becomes `number | Promise<number>`-returning; the isMain block awaits it
+  (top-level await, ESM). Existing sync cases are untouched.
+- `case 'flow-smoke'`: `[dir]`, `--url=`, `--label=` → `return runFlowSmoke(targetDir, { url, label })`.
+- Usage line gains `flow-smoke [dir] [--url=<baseUrl>] [--label=<name>]`.
+
+## Part 5: Canon skill update
+
+`canon/skills/visual-verification/SKILL.md`: replace the hand-rolled flow-smoke instruction with
+the built-in — configure `smoke:` in `.yoke/config.yaml`, chain
+`... && yoke design-scan . && yoke flow-smoke .` in `verify.command`; keep the Playwright-MCP
+guidance for *debugging* a failed flow (watch the saved video first). Mention proofs land in
+`.yoke/proof/<story>/`. Skill count stays 27 (content update, no new skill).
+
+## Testing
+
+- `tests/retrofit/config.test.ts` (extend): smoke section round-trips; config without smoke stays
+  valid; invalid smoke (empty flows) rejected.
+- `tests/smoke/command.test.ts` (fake browser):
+  - exit 2 when no smoke config (message contains example);
+  - exit 2 when playwright is unresolvable: call without `opts.browser` (the seam bypasses
+    resolution) against a temp dir that has a smoke config but no playwright install;
+  - green flow: screenshot file written under `.yoke/proof/latest/<name>.png`, video deleted, exit 0;
+  - landmark timeout → exit 1, screenshot still written, video kept as `<name>.webm`;
+  - console error collected → exit 1;
+  - non-OK response → exit 1;
+  - label resolution: `--label` beats `YOKE_STORY` env beats `latest`;
+  - proof dir wiped between runs (stale file gone);
+  - one failing flow does not stop later flows (both reported).
+- `tests/loop/*`: one test that a fake verifier observes `process.env.YOKE_STORY === story.id`
+  during verify and that it is unset afterwards (both normal and `--isolate` paths if cheap;
+  normal path suffices).
+- `tests/retrofit/gitignore.test.ts`: `.yoke/proof/` ensured.
+
+## Non-goals
+
+- No dev-server startup/readiness management (`start-server-and-test` and friends exist; the
+  skill documents chaining). A connection-refused goto is an ordinary flow failure.
+- No visual diffing/pixel comparison, no multi-browser matrix, no video-always mode (token/disk
+  cost; Ebene C in the Baustein-I backlog stays opt-in future work).
+- Playwright stays a target-project dependency, never Yoke's.
+
+## Attribution
+
+Browser-QA-as-gate idea: gstack `/qa` (MIT © Garry Tan), natively re-implemented cross-agent with
+a proof-artifact contract; no code copied. Extend the existing ATTRIBUTION.md gstack entry.

package/docs/superpowers/specs/2026-07-10-companion-tools-decision.md

@@ -0,0 +1,33 @@
+# Companion tools — integration decision (2026-07-10)
+
+Evaluated four ecosystem projects for integration into Yoke. Criteria: fit with the
+curated-canon promise (small, cross-agent, token-lean), maintenance cost of a vendored
+copy vs. a documented boundary, and overlap with existing canon skills.
+
+## Decisions
+
+| Project | Decision | Form |
+|---|---|---|
+| [claude-mem](https://github.com/thedotmack/claude-mem) (Apache-2.0) | **Integrate as optional companion** | `canon/tools/claude-mem.md` — documented wiring, external installer |
+| [ui-ux-pro-max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) (MIT) | **Integrate as optional companion** | `canon/tools/ui-ux-pro-max.md` — documented pairing, external installer |
+| [ux-ui-mastery](https://github.com/phazurlabs/ux-ui-mastery) (MIT) | **Rejected** | — |
+| [claude-plugins-official](https://github.com/anthropics/claude-plugins-official) | **Not an integration target — a distribution channel** | Yoke itself packaged as a plugin; see the plugin packaging work |
+
+## Rationale
+
+- **claude-mem**: mature, multi-agent, solves a real gap (interactive cross-session memory).
+  But it is a runtime service (worker + vector DB) — the opposite of Yoke's zero-runtime
+  philosophy — so it is wired like rtk/Serena/Playwright MCP: externally installed, boundary
+  documented. Hard rule recorded in the tool doc: **no automatic memory injection inside loop
+  runs** — the loop's memory is the versioned context layer + PRD, by design (reproducibility,
+  reviewability, git history).
+- **ui-ux-pro-max**: complementary, not overlapping — it improves design *generation*; Yoke's
+  `unslop-ui`/`design-scan`/`visual-verification` do design *verification*. It ships its own
+  cross-agent installer and fast update cadence; a vendored copy would go stale. Documented
+  as a pairing, not vendored.
+- **ux-ui-mastery**: rejected. ~310k words across 19 skills would break the curated-canon and
+  token-efficiency promises, it is Claude-only (no cross-agent story), largely redundant with
+  `unslop-ui` + ui-ux-pro-max, and low-traction/low-activity at evaluation time. Users who want
+  it can install it as a Claude plugin alongside Yoke with zero support from us. Revisit only
+  if a specific gap (e.g. an accessibility-audit skill) justifies porting a *single* skill with
+  attribution, as done for superpowers/gstack.

package/docs/superpowers/specs/2026-07-10-multi-agent-parallel-loop-design.md

@@ -0,0 +1,99 @@
+# Multi-agent parallel loop — evaluation & design (2026-07-10)
+
+**Question:** when a project is implemented via the Yoke loop, can we distribute the open
+stories across *many* agents in parallel — and does that actually speed up completion?
+
+**Answer:** yes, with a bounded design — the worktree machinery we already have does most of
+the work — but parallelism pays off only under specific conditions, and it multiplies token
+cost. This doc evaluates where it helps, where it hurts, and specifies a three-phase design.
+
+## Where we start (current state)
+
+- The loop is strictly **serial**: one story at a time, selected by lowest `priority`
+  (`src/loop/prd.ts` — `selectNextStory`), guarded by a single-flight lock (`.yoke/loop.lock`).
+- `--isolate` already gives every story its **own detached git worktree** under
+  `.yoke/worktrees/<story-id>`, merged back with `git merge --ff-only` and discarded on failure.
+  This is exactly the isolation primitive a parallel dispatcher needs.
+- The PRD schema has **no dependency field** — stories are implicitly assumed independent,
+  ordering is a soft hint via `priority`.
+- Two multi-agent mechanisms already exist, both *role-parallel*, not *task-parallel*:
+  the reviewer can be a different agent (`--reviewer=codex`), and the
+  `dispatching-parallel-agents` / `subagent-driven-development` skills cover in-session
+  fan-out *within* one Claude Code session.
+
+## When parallelism actually speeds things up (the honest part)
+
+Parallel story execution helps iff:
+
+1. **Stories are genuinely independent** — no shared files, no semantic coupling. Two stories
+   editing the same module produce merge conflicts or, worse, silently incompatible designs
+   that both pass their own acceptance tests.
+2. **Verify is the short pole, not the long pole.** Each merged story must be verified against
+   the *integrated* tree (merge-queue semantics). If `npm test` takes 10 minutes, merges
+   serialize on verification and N workers approach 1× speedup (Amdahl).
+3. **Wall-clock matters more than spend.** N parallel agents ≈ N× token cost for (at best)
+   ~N× wall-clock speedup on the parallel portion. Parallelism buys *time*, never *efficiency*.
+
+Typical PRDs from `yoke prd draft` (5–12 stories on one small codebase) violate (1) more often
+than not — early stories scaffold what later stories touch. The realistic win is **2–4 workers
+on the independent middle of a backlog**, not 12 workers on 12 stories.
+
+## Design
+
+### Phase 1 — dependency-aware parallel dispatch (`--parallel=N`)
+
+- **PRD schema:** add optional `needs: [story-ids]` per story (default `[]`). `prd.schema.md`
+  documents: "list the stories whose *code* this story builds on." `yoke prd draft` prompts the
+  drafting agent to emit `needs` — it already reasons about ordering when assigning priorities.
+- **Scheduler:** ready-set = open stories (`passes: false`) whose `needs` are all
+  `passes: true`. Dispatcher keeps ≤ N workers busy; each worker claims a story via a per-story
+  claim file (`.yoke/claims/<story-id>.json`, PID + timestamp — same liveness logic as the
+  existing loop lock), runs the full existing pipeline (implement → verify → review) inside its
+  own worktree.
+- **Merge queue (the critical piece):** workers never integrate directly. Completed worktrees
+  enter a FIFO queue; a single integrator (a) rebases the worktree branch onto current HEAD,
+  (b) re-runs verify if HEAD moved since the story's base, (c) ff-merges, (d) marks
+  `passes: true`. Rebase conflict → story goes back to the ready-set with a `merge-conflict`
+  note for the next agent run; the loop's "nothing lands unverified" invariant survives
+  parallelism intact.
+- **Single-flight lock** stays, reinterpreted: it now guards the *dispatcher*, not the story.
+
+### Phase 2 — conflict avoidance (make parallelism worth turning on)
+
+- Optional `area:` label per story (e.g. `area: api`, `area: ui`); the scheduler never runs two
+  stories with the same area concurrently. Cheap, no file-prediction magic, removes the most
+  common conflict class.
+- Record per-story wall-clock + rebase-conflict counts (the benchmark harness in `bench/`
+  measures this from outside today; the reporter should own it) so `--parallel` can be
+  recommended or discouraged per project from *data*.
+
+### Phase 3 — heterogeneous workers (cross-agent dispatch)
+
+Workers need not be the same CLI. Assignment policies, in order of usefulness:
+
+1. **Availability/cost:** cheap-fast model for low-priority stories, strongest model for
+   stories with many dependents (they block the most downstream work).
+2. **Affinity:** per-story `agent:` hint (e.g. Gemini for large-context refactors).
+3. **Review stays cross-model** — implementer ≠ reviewer per story, as today.
+
+Prerequisite: token reporting for gemini/codex runners (today only claude reports usage via
+stream-json), otherwise cost-based policies fly blind.
+
+## What we deliberately do NOT build
+
+- **No shared mutable context between concurrent agents.** Each worker reads the committed
+  context layer at its worktree's base commit. Context/DECISIONS updates land only through the
+  merge queue, serialized. Cross-talk between concurrent agents is how "overnight loop" horror
+  stories happen.
+- **No optimistic file-overlap prediction.** Predicting which files a story will touch before
+  running it is guesswork; `needs` + `area` + rebase-verify catch the same failures mechanically.
+- **No parallelism by default.** Serial stays the default; `--parallel` is opt-in per run,
+  consistent with every other Yoke escalation (`--isolate`, `--review`, loop itself).
+
+## Verdict
+
+Worth building, in this order, behind an opt-in flag: **Phase 1 is ~3 focused Bausteine**
+(PRD `needs` + scheduler/claims + merge queue) on top of primitives that already exist and
+are tested (worktrees, locks, gates). Phase 2 is small and makes Phase 1 honest. Phase 3 is
+where "one harness, three agents" becomes a genuinely unique capability — no other harness
+dispatches one backlog across Claude, Codex, and Gemini concurrently with mechanical gates.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hecer/yoke",
-  "version": "0.2.0",
+  "version": "0.8.0",
   "description": "One harness, three agents, zero trust in \"done\" — cross-agent coding harness for Claude Code, Codex CLI, and Gemini CLI: one skill canon, mechanical safety gates, an autonomous loop with screenshot/video proofs.",
   "type": "module",
   "bin": {
@@ -9,6 +9,9 @@
   "files": [
     "dist",
     "canon",
+    "bench",
+    "docs",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],
@@ -35,7 +38,10 @@
     "code-review",
     "skills",
     "agents-md",
-    "tdd"
+    "tdd",
+    "claude-plugin",
+    "claude-code-plugin",
+    "gemini-cli-extension"
   ],
   "license": "MIT",
   "publishConfig": {