@cloverleaf/reference-impl 0.8.2 → 0.8.4

package/VERSION

@@ -1 +1 @@
-0.8.2
+0.8.4

package/dist/discovery-config.mjs

@@ -5,7 +5,15 @@ const here = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_DEFAULT = join(here, '..', 'config', 'discovery.json');
 export function loadDiscoveryConfig(repoRoot) {
     const override = join(repoRoot, '.cloverleaf', 'config', 'discovery.json');
-    const fallback = JSON.parse(readFileSync(PACKAGE_DEFAULT, 'utf-8'));
+    const rawFallback = JSON.parse(readFileSync(PACKAGE_DEFAULT, 'utf-8'));
+    const fallback = {
+        docContextUri: typeof rawFallback.docContextUri === 'string' ? rawFallback.docContextUri : '',
+        projectId: typeof rawFallback.projectId === 'string' ? rawFallback.projectId : '',
+        idStart: typeof rawFallback.idStart === 'number' ? rawFallback.idStart : 1,
+        prep_copy_dirs: Array.isArray(rawFallback.prep_copy_dirs)
+            ? rawFallback.prep_copy_dirs.filter((p) => typeof p === 'string')
+            : [],
+    };
     if (existsSync(override)) {
         try {
             const doc = JSON.parse(readFileSync(override, 'utf-8'));
@@ -22,5 +30,8 @@ function normalise(doc, fallback) {
         docContextUri: typeof doc.docContextUri === 'string' ? doc.docContextUri : fallback.docContextUri,
         projectId: typeof doc.projectId === 'string' ? doc.projectId : fallback.projectId,
         idStart: typeof doc.idStart === 'number' ? doc.idStart : fallback.idStart,
+        prep_copy_dirs: Array.isArray(doc.prep_copy_dirs)
+            ? doc.prep_copy_dirs.filter((p) => typeof p === 'string')
+            : fallback.prep_copy_dirs,
     };
 }

package/dist/prep-worktree.mjs

@@ -1,6 +1,7 @@
 import { cpSync, existsSync, rmSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 import { join, dirname } from 'node:path';
+import { loadDiscoveryConfig } from './discovery-config.mjs';
 /**
  * Prepare a freshly-created git worktree of the cloverleaf monorepo for running reference-impl
  * tests. Addresses the v0.5 dogfood finding (CLV-16, CLV-17 Delivery runs) where Reviewer/QA
@@ -116,6 +117,19 @@ export function prepWorktree(mainRoot, worktreePath) {
     primeCopy(mainStandardNm, wtStandardNm);
     primeCopy(mainRefImplNm, wtRefImplNm);
     primeCopy(join(resolvedMain, 'reference-impl', 'dist'), join(worktreePath, 'reference-impl', 'dist'));
+    // Honor discovery_config.prep_copy_dirs: copy each listed gitignored directory
+    // (e.g., docs/superpowers) from mainRoot into the worktree. Walker briefs reference
+    // these paths but git checkouts of main don't carry gitignored content.
+    const discoveryConfig = loadDiscoveryConfig(resolvedMain);
+    for (const dir of discoveryConfig.prep_copy_dirs) {
+        const srcPath = join(resolvedMain, dir);
+        const dstPath = join(worktreePath, dir);
+        if (!existsSync(srcPath)) {
+            process.stderr.write(`prep-worktree: prep_copy_dirs entry '${dir}' not found at ${srcPath} — skipping.\n`);
+            continue;
+        }
+        primeCopy(srcPath, dstPath);
+    }
     execSync('npm run build', {
         cwd: join(worktreePath, 'standard'),
         stdio: 'pipe',

package/dist/qa-report.mjs

@@ -1,5 +1,8 @@
 function escape(s) {
-    return s
+    if (s === undefined || s === null)
+        return '';
+    const str = typeof s === 'string' ? s : String(s);
+    return str
         .replace(/&/g, '&')
         .replace(/</g, '&lt;')
         .replace(/>/g, '&gt;')

package/lib/discovery-config.ts

@@ -9,11 +9,20 @@ export interface DiscoveryConfig {
   docContextUri: string;
   projectId: string;
   idStart: number;
+  prep_copy_dirs: string[];
 }
 
 export function loadDiscoveryConfig(repoRoot: string): DiscoveryConfig {
   const override = join(repoRoot, '.cloverleaf', 'config', 'discovery.json');
-  const fallback = JSON.parse(readFileSync(PACKAGE_DEFAULT, 'utf-8')) as DiscoveryConfig;
+  const rawFallback = JSON.parse(readFileSync(PACKAGE_DEFAULT, 'utf-8')) as Partial<DiscoveryConfig>;
+  const fallback: DiscoveryConfig = {
+    docContextUri: typeof rawFallback.docContextUri === 'string' ? rawFallback.docContextUri : '',
+    projectId: typeof rawFallback.projectId === 'string' ? rawFallback.projectId : '',
+    idStart: typeof rawFallback.idStart === 'number' ? rawFallback.idStart : 1,
+    prep_copy_dirs: Array.isArray(rawFallback.prep_copy_dirs)
+      ? (rawFallback.prep_copy_dirs as unknown[]).filter((p): p is string => typeof p === 'string')
+      : [],
+  };
 
   if (existsSync(override)) {
     try {
@@ -31,5 +40,8 @@ function normalise(doc: Partial<DiscoveryConfig>, fallback: DiscoveryConfig): Di
     docContextUri: typeof doc.docContextUri === 'string' ? doc.docContextUri : fallback.docContextUri,
     projectId:     typeof doc.projectId     === 'string' ? doc.projectId     : fallback.projectId,
     idStart:       typeof doc.idStart       === 'number' ? doc.idStart       : fallback.idStart,
+    prep_copy_dirs: Array.isArray(doc.prep_copy_dirs)
+      ? (doc.prep_copy_dirs as unknown[]).filter((p): p is string => typeof p === 'string')
+      : fallback.prep_copy_dirs,
   };
 }

package/lib/prep-worktree.ts

@@ -1,6 +1,7 @@
 import { cpSync, existsSync, rmSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 import { join, dirname } from 'node:path';
+import { loadDiscoveryConfig } from './discovery-config.js';
 
 /**
  * Prepare a freshly-created git worktree of the cloverleaf monorepo for running reference-impl
@@ -130,6 +131,20 @@ export function prepWorktree(mainRoot: string, worktreePath: string): void {
   primeCopy(mainRefImplNm, wtRefImplNm);
   primeCopy(join(resolvedMain, 'reference-impl', 'dist'), join(worktreePath, 'reference-impl', 'dist'));
 
+  // Honor discovery_config.prep_copy_dirs: copy each listed gitignored directory
+  // (e.g., docs/superpowers) from mainRoot into the worktree. Walker briefs reference
+  // these paths but git checkouts of main don't carry gitignored content.
+  const discoveryConfig = loadDiscoveryConfig(resolvedMain);
+  for (const dir of discoveryConfig.prep_copy_dirs) {
+    const srcPath = join(resolvedMain, dir);
+    const dstPath = join(worktreePath, dir);
+    if (!existsSync(srcPath)) {
+      process.stderr.write(`prep-worktree: prep_copy_dirs entry '${dir}' not found at ${srcPath} — skipping.\n`);
+      continue;
+    }
+    primeCopy(srcPath, dstPath);
+  }
+
   execSync('npm run build', {
     cwd: join(worktreePath, 'standard'),
     stdio: 'pipe',

package/lib/qa-report.ts

@@ -8,8 +8,10 @@ export interface QaRunResult {
   stderrTail: string;
 }
 
-function escape(s: string): string {
-  return s
+function escape(s: unknown): string {
+  if (s === undefined || s === null) return '';
+  const str = typeof s === 'string' ? s : String(s);
+  return str
     .replace(/&/g, '&')
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "Reference implementation of the Cloverleaf methodology as Claude Code skills. Implements the Tight Loop (Implementer + Reviewer).",
   "type": "module",
   "license": "MIT",

package/skills/cloverleaf-breakdown/SKILL.md

@@ -46,6 +46,8 @@ The user has invoked this skill with an RFC-ID (e.g., `CLV-009`).
 
    In the subagent context, also supply a hint that `next_id_base === $PLAN_ID`, so task IDs in `tasks[]` start at `PLAN_ID + 1`. The Plan agent allocates its own ID as `next_id_base` and task IDs sequentially after.
 
+   **Dispatch conventions:** invoke the Task tool in foreground mode (its default — do NOT pass `run_in_background: true`). The Task tool returns the subagent's final message as a string in the result. Do NOT use Bash `sleep` to poll an output file — the harness blocks foreground `sleep`, and background dispatch is unnecessary here because the foreground Task tool already blocks until the subagent finishes.
+
 7. Parse subagent response — expected JSON conforming to `plan.schema.json`. Required fields: `id, type: "plan", status: "drafting", owner, project, parent_rfc, task_dag (edge-based), tasks (inline Task docs, status=pending)`. 3-bounce budget per invocation.
 
 8. Ensure output `plan.id === $PLAN_ID`, `project === $PROJECT_ID`, `parent_rfc === { project: <rfc.project>, id: $RFC_ID }`. If the subagent drifted, override these before save.

package/skills/cloverleaf-document/SKILL.md

@@ -43,6 +43,8 @@ description: Run the Documenter agent on a task in the `implementing` state (ful
      - `{{base_branch}}` → `main`
      - `{{repo_root}}` → absolute path
 
+   **Dispatch conventions:** invoke the Task tool in foreground mode (its default — do NOT pass `run_in_background: true`). The Task tool returns the subagent's final message as a string in the result. Do NOT use Bash `sleep` to poll an output file — the harness blocks foreground `sleep`, and background dispatch is unnecessary here because the foreground Task tool already blocks until the subagent finishes.
+
 6. Parse the subagent's response. Expect JSON of the form `{"commits_added": N, "files_changed": [...], "summary": "..."}`.
 
 7. On failure to parse or response with invalid shape: report the response and stop without advancing state.

package/skills/cloverleaf-draft-rfc/SKILL.md

@@ -41,6 +41,8 @@ The user has invoked this skill with an RFC-ID (e.g., `CLV-009`).
      - `{{completed_spikes}}` → `COMPLETED_SPIKES` JSON array (or `[]`)
      - `{{spike}}` → (unused for draftRfc; substitute `null`)
 
+   **Dispatch conventions:** invoke the Task tool in foreground mode (its default — do NOT pass `run_in_background: true`). The Task tool returns the subagent's final message as a string in the result. Do NOT use Bash `sleep` to poll an output file — the harness blocks foreground `sleep`, and background dispatch is unnecessary here because the foreground Task tool already blocks until the subagent finishes.
+
 6. Parse subagent's response: expected JSON conforming to `rfc.schema.json`. Required fields: `id`, `type: "rfc"`, `status: "drafting"`, `owner`, `project`, `title`, `problem`, `solution`, `unknowns` (array of strings), `acceptance_criteria`, `out_of_scope`.
 
    If output fails schema validation: bounce. Budget: 3 bounces per invocation. On budget exhaustion: report and stop without advancing state.

package/skills/cloverleaf-implement/SKILL.md

@@ -32,6 +32,8 @@ The user has invoked this skill with a TASK-ID (e.g., `DEMO-001`).
      - `{{repo_root}}` → absolute path to the current repo
      - `{{base_branch}}` → `main` (or the current default branch)
 
+   **Dispatch conventions:** invoke the Task tool in foreground mode (its default — do NOT pass `run_in_background: true`). The Task tool returns the subagent's final message as a string in the result. Do NOT use Bash `sleep` to poll an output file — the harness blocks foreground `sleep`, and background dispatch is unnecessary here because the foreground Task tool already blocks until the subagent finishes.
+
 5. Parse the subagent's response. Expect JSON of the form `{"status": "done", "branch": "...", "files_changed": [...], "summary": "..."}` or `{"status": "blocked", "reason": "..."}`.
 
 6. On `blocked`: report the reason and stop. Do NOT advance status.

package/skills/cloverleaf-qa/SKILL.md

@@ -49,6 +49,8 @@ description: Run the QA agent on a task in the `qa` state (full pipeline only).
    - `model`: `sonnet`
    - Prompt: contents of `$(cloverleaf-cli plugin-root)/prompts/qa.md` with substitutions for `{{task}}`, `{{diff}}`, `{{branch}}`, `{{base_branch}}`, `{{repo_root}}`, `{{qa_rules}}` (the JSON loaded in step 5).
 
+   **Dispatch conventions:** invoke the Task tool in foreground mode (its default — do NOT pass `run_in_background: true`). The Task tool returns the subagent's final message as a string in the result. Do NOT use Bash `sleep` to poll an output file — the harness blocks foreground `sleep`, and background dispatch is unnecessary here because the foreground Task tool already blocks until the subagent finishes.
+
 8. Parse response: expect `{"verdict": "pass"|"bounce"|"escalate", "summary", "findings", "results"}`.
 
 9. Branch on verdict:

package/skills/cloverleaf-review/SKILL.md

@@ -42,6 +42,8 @@ description: Run the Reviewer agent on a task in the `review` state. Emits a fee
    - `model`: `sonnet`
    - Prompt: contents of `$(cloverleaf-cli plugin-root)/prompts/reviewer.md` with substitutions for `{{task}}`, `{{branch}}`, `{{base_branch}}`, `{{repo_root}}`, `{{diff}}`.
 
+   **Dispatch conventions:** invoke the Task tool in foreground mode (its default — do NOT pass `run_in_background: true`). The Task tool returns the subagent's final message as a string in the result. Do NOT use Bash `sleep` to poll an output file — the harness blocks foreground `sleep`, and background dispatch is unnecessary here because the foreground Task tool already blocks until the subagent finishes.
+
 6. Parse the subagent's response. Expect a feedback envelope JSON of the form `{"verdict": "pass"|"bounce", "summary": "...", "findings": [...]}`. Validate shape: verdict must be `pass` or `bounce`; if `bounce`, findings must have at least one entry with `severity` (one of `blocker|error|warning|info`) and `message`.
 
 7. Branch on verdict:

package/skills/cloverleaf-security-review/SKILL.md

@@ -28,6 +28,9 @@ description: Run the Security Reviewer agent on a task in the `security-review`
    - `subagent_type`: `general-purpose`
    - `model`: `sonnet`
    - Prompt: contents of `$(cloverleaf-cli plugin-root)/prompts/security-reviewer.md` with substitutions for `{{task}}`, `{{branch}}`, `{{base_branch}}`, `{{repo_root}}`, `{{diff}}`.
+
+   **Dispatch conventions:** invoke the Task tool in foreground mode (its default — do NOT pass `run_in_background: true`). The Task tool returns the subagent's final message as a string in the result. Do NOT use Bash `sleep` to poll an output file — the harness blocks foreground `sleep`, and background dispatch is unnecessary here because the foreground Task tool already blocks until the subagent finishes.
+
    Parse the subagent's feedback envelope (`verdict` + `findings[]`).
 
 6. **Merge + derive verdict.** Concatenate Pass A findings + Pass B findings into one `findings[]`. Derive the final verdict from the max severity across ALL findings:

package/skills/cloverleaf-spike/SKILL.md

@@ -38,6 +38,8 @@ The user has invoked this skill with a SPIKE-ID (e.g., `CLV-010`).
      - `{{brief}}` → `null` (unused for runSpike)
      - `{{prior_rfc}}`, `{{completed_spikes}}` → `null`
 
+   **Dispatch conventions:** invoke the Task tool in foreground mode (its default — do NOT pass `run_in_background: true`). The Task tool returns the subagent's final message as a string in the result. Do NOT use Bash `sleep` to poll an output file — the harness blocks foreground `sleep`, and background dispatch is unnecessary here because the foreground Task tool already blocks until the subagent finishes.
+
 6. Parse subagent response. Expected: the spike JSON with `status: "completed"`, `findings: string`, `recommendation: string`. Schema: `spike.schema.json` (validated by save-spike).
 
    If output fails schema validation: bounce. Budget: 3 bounces. On exhaustion: report and stop without advancing to completed.

package/skills/cloverleaf-ui-review/SKILL.md

@@ -72,6 +72,8 @@ description: Run the UI Reviewer agent on a task in the `ui-review` state (full
       - `{{affected_routes}}` → the value of `$AFFECTED` (verbatim — may be `"all"`, a JSON array, or `[]` but step 6 handled `[]` already)
       - `{{ui_review_config}}` → JSON-stringified result of `cloverleaf-cli ui-review-config <repo_root>` (used by the subagent to scope viewport sizes, thresholds, and axe rule overrides)
 
+    **Dispatch conventions:** invoke the Task tool in foreground mode (its default — do NOT pass `run_in_background: true`). The Task tool returns the subagent's final message as a string in the result. Do NOT use Bash `sleep` to poll an output file — the harness blocks foreground `sleep`, and background dispatch is unnecessary here because the foreground Task tool already blocks until the subagent finishes.
+
 11. Parse the subagent's response. Expect `{"verdict": "pass"|"bounce"|"escalate", "summary": "...", "findings": [...]}`.
 
 12. **Read the baseline-approval sidecar** (after the subagent completes, regardless of verdict):