@cloverleaf/reference-impl 0.6.1 → 0.6.3

package/README.md

@@ -96,10 +96,16 @@ The installer (`install.sh`) automatically runs the Playwright browser install s
 
     npx playwright install chromium webkit firefox
 
-On **Linux**, webkit additionally requires system-level dependencies:
+On **Linux**, webkit additionally requires system-level dependencies. By default `install.sh` installs webkit deps only:
 
     npx playwright install-deps webkit
 
+To also install firefox system deps (enabling the full chromium + webkit + firefox browser matrix for the UI Reviewer), pass `--with-cross-browser` to the installer:
+
+    ./install.sh --with-cross-browser
+
+This runs `npx playwright install-deps webkit firefox` instead. When the flag is omitted, `install.sh` prints a note reminding you how to enable cross-browser support later.
+
 **Disk footprint:** approximately 600–650 MB total across all three browsers in the default `PLAYWRIGHT_BROWSERS_PATH` location (`~/.cache/ms-playwright/`).
 
 | Browser   | Approx. size |

package/dist/prep-worktree.mjs

@@ -115,6 +115,7 @@ export function prepWorktree(mainRoot, worktreePath) {
     //      EEXIST on vite/node_modules/.bin on second invocation).
     primeCopy(mainStandardNm, wtStandardNm);
     primeCopy(mainRefImplNm, wtRefImplNm);
+    primeCopy(join(resolvedMain, 'reference-impl', 'dist'), join(worktreePath, 'reference-impl', 'dist'));
     execSync('npm run build', {
         cwd: join(worktreePath, 'standard'),
         stdio: 'pipe',

package/dist/state.mjs

@@ -0,0 +1,97 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import { randomUUID } from 'node:crypto';
+import { tasksDir, projectsDir } from './paths.mjs';
+import { emitStatusTransition, formatReason } from './events.mjs';
+// Import validator from @cloverleaf/standard.
+// The standard package ships TypeScript source only with no exports map.
+// Vitest (via vite-node) resolves .js → .ts for workspace symlinked packages,
+// so the .js convention works here. If it ever fails with "module not found",
+// switch the specifier to '@cloverleaf/standard/validators/index.ts'.
+import { validateStatusTransitionLegality } from '@cloverleaf/standard/validators/index.js';
+import { validateOrThrow } from './validate.mjs';
+const req = createRequire(import.meta.url);
+export function loadTask(repoRoot, taskId) {
+    const path = join(tasksDir(repoRoot), `${taskId}.json`);
+    if (!existsSync(path))
+        throw new Error(`Task ${taskId} not found at ${path}`);
+    return JSON.parse(readFileSync(path, 'utf-8'));
+}
+export function saveTask(repoRoot, task) {
+    validateOrThrow('https://cloverleaf.example/schemas/task.schema.json', task);
+    const path = join(tasksDir(repoRoot), `${task.id}.json`);
+    writeFileSync(path, JSON.stringify(task, null, 2) + '\n');
+}
+export function loadProject(repoRoot, projectId) {
+    const path = join(projectsDir(repoRoot), `${projectId}.json`);
+    if (!existsSync(path))
+        throw new Error(`Project ${projectId} not found at ${path}`);
+    return JSON.parse(readFileSync(path, 'utf-8'));
+}
+function loadTaskStateMachine() {
+    // state-machines/task.json is a static JSON asset. Navigate from standard's
+    // package.json — no exports map support needed.
+    const pkgPath = req.resolve('@cloverleaf/standard/package.json');
+    const pkgDir = pkgPath.replace(/\/package\.json$/, '');
+    return JSON.parse(readFileSync(`${pkgDir}/state-machines/task.json`, 'utf-8'));
+}
+export function advanceStatus(repoRoot, taskId, toStatus, actor, options = {}) {
+    const task = loadTask(repoRoot, taskId);
+    const from = task.status;
+    const sm = loadTaskStateMachine();
+    // Read risk_class directly from the task (defaulting to 'low' if absent).
+    // The validator derives itemPath from workItem.risk_class: low → fast_lane, else full_pipeline.
+    // If caller passed options.path, translate it back to risk_class for the validator.
+    const riskClass = options.path === 'fast_lane' ? 'low'
+        : options.path === 'full_pipeline' ? 'high'
+            : (task.risk_class ?? 'low');
+    // Build a minimal Task-shaped object so the validator can resolve path-tagged transitions.
+    const workItemForValidator = {
+        type: 'task',
+        id: task.id,
+        project: task.project,
+        status: task.status,
+        risk_class: riskClass,
+        context: { rfc: { project: task.project, id: task.id } },
+        definition_of_done: task.definition_of_done,
+        acceptance_criteria: task.acceptance_criteria,
+    };
+    const reason = formatReason({ gate: options.gate, path: options.path });
+    const event = {
+        event_id: randomUUID(),
+        event_type: 'status_transition',
+        occurred_at: new Date().toISOString(),
+        work_item_id: { project: task.project, id: task.id },
+        work_item_type: 'task',
+        from_status: from,
+        to_status: toStatus,
+        actor: { kind: actor, id: actor },
+        ...(reason ? { reason } : {}),
+    };
+    const result = validateStatusTransitionLegality(event, sm, workItemForValidator);
+    if (!result.ok) {
+        const msgs = result.violations.map((v) => v.message).join('; ');
+        throw new Error(`Illegal transition ${from} → ${toStatus}: ${msgs}`);
+    }
+    // NEW: emit first, save second. validateStatusTransitionLegality stays above.
+    const emittedPath = emitStatusTransition(repoRoot, {
+        project: task.project,
+        workItemType: 'task',
+        workItemId: task.id,
+        from,
+        to: toStatus,
+        actor,
+        gate: options.gate,
+        path: options.path,
+    });
+    const proposed = { ...task, status: toStatus };
+    try {
+        saveTask(repoRoot, proposed);
+    }
+    catch (err) {
+        const inner = err instanceof Error ? err.message : String(err);
+        throw new Error(`orphan event written to ${emittedPath} but task save failed: ${inner}`);
+    }
+    return proposed;
+}

package/install.sh

@@ -7,10 +7,23 @@ set -euo pipefail
 # `claude plugin` CLI. Point Claude Code at the cloverleaf repo root (where
 # .claude-plugin/marketplace.json lives), then install the plugin from the
 # resulting marketplace.
+#
+# Flags:
+#   --with-cross-browser   On Linux, also install firefox system deps (in
+#                          addition to webkit) so the UI Reviewer can run the
+#                          full chromium + webkit + firefox browser matrix.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
 
+# Parse flags from "$@".
+WITH_CROSS_BROWSER=0
+for arg in "$@"; do
+  case "$arg" in
+    --with-cross-browser) WITH_CROSS_BROWSER=1 ;;
+  esac
+done
+
 if ! command -v claude >/dev/null 2>&1; then
   echo "error: 'claude' CLI not found on PATH."
   echo "Install Claude Code first: https://docs.claude.com/claude-code"
@@ -50,11 +63,19 @@ echo ""
 
 npx playwright install chromium webkit firefox
 
-# On Linux, system deps for webkit are also required.
+# On Linux, system deps are also required.
 if [ "$(uname -s)" = "Linux" ]; then
   echo ""
-  echo "Linux detected — installing webkit system dependencies..."
-  npx playwright install-deps webkit
+  if [ "$WITH_CROSS_BROWSER" = "1" ]; then
+    echo "Linux detected — installing webkit + firefox system dependencies (--with-cross-browser)..."
+    npx playwright install-deps webkit firefox
+  else
+    echo "Linux detected — installing webkit system dependencies..."
+    npx playwright install-deps webkit
+    echo ""
+    echo "Note: to also install firefox system dependencies for full cross-browser"
+    echo "  UI review support, re-run with: ./install.sh --with-cross-browser"
+  fi
 fi
 
 echo ""

package/lib/prep-worktree.ts

@@ -128,6 +128,7 @@ export function prepWorktree(mainRoot: string, worktreePath: string): void {
   //      EEXIST on vite/node_modules/.bin on second invocation).
   primeCopy(mainStandardNm, wtStandardNm);
   primeCopy(mainRefImplNm, wtRefImplNm);
+  primeCopy(join(resolvedMain, 'reference-impl', 'dist'), join(worktreePath, 'reference-impl', 'dist'));
 
   execSync('npm run build', {
     cwd: join(worktreePath, 'standard'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit",
     "build": "tsc -p tsconfig.build.json && node scripts/rename-to-mjs.mjs",
     "acceptance:walker": "bash scripts/acceptance-walker.sh",
-    "prepublishOnly": "npm test && npm run build"
+    "prepublishOnly": "node scripts/check-standard-prepped.mjs && npm test && npm run build"
   },
   "dependencies": {
     "@cloverleaf/standard": "^0.4.0",

package/prompts/documenter.md

@@ -10,6 +10,14 @@ You are the Cloverleaf Documenter. Your job: produce doc-only commits that updat
 - **Repo root**: {{repo_root}}
 - **Diff from base**: {{diff}}
 
+## Pre-flight — ensure correct working directory
+
+```bash
+cd "$(git rev-parse --show-toplevel)"
+```
+
+Run this as the first executable step before anything else. Session B sessions may inherit an arbitrary `cwd` from the walker harness; this anchors you at the repo root.
+
 ## Tool constraints
 
 - Use `git worktree add <temp> {{branch}}` to work on an isolated checkout. Do NOT `git checkout` in the main working directory.

package/prompts/implementer.md

@@ -11,6 +11,14 @@ You are the Cloverleaf Implementer agent. Your job: take a Task and produce work
 
 ## Your process
 
+0. **Pre-flight — ensure correct working directory.**
+
+   ```bash
+   cd "$(git rev-parse --show-toplevel)"
+   ```
+
+   Run this as the first executable step before anything else. Session B sessions may inherit an arbitrary `cwd` from the walker harness; this anchors you at the repo root.
+
 1. Read the task's `title`, `acceptance_criteria`, `definition_of_done`, and `context`. Read any referenced files.
 2. If `feedback` is present, re-read each finding; plan how to address them.
 3. Create a new branch named `cloverleaf/<task.id>` from `base_branch` using `git checkout -b cloverleaf/<task.id>`.

package/prompts/qa.md

@@ -17,6 +17,14 @@ The Standard's QA contract requires a `preview_uri`. You were passed the sentine
 
 ## Runtime procedure
 
+0. **Pre-flight — ensure correct working directory.**
+
+   ```bash
+   cd "$(git rev-parse --show-toplevel)"
+   ```
+
+   Run this as the first executable step before anything else. Session B sessions may inherit an arbitrary `cwd` from the walker harness; this anchors you at the repo root.
+
 1. Set up isolated worktree and prepare its node_modules + standard/dist. The `prep-worktree`
    helper copies main's `standard/node_modules` and `reference-impl/node_modules` into the
    worktree and runs the standard build script so the @cloverleaf/standard symlink resolves

package/prompts/reviewer.md

@@ -11,6 +11,14 @@ You are the Cloverleaf Reviewer agent. Your job: perform a fresh-eyes review of
 
 ## Your process
 
+0. **Pre-flight — ensure correct working directory.**
+
+   ```bash
+   cd "$(git rev-parse --show-toplevel)"
+   ```
+
+   Run this as the first executable step before anything else. Session B sessions may inherit an arbitrary `cwd` from the walker harness; this anchors you at the repo root.
+
 1. Read the task's `acceptance_criteria` and `definition_of_done`.
 2. Run `git diff <base_branch>..<branch> --stat` and `git diff <base_branch>..<branch>` to see the change.
 3. For each acceptance criterion, determine whether the diff satisfies it. Note any unsatisfied criteria as findings.

package/prompts/ui-reviewer.md

@@ -2,6 +2,14 @@
 
 You are the Cloverleaf UI Reviewer. Your job: review a task's UI changes at multiple viewports and browser engines for accessibility violations (axe-core) and visual regressions (pixelmatch) using headless Playwright browsers. You are read-only for source code and tests — but you DO write baseline/diff artifacts under `.cloverleaf/` on the feature branch.
 
+## Pre-flight — ensure correct working directory
+
+```bash
+cd "$(git rev-parse --show-toplevel)"
+```
+
+Run this as the first executable step before anything else. Session B sessions may inherit an arbitrary `cwd` from the walker harness; this anchors you at the repo root.
+
 ## Input
 
 - **Task**: {{task}}

package/skills/cloverleaf-run/SKILL.md

@@ -7,7 +7,9 @@ description: End-to-end orchestrator. Reads task.risk_class to dispatch fast lan
 
 ## Branch discipline
 
-Each sub-skill runs from `main`. Between steps, confirm branch is `main` before proceeding. All sub-skills return the user to `main`.
+`<repo_root>` is `$(git rev-parse --show-toplevel)` of your current working directory. In walker context (Session B inside `$WORKTREE_ROOT`), this is the worktree path, NOT the primary repo. Pass `<repo_root>` explicitly to every `cloverleaf-cli` invocation, and run `git add .cloverleaf/ && git commit` from `<repo_root>` so state-advance commits land on the worktree's current branch (`cloverleaf/<TASK-ID>` in walker mode).
+
+Do NOT `git checkout main` from a walker worktree — main is held by the primary repo. To compare against main, use `git diff main..HEAD` or `git show main:<path>`. Sub-skills run from the worktree's current branch and stay on it; the walker (in the primary repo) does the final merge to main itself after all tasks reach final-gate.
 
 ## Per-agent bounce budget
 

package/skills/cloverleaf-run-plan/SKILL.md

@@ -178,15 +178,38 @@ description: Autonomous DAG walker for Cloverleaf Plans. Given a PLAN-ID in stat
 
    If every task in the plan's `task_dag.nodes` has `state: "merged"`, print: "✓ Plan `<PLAN-ID>` complete."
 
+   ## Next steps (release publishing)
+
+   Once all tasks are merged, run the following commands in order to tag and publish the release:
+
+   ```bash
+   git tag -a reference-impl-v<VERSION> -m "reference-impl v<VERSION>"
+   git push origin main
+   git push origin reference-impl-v<VERSION>
+   (cd reference-impl && npm publish --access public)
+   gh release create reference-impl-v<VERSION> --title "reference-impl v<VERSION>" --notes-from-tag
+   ```
+
 ## Session brief template
 
 The walker constructs a per-task `scenario_brief` roughly like:
 
 ```
 You are driving <TASK-ID> Delivery via /cloverleaf-run inside a dedicated
-git worktree at <worktree_path>. The worktree is checked out to branch
+git worktree rooted at $WORKTREE_ROOT. The worktree is checked out to branch
 cloverleaf/<TASK-ID> (already created from main). Task risk_class: <class>.
 
+**Pre-flight: before any task steps, run `cd "$WORKTREE_ROOT"` to ensure your
+working directory is the worktree root, not whatever directory the session
+inherited.**
+
+**DO NOT run `git checkout main` from this worktree.** The `main` branch is
+held by the primary repo — attempting to check it out here will fail because
+the same branch cannot be checked out in two worktrees simultaneously. To
+compare your work against main, use `git diff main..HEAD` (safe diff) or
+`git show main:<path>` (safe file inspection). All state-advance commits must
+stay on the worktree's current branch (`cloverleaf/<TASK-ID>`).
+
 Plan: invoke `/cloverleaf-run <TASK-ID>`.
 
 **DO NOT invoke `/cloverleaf-merge`**. Fast lane stops after `/cloverleaf-review`