@mmerterden/multi-agent-pipeline 20.12.0 → 20.15.0

package/pipeline/commands/multi-agent/refactor/SKILL.md

@@ -72,46 +72,12 @@ Roll the high-impact + low/med-effort survivors into the Step 4 plan as band-A i
 
 Some skills/components in this project (or in the marketplace plugins it ships) were derived from an upstream source. Upstream keeps evolving  -  it fixes bugs and adds features. This step detects upstream drift so we can decide whether to pull the improvements back.
 
-The upstream mapping is **configuration, never hardcoded** (it can reference private sources, so it stays out of the shipped skill). Read it from `~/.claude/multi-agent-preferences.json` at `global.derivedSkillSources` (an array). Each entry:
-
-```jsonc
-{
-  "label": "<human name for this derivation>",
-  "localPath": "<repo-relative dir where our derived copy lives>",
-  "upstreamMarketplace": "<installed marketplace name>",   // resolved under ~/.claude/plugins/cache/<marketplace>/
-  "upstreamPlugin": "<plugin name>",
-  "upstreamSkills": ["<skill-a>", "<skill-b>"],            // the upstream skills we took
-  "derivedFromVersion": "<x.y.z>",                         // the version we last synced from
-  "upstreamVersionSource": "marketplace.json",             // which manifest is authoritative; default marketplace.json
-  "upstreamLocalClone": "<optional path>",                 // working copy of the upstream repo, preferred over the cache
-  "upstreamRepoUrl": "<optional https url>"                // used when neither a clone nor the marketplace is available
-}
-```
-
-**The plugin cache is a mirror, not the authority.** `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/` only holds whatever the last `claude plugin marketplace update` fetched. Reading it as the current upstream version is how this step reported "up to date" while the derivation was four releases behind: the cache sat at 0.2.1 and upstream was at 0.4.1. Resolve in the order below and never let the cache alone produce an "up to date" verdict.
-
-**Which manifest carries the version** is `upstreamVersionSource`, default `marketplace.json`. That is what a marketplace consumer actually resolves, and some upstreams keep per-plugin `plugin.json` versions deliberately unused - reading those records a version nobody ships. An entry here was recorded at 0.7.0 from `plugin.json` while the upstream marketplace said 0.6.0 and its CHANGELOG stated in as many words that `plugin.json` is not used.
-
-Procedure:
-1. If `global.derivedSkillSources` is missing or empty -> **skip** this step and report "no derived-skill sources configured" (nothing to check). Never invent a source.
-2. For each entry, resolve the current upstream version, in this order, stopping at the first that answers:
-   - **`upstreamLocalClone`** if set: read `<clone>/.claude-plugin/<upstreamVersionSource>`. Also run `git -C <clone> fetch --dry-run` (or compare against `@{u}`) and say so when the clone is itself behind, so a stale working copy is not silently trusted either.
-   - **`upstreamRepoUrl`**: read the same manifest over the API (`gh api` / `WebFetch`). A private upstream can 404 for the currently active account even when the repo exists - that is an unreachable result, not a "no drift" result.
-   - **Plugin cache** under `~/.claude/plugins/cache/<upstreamMarketplace>/<upstreamPlugin>/*/`: last resort only. When the cache is the only source that answered, report the entry as **`unverified (cache only)`**, never as "up to date", and add a plan item to configure `upstreamLocalClone`.
-   - If nothing is reachable, record the entry as "upstream unreachable" and move on (do not fail the whole run).
-3. Compare the resolved upstream version to `derivedFromVersion`:
-   - equal, from an authoritative source -> "up to date" (no drift)
-   - equal, from the cache only -> "unverified (cache only)"
-   - newer -> **drift**: read the CHANGELOG entries between the two versions, and diff each `upstreamSkills` SKILL.md (+ any templates) against our `localPath` copy. Summarize what changed upstream (bug fixes, new sections, new templates, renamed inputs). Ignore changelog entries that only touch skills outside `upstreamSkills` - they are not ours to port.
-4. Emit the drift table (plan band D):
-
-```
-| Derivation | Our copy (localPath) | Derived-from | Upstream now | Drift | What changed upstream |
-|------------|----------------------|--------------|--------------|-------|-----------------------|
-| <label>    | <path>               | 0.2.1        | 0.3.0        | YES   | <changelog + diff summary> |
-```
+Rules that hold for every entry:
+- The upstream mapping is **configuration, never hardcoded**: `global.derivedSkillSources` in `~/.claude/multi-agent-preferences.json`. Missing or empty -> **skip** and report "no derived-skill sources configured". Never invent a source.
+- **The plugin cache is a mirror, not the authority.** Never let the cache alone produce an "up to date" verdict; report it as **`unverified (cache only)`**. An unreachable upstream is recorded as "upstream unreachable" and the run continues.
+- Each drifted entry becomes a band-D plan item. Do not auto-apply upstream changes  -  they go through Step 5 approval like everything else, and after porting, bump the entry's `derivedFromVersion`.
 
-5. For each drifted entry, add a band-D plan item: "port upstream <plugin> <version> changes into <localPath>", with the specific skills to update. Do not auto-apply upstream changes  -  they go through Step 5 approval like everything else, and after porting, bump the entry's `derivedFromVersion`.
+Full procedure: `$HOME/.claude/multi-agent-refs/refactor/drift.md`. Read it when `global.derivedSkillSources` has at least one entry (entry schema, source resolution order, version manifest, comparison, band-D table).
 
 ## Step 0c: DEV-TOOLKIT  -  current MCP practice for the companion toolkit
 
@@ -121,44 +87,9 @@ Full procedure  -  resolution (configuration first, never a hardcoded path; skip
 
 ## Step 0d: RUN-ERRORS  -  what the pipeline actually failed on
 
-Before speculating about improvements, read what real runs already failed on. When usage logging is enabled, every terminated run appends its errors to a local ledger:
-
-```bash
-LEDGER="$HOME/.claude/logs/multi-agent/errors-ledger.jsonl"
-[ -f "$LEDGER" ] || echo "no run-error ledger yet - skip band F"
-```
-
-Each line is one run: `{ t, id, u, c, rp, ph, v, errs[] }`. The `errs[]` entries are cause tags (`<phase>:<cause>` halt reasons, `phase-<id>-failed`, `run-failed`).
-
-1. Read the ledger (best-effort; a missing or unreadable file means skip band F, not a failure).
-2. Group by error tag. For each tag compute: occurrences, distinct users affected, distinct repos, the phase it usually strikes, first + last seen, and which pipeline versions it spans (a tag that persists across versions is unfixed; one that stopped at a version is already resolved  -  do not re-raise it).
-3. Rank by `occurrences x users-affected`. A failure that recurs across users or tasks is lived evidence, not a hypothesis  -  it outranks a speculative improvement.
-4. For each surviving tag, trace it to the phase doc / script that emits that cause and propose the concrete fix.
-
-This band mirrors the admin dashboard's "Gelişim alanları" panel, but reads the local ledger so it needs no auth and works offline. If `$ARGUMENTS` names a focus area, still read the ledger  -  a recurring run error in that area is the strongest possible signal.
-
-Then read what the transcripts themselves record, which is the half no model noticed:
-
-```bash
-node "$HOME/.claude/scripts/learn-from-transcripts.mjs" --json
-```
-
-It correlates rather than interprets  -  a failed read against the read that then worked, an identical invocation that kept failing, a search that was too narrow, a call the user refused twice, a file too big to read whole. Dry run by default; `--apply` writes them to the learnings ledger as `source: transcript-mining` and renders a marked block in `CLAUDE.local.md`. Zero candidates alongside a non-zero `toolResultsExamined` means there was nothing to find; zero of both means the read is broken.
-
-Output (plan band F):
-
-```
-| # | Error tag | Occurrences | Users | Usual phase | Versions | Root cause (file) | Fix | In plan? |
-|---|-----------|-------------|-------|-------------|----------|-------------------|-----|----------|
-| 1 | 4:reviewer-json-invalid | 12 | 3 | 4 | 14.x-15.x | reviewer prompt lets prose leak | tighten schema instruction in phase-3-review.md | Yes (P0) |
-| 2 | phase-3-failed | 5 | 2 | 3 | 15.0.x | build step misses a stack toolchain | add preflight in phase-2-dev.md | Yes (P1) |
-```
-
-Rules for this band:
+Before speculating about improvements, read what real runs already failed on. When usage logging is enabled, every terminated run appends its errors to a local ledger at `$HOME/.claude/logs/multi-agent/errors-ledger.jsonl`. A missing, unreadable or empty ledger means skip band F silently  -  it is additive signal, never a gate. If `$ARGUMENTS` names a focus area, still read the ledger  -  a recurring run error in that area is the strongest possible signal. A tag that stopped recurring after a version bump is resolved: report it, do not re-raise it. Never quote a user's identity as blame.
 
-- The ledger is evidence of the past, not a spec. A tag that stopped recurring after a version bump is resolved  -  report it as resolved, do not add a plan item.
-- Never quote a user's identity as blame. The `u` field is for counting distinct affected users, not for naming anyone in the plan.
-- If the ledger is empty or absent, skip band F silently  -  it is additive signal, never a gate.
+Full procedure: `$HOME/.claude/multi-agent-refs/refactor/run-errors.md`. Read it when the ledger exists (record shape, grouping and ranking, transcript mining, band-F table).
 
 ## Step 0e: BACKLOG  -  friction this pipeline already noticed
 

package/pipeline/commands/multi-agent/review/SKILL.md

@@ -26,6 +26,11 @@ Skip Phase 0-3 and review a diff only. Five input shapes, two providers:
 
 Branch-mode runs print to chat only. PR-mode runs print to chat AND post the verdict to the PR per `$HOME/.claude/multi-agent-refs/channels/pr-review-actions.md`: per-finding inline comments + an explicit approve / needs-work state. **No monolithic advisory comment** is ever posted.
 
+## Gotchas
+
+- The counterpart-repo comparison needs exactly one resolved candidate. With several, an unattended run skips it silently, so an autopilot review can have no cross-platform section.
+- The counterpart's stack comes from marker files, never from the repo name.
+
 ## Steps
 
 ### 0. Session bootstrap  -  TASK_ID + tmp cleanup

package/pipeline/commands/multi-agent/review-analysis/SKILL.md

@@ -1,6 +1,6 @@
 ---
-description: "Review a written analysis document instead of a diff: resolve it from a path, a Confluence page or a Jira issue, run the deterministic gates first, then a parallel model review. Findings cite the Locked rule they break. Never edits the document."
-description-tr: "Diff yerine yazılmış analiz dokümanını review eder: yol, Confluence sayfası veya Jira issue'sundan getirir, önce deterministik geçitleri koşar, sonra paralel model review. Bulgular ihlal edilen Locked kuralını gösterir. Dokümanı düzenlemez."
+description: "Review a written analysis document instead of a diff: resolve it from a path, a Confluence page or a Jira issue, run the deterministic gates first, then a parallel model review. Findings cite the Locked rule they break. Never edits the document. Use when an analysis needs judging before development starts."
+description-tr: "Diff yerine yazılmış analiz dokümanını review eder: yol, Confluence sayfası veya Jira issue'sundan getirir, önce deterministik geçitleri koşar, sonra paralel model review. Bulgular ihlal edilen Locked kuralını gösterir. Dokümanı düzenlemez. Bir analizin geliştirme başlamadan önce değerlendirilmesi gerektiğinde kullanılır."
 argument-hint: "[path | Confluence URL | pageId | JIRA-KEY] [--state <state.json>]  -  optional; with no argument, pick from recent analyses"
 parameters: [{"name":"target","kind":"text"},{"name":"--state","kind":"path"}]
 gui: form
@@ -14,6 +14,11 @@ confirm: none
 
 `/multi-agent:review` judges a diff. This judges the document that diff was supposed to come from, before anyone writes the code it describes. No worktree, no branch, no commit, and the reviewed document is never edited in place.
 
+## Gotchas
+
+- Validator ERRORs are Blockers and WARNs are Important, unless the document states why the warned-about item is acceptable.
+- Every rubric class is printed, with `none` when empty. A class missing from the verdict did not run; it is not a clean result.
+
 ## Flow
 
 Read `$HOME/.claude/multi-agent-refs/analysis/review.md` and execute it:
@@ -27,7 +32,7 @@ Read `$HOME/.claude/multi-agent-refs/analysis/review.md` and execute it:
 
 ## Why it cites Locked decisions
 
-The analysis flow already declares 36 Locked decisions and two deterministic validators. A reviewer that says "I would have written this differently" gives the author nothing to act on; one that says "Locked 33: the Confluence page is in the evidence record but not in Section 21" gives them a fix and a reason. Findings that map to no rule are still allowed, but they are marked as judgement, not dressed up as a violation.
+The analysis flow already declares 37 Locked decisions and two deterministic validators. A reviewer that says "I would have written this differently" gives the author nothing to act on; one that says "Locked 33: the Confluence page is in the evidence record but not in Section 21" gives them a fix and a reason. Findings that map to no rule are still allowed, but they are marked as judgement, not dressed up as a violation.
 
 ## What it never does
 

package/pipeline/commands/multi-agent/scenario-audit/SKILL.md

@@ -0,0 +1,79 @@
+---
+description: "Audit test scenarios from a CSV against the code: mark each PRESENT, PARTIAL, ABSENT or UNCLEAR, every PRESENT backed by a file:line that resolves at HEAD. Read-only. Use when a test set or acceptance list has to be checked against what the code does."
+description-tr: "Test senaryolarını koda karşı denetler: CSV'deki (ya da CSV'ye aktarılmış Jira test setindeki) her senaryo için kodun onu nerede karşıladığını bulur ve VAR, KISMEN, YOK ya da BELİRSİZ olarak işaretler; her VAR, HEAD'de çözülen bir dosya:satır ile desteklenir. Salt-okunur."
+allowed-tools: Bash, Read, Grep, AskUserQuestion
+argument-hint: "<scenarios.csv> [--repo <path>]"
+parameters: [{"name":"scenarios","kind":"path","required":true},{"name":"--repo","kind":"path"}]
+gui: form
+destructive: false
+confirm: none
+not-for: test, manual-test, review
+---
+
+# multi-agent scenario-audit
+
+**Input**: $ARGUMENTS
+
+Checks a list of test scenarios against a repository and says, per scenario,
+whether the code implements it. The judgement is yours; the evidence rule is
+the script's. Nothing is written and nothing leaves the machine.
+
+Script: `$HOME/.claude/scripts/scenario-audit.mjs`.
+
+## Gotchas
+
+- A verdict without a resolving `file:line` is not PRESENT. `verify` turns it into UNCLEAR and says why; do not argue with it, find the line.
+- ABSENT is a claim about a search. Record the terms you searched; an ABSENT with no terms becomes UNCLEAR.
+- Scenario text is usually business language and the code is not. Search for identifiers, localization keys, endpoint paths and error codes, not for the scenario's words.
+- The audit reads HEAD. Uncommitted work is not seen; say so when the working tree is dirty.
+
+## Step 1 - Inventory
+
+The scenarios file is a CSV with an id column and a title column (`id`/`no`/`key`,
+`title`/`scenario`/`senaryo`/`başlık`; optional `steps`/`adımlar` and
+`expected`/`beklenen`). Comma or semicolon. A Jira test set is exported to this
+shape first.
+
+```bash
+node "$HOME/.claude/scripts/scenario-audit.mjs" inventory --csv "<scenarios.csv>" > /tmp/ma-scenarios.json
+```
+
+Exit 2 names the missing column. With no `--repo`, the repository is the
+current directory; confirm it in one line before searching.
+
+## Step 2 - Search
+
+For each scenario, write the code-level terms that would implement it into
+`/tmp/ma-terms.json` (`{"<id>": ["term", ...]}`), then:
+
+```bash
+node "$HOME/.claude/scripts/scenario-audit.mjs" search --terms /tmp/ma-terms.json --repo "<repo>"
+```
+
+Read the candidate lines it returns. A term nothing matched is listed under
+`missing`; try a second term before concluding anything.
+
+## Step 3 - Verdict
+
+Write `/tmp/ma-verdicts.json`: `[{id, status, citations, searched, note}]`.
+
+| Status | When | Needs |
+|---|---|---|
+| `PRESENT` | the code does what the scenario expects | `citations`: the `file:line` that does it |
+| `PARTIAL` | part of it, e.g. the happy path without the error case | `citations`, and `note` saying what is missing |
+| `ABSENT` | nothing implements it | `searched`: the terms that found nothing relevant |
+| `UNCLEAR` | the code exists but its behaviour cannot be told from reading | `note` |
+
+```bash
+node "$HOME/.claude/scripts/scenario-audit.mjs" verify --csv "<scenarios.csv>" \
+  --verdicts /tmp/ma-verdicts.json --repo "<repo>" --lang "<outputLanguage>"
+```
+
+## Step 4 - Report
+
+Print the table `verify` produced, verbatim, and its count line. Then the
+scenarios that moved to UNCLEAR during verification, with the reason. State
+which verdicts rest on a resolved citation (mechanical) and that the reading of
+the code behind them is judgement.
+
+**Stop. No issue, no comment, no worktree.**

package/pipeline/commands/multi-agent/serve/SKILL.md

@@ -56,7 +56,10 @@ Or leave it: it exits on its own when idle.
 ## What it will not do
 
 There is no route that merges, marks ready, runs a command or starts a host.
-`POST /v1/launch` validates a launch request, writes it (0600) and returns the
-argv and environment `launch.json` declares; the client starts the process.
+`POST /v1/launch` and `POST /v1/runs/{id}/resume` return the argv and
+environment `launch.json` declares; the client starts the process.
 `POST /v1/runs/{id}/answer` accepts only an option the run's pending question
-offered.
+offered. `POST /v1/runs/{id}/kill` and `POST /v1/gc` act only on a second
+request carrying the single-use confirm token the first one returned, and a
+kill never deletes the remote branch or the logs. Autopilot can be turned off
+over HTTP, never on.