@flumecode/runner 0.10.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flumecode/runner",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
   "description": "FlumeCode local runner — claims jobs and drives your local Claude Code against a real checkout.",
   "bin": {

package/skills-plugin/skills/implement-plan/SKILL.md

@@ -96,8 +96,9 @@ the next step.
    useful). For **each** AC it must return: the criterion text verbatim, a verdict
    (**met / not met / unclear**), a one-or-two-sentence rationale, and — this is the
    evidence the report needs — the **exact diff hunk(s)** that prove it, each tagged
-   with its file path (the minimal lines that matter, copied verbatim from
-   `git --no-pager diff`; not the whole file). A _met_ AC should cite at least one
+   with its file path (the hunks that prove it, copied verbatim from
+   `git --no-pager diff`, such that the union of every AC's evidence covers the
+   entire diff — each changed hunk cited under at least one criterion). A _met_ AC should cite at least one
    hunk; _not met_ / _unclear_ may cite none. **Ground every verdict in the actual
    diff:** a criterion may be marked _met_ only if `git --no-pager diff` really
    contains the change that satisfies it, and each cited hunk must be copied verbatim
@@ -105,7 +106,7 @@ the next step.
    implement subagent claimed. If `git --no-pager diff` is empty, the implementation
    produced no changes: no criterion may be _met_, and the review must say so. Tell it
    to return this as a clean, structured list so you can hand it straight to the
-   report step.
+   report step. In addition to per-AC verdicts, cross-check that every hunk in `git --no-pager diff` is cited by at least one AC's evidence; report any uncovered hunk as a coverage gap (signalling a missing AC or an out-of-scope change).
 
 5. **Code-quality review** — Task, `model: "opus"`, read-only. Give the subagent
    the coding guidelines (verbatim) and tell it to review the changes for
@@ -131,7 +132,7 @@ the next step.
    copied verbatim from that live diff — it must drop or correct any hunk carried
    over from step 4 that no longer appears in the actual diff, and the **Files
    changed** list must come from `git --no-pager diff --stat`, not from what an
-   earlier subagent claimed. **If `git --no-pager diff` is empty, the
+   earlier subagent claimed. Tell it to enumerate all hunks from `git --no-pager diff` and ensure each is attached to ≥1 AC's `evidence`; any hunk mapping to no plan AC goes under `## Caveats / follow-ups` as an explicit unattributed change. **If `git --no-pager diff` is empty, the
    implementation changed nothing:** the report must say so plainly — an honest
    `summary`, no AC marked `met` with evidence — and must never describe edits
    that aren't in the diff. Tell it to submit the user-facing report by calling
@@ -149,13 +150,13 @@ The report subagent calls `submit_report` with these fields:
 
 - **`summary`** — one or two sentences on what was implemented.
 - **`prose`** — markdown for the remaining sections, using `##` headings:
-  **What changed** (the plan steps, each mapped to the concrete changes that satisfy
-  it), **Code quality** (the quality-review outcome and anything left as
+  **Code quality** (the quality-review outcome and anything left as
   nice-to-have), **Files changed** (the list from the diff), **Build / tests** (lists
   each verification command and its final pass/fail result, or explains that no
   build/test setup was found), and **Caveats / follow-ups** (anything deferred,
-  unmet, or worth a human's eyes). Do **not** put the acceptance-criteria section in
-  `prose`, and do **not** include a PR link — the runner adds it.
+  unmet, or worth a human's eyes — including any diff hunks that map to no plan AC,
+  listed explicitly as unattributed changes). Do **not** put the acceptance-criteria
+  section in `prose`, and do **not** include a PR link — the runner adds it.
 - **`acceptanceCriteria`** — one entry per AC from the plan, in plan order, each:
   - `criterion` — the AC text verbatim.
   - `status` — `"met"` / `"not_met"` / `"unclear"`, mirroring the AC review.
@@ -177,3 +178,4 @@ The report subagent calls `submit_report` with these fields:
   once — not as prose for you to echo. Each acceptance criterion carries the diff
   hunk(s) that prove its verdict, copied verbatim from the live `git --no-pager diff`
   — never fabricated. An empty diff means an honest "nothing changed" report.
+- The report exists so the human reviewer can verify each acceptance criterion is satisfied — the ACs and their diff evidence are the primary review surface.

package/skills-plugin/skills/lint-plugin-generator/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: lint-plugin-generator
+description: >-
+  Generate a concrete plan to install the FlumeCode Lint plugin for THIS repo —
+  a .flumecode/plugins/lint/ manifest wired to the pre-commit socket that runs
+  the repo's lint/format checks and reports a heartbeat.
+---
+
+# lint-plugin-generator
+
+You generate a concrete, repo-specific plan to install the FlumeCode Lint
+plugin. You work **read-only**: inspect the repo and produce a plan via
+`submit_plan`; never edit files.
+
+## Orient yourself first
+
+Before producing the plan, inspect:
+
+1. `.flumecode/wiki/README.md` and `components/skills-plugin.md` (if present) for context.
+2. `package.json` `scripts` — look for `lint`, `format`, `format:check`, `typecheck`, `test`.
+3. `.lintstagedrc.json` / `.lintstagedrc.js` — staged-file formatters.
+4. `.husky/pre-commit` — the exact commands the pre-commit hook already runs.
+5. ESLint config (`eslint.config.*`, `.eslintrc.*`) and Prettier config (`.prettierrc.*`) to confirm tools are present.
+
+From this, determine the **exact shell commands** the run script should execute
+(e.g. `pnpm exec lint-staged && pnpm lint && pnpm typecheck`). Do not
+hard-code — derive from the repo.
+
+## Produce the plan
+
+Call `submit_plan` **once**, passing a `plans` array with one entry whose steps
+instruct the implementer to create:
+
+### Artifact 1 — `.flumecode/plugins/lint/plugin.json`
+
+```json
+{
+  "key": "lint",
+  "socket": "pre-commit",
+  "run": "node .flumecode/plugins/lint/run.mjs",
+  "heartbeat": {
+    "url": "https://<flumecode-base-url>/api/runner/plugins/heartbeat",
+    "token": "<repo-scoped-token>"
+  }
+}
+```
+
+`url` and `token` are placeholders — note in the plan that the user must fill
+them in via the FlumeCode web UI after installation. The plan must **not**
+commit a real token value.
+
+### Artifact 2 — `.flumecode/plugins/lint/run.mjs`
+
+A Node.js ES module that:
+
+1. Reads `plugin.json` from the same directory to get `heartbeat.url` and `heartbeat.token`.
+2. Determines the current git branch (`git rev-parse --abbrev-ref HEAD`).
+3. Runs each detected lint/format/typecheck command with `child_process.execSync` (stdio: `inherit`).
+4. On success, POSTs to the heartbeat URL:
+   `{ repoId: process.env.FLUMECODE_REPO_ID, pluginKey: "lint", branch, status: "pass", timestamp: new Date().toISOString() }`
+   (`FLUMECODE_REPO_ID` — the runner will inject this in Plan 2; if not yet available, the heartbeat may omit repoId or read it from .flumecode/config.json)
+5. On any command failure, exits non-zero (and optionally POSTs `status: "fail"`).
+
+The `repoId` comes from the `FLUMECODE_REPO_ID` environment variable that the
+runner sets. The heartbeat request uses `Authorization: Bearer <token>`.
+
+### Manifest shape
+
+The manifest `plugin.json` must have exactly these fields:
+
+```
+{ key, socket, run, heartbeat: { url, token } }
+```
+
+This is the shape the FlumeCode plugin loader expects.
+
+### Heartbeat endpoint
+
+`POST /api/runner/plugins/heartbeat` with JSON body:
+`{ repoId, pluginKey, branch, status, timestamp }`
+(this endpoint does not exist yet — it will be created by Plan 2; include this as a step in the generated plan or as a prerequisite note)
+
+### Acceptance criteria the plan must include
+
+- `.flumecode/plugins/lint/plugin.json` exists with `key: "lint"`, `socket: "pre-commit"`, `run: "node .flumecode/plugins/lint/run.mjs"`.
+- `.flumecode/plugins/lint/run.mjs` runs the repo's detected lint/format/typecheck commands and exits non-zero on any failure.
+- A successful run POSTs a heartbeat with `{ repoId, pluginKey: "lint", branch, status: "pass", timestamp }`.
+
+## Always
+
+- Stay read-only. Produce the plan via `submit_plan`; never edit files.
+- The plan must be specific enough for an `implement-plan` run to execute
+  without re-deriving the commands — include the actual detected commands in
+  the step descriptions and pseudo code.
+- Leave `heartbeat.url` and `heartbeat.token` as placeholders — document that
+  the user fills them in via the FlumeCode web UI after installation.

package/skills-plugin/skills/request-to-plan/SKILL.md

@@ -71,11 +71,19 @@ Field-by-field guidance:
   - **`description`** — what changes and why: the concrete change being made and the rationale for it. Use concrete file references (`path/to/file.ts`) and name the functions/symbols involved.
   - **`pseudoCode`** — an array of `{ file, pseudoCode }` entries. Provide an entry for every file the step touches **except** documentation files (SKILL.md, README.md, wiki pages, etc.). `pseudoCode` is optional in the schema but expected for all non-documentation files. Each entry names the file path and contains pseudo code that precisely describes the changes to make in that file.
 - **`acceptanceCriteria`** — **required; at least 2 items.** Each criterion must
-  be an observable condition you could check after the work is done: a behavior,
-  a test result, or a verifiable state. Together they must fully define "done" —
-  satisfying all of them resolves the request, no more and no less. Do **not**
-  restate a step as a criterion ("the function is updated" is a step; "calling
-  the function with X returns Y" is a criterion).
+  be a concrete, deterministically-checkable condition that a third party can verify
+  without knowing the author's intent. Write each as a trigger/precondition and the
+  exact observable result: `run X → output Y`, `file Z contains W`, `calling f(a) returns b`.
+  No vague adjectives (`robust`, `clean`, `properly`, `works correctly`). The set
+  must be **collectively exhaustive** — every step's intended change is covered by
+  at least one AC. Do **not** restate a step as a criterion.
+
+  **Good vs bad examples:**
+  - ✅ `grep -rn "What changed" apps/runner/src/report.ts` produces no matches.
+  - ❌ The report is cleaner and no longer mentions 'What changed'. _(vague, not checkable)_
+  - ✅ `pnpm test` in the repo root exits 0 and report.test.ts output contains no failures.
+  - ❌ Tests pass correctly. _(no trigger, no observable result)_
+
 - **`risks`** — anything that could change the approach or surface a problem.
 - **`outOfScope`** — what you are deliberately not doing.
 

package/skills-plugin/skills/resolve-merge-conflict/SKILL.md

@@ -25,11 +25,34 @@ branch was building, which is exactly the intent you must preserve when you choo
 to integrate each conflict. Check the FlumeCode wiki (`.flumecode/wiki/README.md`) if
 one exists to understand the conflicting code.
 
+If the prompt includes a **'Related sessions behind the incoming changes'** section, read it carefully — it carries the accepted plan and final implementation report of the other coding sessions whose work landed on the merge branch and is now conflicting with yours. Use those plans and reports to understand what _they_ were building so you can resolve each conflict in a way that preserves both sessions' intent, not just this one's.
+
+## Why conflicts are routine here (and how to avoid making them worse)
+
+Every coding session is frozen to one commit, but several sessions often run against
+the same base at once. When a sibling session merges first, this branch's base
+(usually `main`) moves and the overlap surfaces as a conflict — so conflicts are a
+normal, expected event, not a sign anything went wrong. **Rebasing onto the base does
+not make a genuine conflict disappear** — it just replays this branch's commits onto
+the new base, and the same overlapping lines collide there too. Integration is
+unavoidable; your job is to do it well, preserving both intents.
+
 ## Step 1 — Find every conflict
 
 - `git status` shows the unmerged paths; `git diff --diff-filter=U` shows the
   conflicting hunks. Work through **all** of them — a single leftover marker fails the
   run.
+- **Generated/derived files: regenerate, don't hand-merge.** Some conflicted files are
+  not authored directly — they're produced from a source of truth by a tool (DB
+  migrations + their journal/snapshot from a schema, lockfiles from a manifest, bundled
+  or compiled output, sequentially-numbered files, generated API clients/types). For
+  these, **removing the markers is not enough**: a hand-merge can be marker-free yet
+  inconsistent, which breaks the build in a way the conflict markers never warned about.
+  Resolve the **source** first (e.g. the schema or manifest), then **re-run the
+  generator** to rebuild the derived files from scratch rather than stitching both
+  sides together by hand. Check the repo's wiki (`.flumecode/wiki/`) for the exact
+  regeneration command and any conventions — and if a regeneration step exists, prefer
+  it over editing the generated file directly.
 
 ## Step 2 — Resolve each conflict correctly
 
@@ -53,13 +76,18 @@ coding guidelines verbatim) — subagents start blank.
 
 Run the project's build and tests to confirm the resolved tree is correct (the
 runner's commit will also run the repo's pre-commit hook, so failing checks would
-block the merge anyway). Fix anything the merge broke.
+block the merge anyway). Fix anything the merge broke. The runner then checks every
+file that was conflicted for leftover markers (`<<<<<<<`, `=======`, `>>>>>>>`) and
+**fails the run** if any remain — so make sure each conflicted file reads as clean code
+before you finish. (You don't need to `git add`; the runner stages and commits for you.)
 
 ## Never
 
-- Never `git add`, `git commit`, `git merge --continue`, `git push`, or open a PR —
-  the runner stages the resolved tree, finalizes the merge commit, and updates the
-  **existing** pull request. A new PR must never be created.
+- Never `git commit`, `git merge --continue`, `git push`, or open a PR — the runner
+  stages the resolved tree, finalizes the merge commit, and updates the **existing**
+  pull request. A new PR must never be created. (Leaving the files unstaged is fine —
+  the runner detects whether you're done by scanning file content for markers, not by
+  the index, so don't try to `git merge --continue` to "complete" the merge yourself.)
 - Never leave a conflict marker behind, and never resolve a conflict by discarding one
   side's intent.