@cloverleaf/reference-impl 0.8.1 → 0.8.3

package/VERSION

@@ -1 +1 @@
-0.8.1
+0.8.3

package/dist/cli.mjs

@@ -44,7 +44,7 @@
  */
 import { readFileSync, mkdirSync, copyFileSync, appendFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { execSync } from 'node:child_process';
+import { execSync, execFileSync } from 'node:child_process';
 import { loadTask, saveTask } from './task.mjs';
 import { advanceStatus } from './task.mjs';
 import { emitGateDecision } from './events.mjs';
@@ -66,7 +66,7 @@ import { buildBaselinePath } from './visual-diff.mjs';
 import { computeReadyTasks, detectCycle } from './dag-walker.mjs';
 import { readWalkState, writeWalkState, walkStatePath } from './walk-state.mjs';
 import { loadWalkerConfig } from './walker-config.mjs';
-import { classifyFiles } from './scope-check.mjs';
+import { classifyFiles, normalizePath } from './scope-check.mjs';
 import { computeRfcTasksView } from './rfc-tasks.mjs';
 import { loadSecretPatternsConfig, scanSecrets } from './secret-scan.mjs';
 import { classifyTaskSecurity } from './security-classify.mjs';
@@ -652,8 +652,29 @@ try {
             catch {
                 // No diff is fine (empty branch)
             }
-            // 4. Classify and output
-            const result = classifyFiles(taskDoc, modifiedFiles, siblingScopes);
+            // 4. Compute sharedFiles via git check-attr (merge=union honors user's multi-writer intent)
+            let sharedFiles = new Set();
+            if (modifiedFiles.length > 0) {
+                try {
+                    const out = execFileSync('git', ['-C', repoRoot, 'check-attr', '-z', 'merge', '--', ...modifiedFiles], { encoding: 'utf-8' });
+                    // -z output: NUL-separated triplets: path\0attr\0value\0
+                    const parts = out.split('\0');
+                    for (let i = 0; i + 2 < parts.length; i += 3) {
+                        const path = parts[i];
+                        const attr = parts[i + 1];
+                        const value = parts[i + 2];
+                        if (attr === 'merge' && value === 'union') {
+                            sharedFiles.add(normalizePath(path));
+                        }
+                    }
+                }
+                catch (err) {
+                    process.stderr.write(`cloverleaf-cli check-scope: git check-attr failed (${err instanceof Error ? err.message : String(err)}); proceeding with no shared-file annotations.\n`);
+                    sharedFiles = new Set();
+                }
+            }
+            // 5. Classify and output
+            const result = classifyFiles(taskDoc, modifiedFiles, siblingScopes, sharedFiles);
             process.stdout.write(JSON.stringify(result) + '\n');
             process.exit(0);
         }

package/dist/scope-check.mjs

@@ -37,7 +37,7 @@
  *  - Strip trailing `/` (preserving a non-empty result)
  *  - Return the resulting string (may be empty for degenerate inputs; caller filters)
  */
-function normalizePath(p) {
+export function normalizePath(p) {
     let s = p.trim().replace(/\\/g, '/');
     // Strip leading `./` repeatedly
     while (s.startsWith('./')) {
@@ -71,7 +71,7 @@ function normalizePaths(paths) {
  * @param siblingScopes - Other tasks in the same Plan with their declared files.
  * @returns             - { contested, own, extension } with arrays sorted by file path.
  */
-export function classifyFiles(taskDoc, modifiedFiles, siblingScopes) {
+export function classifyFiles(taskDoc, modifiedFiles, siblingScopes, sharedFiles) {
     // 1. Normalize own files from taskDoc.scope.files_touched
     const scope = taskDoc['scope'];
     const rawOwn = Array.isArray(scope?.['files_touched'])
@@ -117,6 +117,11 @@ export function classifyFiles(taskDoc, modifiedFiles, siblingScopes) {
         if (ownSet.has(f)) {
             own.push(f);
         }
+        else if (sharedFiles?.has(f)) {
+            // merge=union (or other shared-intent annotation): never contested.
+            // Falls into extension so post-merge auto-extend picks it up.
+            extension.push(f);
+        }
         else if (siblingMap.has(f)) {
             const owners = siblingMap.get(f);
             contested.push({ file: f, owner: owners[0] }); // lex-smallest wins

package/lib/cli.ts

@@ -45,7 +45,7 @@
 
 import { readFileSync, mkdirSync, copyFileSync, appendFileSync, existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { execSync } from 'node:child_process';
+import { execSync, execFileSync } from 'node:child_process';
 import { loadTask, saveTask } from './task.js';
 import { advanceStatus } from './task.js';
 import { emitGateDecision } from './events.js';
@@ -68,7 +68,7 @@ import { buildBaselinePath } from './visual-diff.js';
 import { computeReadyTasks, detectCycle } from './dag-walker.js';
 import { readWalkState, writeWalkState, walkStatePath } from './walk-state.js';
 import { loadWalkerConfig } from './walker-config.js';
-import { classifyFiles } from './scope-check.js';
+import { classifyFiles, normalizePath } from './scope-check.js';
 import type { SiblingScope } from './scope-check.js';
 import { computeRfcTasksView, type RfcTasksView } from './rfc-tasks.js';
 import { loadSecretPatternsConfig, scanSecrets } from './secret-scan.js';
@@ -663,8 +663,35 @@ try {
         // No diff is fine (empty branch)
       }
 
-      // 4. Classify and output
-      const result = classifyFiles(taskDoc, modifiedFiles, siblingScopes);
+      // 4. Compute sharedFiles via git check-attr (merge=union honors user's multi-writer intent)
+      let sharedFiles = new Set<string>();
+      if (modifiedFiles.length > 0) {
+        try {
+          const out = execFileSync(
+            'git',
+            ['-C', repoRoot, 'check-attr', '-z', 'merge', '--', ...modifiedFiles],
+            { encoding: 'utf-8' },
+          );
+          // -z output: NUL-separated triplets: path\0attr\0value\0
+          const parts = out.split('\0');
+          for (let i = 0; i + 2 < parts.length; i += 3) {
+            const path = parts[i];
+            const attr = parts[i + 1];
+            const value = parts[i + 2];
+            if (attr === 'merge' && value === 'union') {
+              sharedFiles.add(normalizePath(path));
+            }
+          }
+        } catch (err) {
+          process.stderr.write(
+            `cloverleaf-cli check-scope: git check-attr failed (${err instanceof Error ? err.message : String(err)}); proceeding with no shared-file annotations.\n`,
+          );
+          sharedFiles = new Set();
+        }
+      }
+
+      // 5. Classify and output
+      const result = classifyFiles(taskDoc, modifiedFiles, siblingScopes, sharedFiles);
       process.stdout.write(JSON.stringify(result) + '\n');
       process.exit(0);
     }

package/lib/scope-check.ts

@@ -56,7 +56,7 @@ export interface SiblingScope {
  *  - Strip trailing `/` (preserving a non-empty result)
  *  - Return the resulting string (may be empty for degenerate inputs; caller filters)
  */
-function normalizePath(p: string): string {
+export function normalizePath(p: string): string {
   let s = p.trim().replace(/\\/g, '/');
   // Strip leading `./` repeatedly
   while (s.startsWith('./')) {
@@ -93,7 +93,8 @@ function normalizePaths(paths: string[]): string[] {
 export function classifyFiles(
   taskDoc: TaskDoc,
   modifiedFiles: string[],
-  siblingScopes: SiblingScope[]
+  siblingScopes: SiblingScope[],
+  sharedFiles?: Set<string>
 ): ClassifyResult {
   // 1. Normalize own files from taskDoc.scope.files_touched
   const scope = taskDoc['scope'] as Record<string, unknown> | undefined;
@@ -138,6 +139,10 @@ export function classifyFiles(
   for (const f of filteredModified) {
     if (ownSet.has(f)) {
       own.push(f);
+    } else if (sharedFiles?.has(f)) {
+      // merge=union (or other shared-intent annotation): never contested.
+      // Falls into extension so post-merge auto-extend picks it up.
+      extension.push(f);
     } else if (siblingMap.has(f)) {
       const owners = siblingMap.get(f)!;
       contested.push({ file: f, owner: owners[0] }); // lex-smallest wins

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloverleaf/reference-impl",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "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):