@mmerterden/multi-agent-pipeline 15.2.0 → 15.3.1

package/CHANGELOG.md

@@ -16,46 +16,36 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [15.3.1] - 2026-08-15
+
+### Changed
+
+- Documentation and wording clarifications.
+
+## [15.3.0] - 2026-08-15
+
+### Added
+
+- `/multi-agent:setup` gains an optional one-time operational-token onboarding
+  step (opt-in). The token is stored in the OS credential store only, never in a
+  file, prefs value, git, or synced tree.
+
 ## [15.2.0] - 2026-08-15
 
 ### Added
 
-- **`/multi-agent:update` auto-enables usage logging when a token is onboarded.**
-  The private dashboard stays opt-in and off by default, but once the shared
-  ingest token exists on a machine, an update flips `usageLog.enabled` on so the
-  admin's trusted group does not each have to toggle it by hand. It NEVER
-  fabricates or ships a secret: it activates only when a token resolves from
-  `MULTI_AGENT_USAGE_TOKEN`, `usageLog.token`, or the Keychain item named by the
-  new generic `keychainMapping.usage_ingest` slot - a machine that was never
-  given the token stays silent.
-- **`usage-report.mjs` reads the ingest token from the Keychain** (via
-  `credential-store.sh`, resolved through `keychainMapping.usage_ingest`) as a
-  fallback after env and `usageLog.token`, so the secret never has to live in a
-  synced or plaintext file for logging to work.
+- `/multi-agent:update` auto-configures the optional operational integration when
+  its token is already onboarded, resolving it from the credential store; it never
+  fabricates or ships a secret, so a machine without one is unaffected.
 
 ## [15.1.0] - 2026-08-14
 
-Opt-in run telemetry to a private dashboard, and a refactor band that mines it.
-
 ### Added
 
-- **Opt-in usage telemetry (`usageLog`).** When `prefs.global.usageLog.enabled`
-  is set with an ingest token, each run emits one activity event, keyed by task
-  id and refreshed live at every phase boundary via `phase-tracker.sh`, so one
-  record always shows the last phase a run reached — including runs that halt
-  before Phase 7. Wired at Phase 7 report and the halt path; detached and
-  best-effort, never blocking a run. The event carries activity metadata only
-  (who, command, mode, input type, repo, phase, outcome, halt cause, review
-  iterations, duration, token spend, cost, per-phase breakdown, OS, CLI, models,
-  stack, plugins, integrations, credential health, invoked skills, error tags,
-  version) — never prompts, code, diffs, token values or absolute paths. New
-  `pipeline/scripts/usage-report.mjs`; prefs schema + template gain the
-  `usageLog` block. Off by default; the emitter no-ops unless enabled and a
-  token resolves.
-- **`/multi-agent:refactor` Step 0d (band F).** Reads the local run-error ledger
-  (`errors-ledger.jsonl`, written by the telemetry emitter on terminal runs) and
-  ranks recurring failures as prioritized improvement areas — lived evidence,
-  offline, and without auth.
+- Optional, opt-in per-run operational reporting (`usageLog`), off by default and
+  a no-op unless configured.
+- `/multi-agent:refactor` Step 0d (band F) reads a local run-diagnostics ledger to
+  rank recurring failures as prioritized improvement areas - offline, no auth.
 
 ### Changed
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "15.2.0",
+  "version": "15.3.1",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

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

@@ -206,6 +206,39 @@ Save the resolved mapping to preferences:
 
 `null` = not mapped (missing or skipped). Pipeline phases read this mapping to retrieve tokens dynamically  -  never hardcoded key names.
 
+### Step 2.7  -  Operational reporting token (optional, opt-in)
+
+Only relevant when the team runs the optional operational reporting integration and the admin has issued this user a token. This is the ONE-TIME onboarding that configures it afterwards: once the token is in the credential store, `/multi-agent:update` auto-configures `usageLog`. Skipping it leaves the integration fully off.
+
+Ask (in `outputLanguage`), and proceed only on an explicit yes:
+
+```
+Do you have an operational-reporting token from your admin?
+[ Paste token / Skip ]
+```
+
+On paste, store the secret in the credential store ONLY - never in a file, prefs value, git, or any synced/published tree. Use the standard per-user key name so it is revocable independently and consistent across the user's machines:
+
+```bash
+~/.claude/lib/credential-store.sh set "${USER}_Usage_Ingest_Token" "<pasted-token>"
+```
+
+Then map it and enable logging (the token itself stays in the credential store; only the logical mapping + the on-switch land in prefs):
+
+```bash
+node -e '
+  const fs=require("fs"),os=require("os"),p=os.homedir()+"/.claude/multi-agent-preferences.json";
+  const j=JSON.parse(fs.readFileSync(p,"utf8"));
+  j.global=j.global||{}; j.global.keychainMapping=j.global.keychainMapping||{};
+  j.global.keychainMapping.usage_ingest=process.argv[1];
+  j.global.usageLog=Object.assign({enabled:true},j.global.usageLog||{},{enabled:true});
+  fs.writeFileSync(p,JSON.stringify(j,null,2)+"\n");
+' "${USER}_Usage_Ingest_Token"
+echo "  -> operational reporting configured (token in credential store)"
+```
+
+Security notes to surface to the user: the token is **write-only** (append-only to the endpoint - no read access, no other scope), stored **only in the OS credential store**, and **per-user** so the admin can revoke this one token without affecting anyone else. `usage-report.mjs` reads it from the credential store at runtime via the `usage_ingest` mapping; it is never written to a file or transmitted except over TLS to the ingest endpoint.
+
 ### Auto-learned fields (no setup step needed)
 
 **Jira Project Key**: auto-learned from pipeline usage. User runs `/multi-agent ABC-123` → `ABC` is extracted and saved to `prefs.global.defaultJiraKey` (first ever) and `prefs.projects[{project}].jiraProjectKeys` (per-project). Multiple keys accumulate over time  -  most recent first, deduped. Phase 0 Step 1 (Parse Input) handles extraction.

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

@@ -71,10 +71,10 @@ Update the pipeline in one command. Existing preferences are preserved; only ski
    fi
    ```
 
-5b. **Auto-enable usage logging when a token is already onboarded.** The private
-   usage dashboard is opt-in and off by default. This step flips it ON only when a
+5b. **Auto-configure operational reporting when a token is already onboarded.** The
+   integration is opt-in and off by default. This step turns it ON only when a
    token can be resolved - it NEVER fabricates a secret or ships one, so a machine
-   that was never given the token stays silent. Resolution order: env
+   that was never given the token stays inert. Resolution order: env
    `MULTI_AGENT_USAGE_TOKEN`, then `usageLog.token`, then the Keychain item named by
    `keychainMapping.usage_ingest`. Endpoint is left to the emitter's default.
    ```bash
@@ -90,9 +90,9 @@ Update the pipeline in one command. Existing preferences are preserved; only ski
        fi
        if [ -n "$TOK" ]; then
          node -e 'const fs=require("fs"),p=process.argv[1];const j=JSON.parse(fs.readFileSync(p,"utf8"));j.global=j.global||{};j.global.usageLog=j.global.usageLog||{};j.global.usageLog.enabled=true;fs.writeFileSync(p,JSON.stringify(j,null,2)+"\n");' "$PREFS"
-         echo "  -> usage logging activated (ingest token found)"
+         echo "  -> operational reporting configured (token found)"
        else
-         echo "  -> usage logging left off (no ingest token onboarded)"
+         echo "  -> operational reporting left off (no token onboarded)"
        fi
      fi
    fi

package/pipeline/multi-agent-refs/phases/operations.md

@@ -95,13 +95,13 @@ halt per the halt-visibility rule), `3` I/O error.
 Reads need no wrapper; the rename makes any read see either the old or the new
 document, never a truncated one.
 
-**Halt visibility (required, autopilot included).** A halt is never silent. Whenever a phase halts on a hard error (validator failed twice, no subagent returned, dispatch error past fallback, lock irrecoverable), in addition to the `agent-log.md` line: (a) write `state.status = "paused"` and `state.haltReason = "<phase>:<cause>"`; (b) record the cause on the tracker via `phase-tracker.sh meta <phase> halt "<cause>"` and `phase-tracker.sh update <phase> failed`; (c) emit one `>&2` alert line `HALT phase <N>: <cause>  -  resume with /multi-agent:resume #<id>`; (d) if `prefs.global.usageLog.enabled` is true, emit the end-of-run usage ping so a run that never reaches Phase 7 is still recorded with the phase it stopped at (`state.currentPhase` + `haltReason`) - the emitter no-ops when logging is off or unconfigured:
+**Halt visibility (required, autopilot included).** A halt is never silent. Whenever a phase halts on a hard error (validator failed twice, no subagent returned, dispatch error past fallback, lock irrecoverable), in addition to the `agent-log.md` line: (a) write `state.status = "paused"` and `state.haltReason = "<phase>:<cause>"`; (b) record the cause on the tracker via `phase-tracker.sh meta <phase> halt "<cause>"` and `phase-tracker.sh update <phase> failed`; (c) emit one `>&2` alert line `HALT phase <N>: <cause>  -  resume with /multi-agent:resume #<id>`; (d) if `prefs.global.usageLog.enabled` is true, emit the end-of-run report so a run that never reaches Phase 7 is still recorded with the phase it stopped at (`state.currentPhase` + `haltReason`) - the emitter no-ops when it is off or unconfigured:
 
 ```bash
 node $HOME/.claude/scripts/usage-report.mjs --state "$STATE_FILE" >/dev/null 2>&1 || true
 ```
 
-Autopilot suppresses *confirmations*, not *halts*  -  the user must always be able to see why an unattended run stopped without reading the log. The dashboard upserts by run id, so this halt event and a later Phase 7 event (after resume) collapse into one record.
+Autopilot suppresses *confirmations*, not *halts*  -  the user must always be able to see why an unattended run stopped without reading the log. The endpoint upserts by run id, so this halt record and a later Phase 7 record (after resume) collapse into one.
 
 ### Pipeline Best Practices
 

package/pipeline/multi-agent-refs/phases/phase-7-report.md

@@ -196,7 +196,7 @@ $HOME/.claude/scripts/log-metric.sh "$TASK_ID" 7 task.completed \
   duration_ms=$TOTAL_DURATION
 ```
 
-**Usage ping (optional, private dashboard).** When `prefs.global.usageLog.enabled` is true, emit one end-of-run activity event to the configured private dashboard. One POST per run (never per phase), fire-and-forget, activity metadata only  -  who, command, mode, input type, repo, phase reached, outcome, halt cause, review-iteration count, duration, token spend, cost, version. No prompts, code, diffs, or absolute paths. The script no-ops when `usageLog.enabled` is not true or no ingest token resolves, so the call is unconditional and never blocks the run.
+**Operational reporting (optional, opt-in).** When `prefs.global.usageLog.enabled` is true, emit one end-of-run run record to the configured endpoint. One POST per run, fire-and-forget, coarse run metadata only  -  no prompts, code, diffs, or absolute paths. The script no-ops when `usageLog.enabled` is not true or no token resolves, so the call is unconditional and never blocks the run.
 
 ```bash
 node $HOME/.claude/scripts/usage-report.mjs --state "$STATE_FILE" >/dev/null 2>&1 || true

package/pipeline/schemas/prefs.schema.json

@@ -193,7 +193,7 @@
                 "string",
                 "null"
               ],
-              "description": "Keychain item holding the shared ingest token for the private usage dashboard. When set, usage-report.mjs reads the token from here (never from a synced file), and /multi-agent:update auto-enables usageLog once the token is onboarded. Absent = usage logging stays off."
+              "description": "Keychain item holding the ingest token for the optional operational reporting integration. When set, usage-report.mjs reads it from here (never from a synced file), and /multi-agent:update auto-configures the integration once onboarded. Absent = the integration stays off."
             },
             "figma_pat": {
               "type": [
@@ -1087,7 +1087,7 @@
         "usageLog": {
           "type": "object",
           "additionalProperties": false,
-          "description": "Optional end-of-run usage ping to a private dashboard. When enabled, Phase 7 emits ONE activity event per run (never per phase) via pipeline/scripts/usage-report.mjs: who, command, mode, input type, repo, phase reached, outcome, halt cause, review-iteration count, duration, token spend, cost, version. Never prompts, code, diffs, or absolute paths. Off by default; the emitter no-ops unless enabled is true AND a token resolves (from token below or env MULTI_AGENT_USAGE_TOKEN), so it is inert for anyone who has not configured it.",
+          "description": "Optional, opt-in per-run operational reporting via pipeline/scripts/usage-report.mjs. Emits coarse run metadata only (never prompts, code, diffs, or absolute paths). Off by default; the emitter no-ops unless enabled is true AND a token resolves (from token below or env MULTI_AGENT_USAGE_TOKEN), so it is inert for anyone who has not configured it.",
           "properties": {
             "enabled": {
               "type": "boolean",
@@ -1096,7 +1096,7 @@
             },
             "endpoint": {
               "type": "string",
-              "description": "Ingest URL that receives the activity event. The token is sent in the X-Usage-Token header."
+              "description": "Ingest URL that receives the run record. The token is sent in the X-Usage-Token header."
             },
             "token": {
               "type": "string",

package/pipeline/scripts/usage-report.mjs

@@ -1,17 +1,10 @@
 /**
- * usage-report.mjs  -  usage ping (opt-in) for the private mission-control dashboard.
+ * usage-report.mjs  -  optional, opt-in per-run operational reporting.
  *
- * Emits one compact activity event keyed by run id (`taskId`). Called at each
- * phase boundary (status=running, via phase-tracker.sh) and once at the end
- * (terminal status, from Phase 7 report or the halt path). The server upserts
- * by run id, so per-phase calls update ONE record - it always reflects the last
- * phase a run reached, including runs that halt before Phase 7. Fire-and-forget,
- * never throws, never delays the run.
- *
- * Payload is activity metadata only  -  who, command, mode, input type, repo,
- * phase, outcome, halt cause, review iterations, duration, token spend, cost,
- * per-phase breakdown, language, stack, plugins, integrations, credential
- * health, invoked skills, error tags, version. No prompts, code, diffs, token
+ * Off by default; a no-op unless prefs.global.usageLog.enabled is true and a
+ * token resolves. Emits one compact run record keyed by run id (`taskId`),
+ * upserted per phase, fire-and-forget - never throws, never delays a run.
+ * Only coarse run metadata is included; never prompts, code, diffs, token
  * values, or absolute paths.
  *
  * Enable + configure via prefs.global.usageLog: