@mmerterden/multi-agent-pipeline 16.25.0 → 16.27.0

package/pipeline/scripts/learnings-ledger.mjs

@@ -30,6 +30,11 @@
  *                 knowledge in a deterministic order, so it can sit in the cacheable
  *                 stable prefix of a phase prompt (see multi-agent-refs/prompt-assembly.md).
  *                 Every line carries a [L:id] pointer for drill-down. Exit 2 when empty.
+ *   timeline   --anchor <id> [--before N] [--after N] [--repo-slug <slug>]
+ *                 What was learned around an entry. brief/profile rank by
+ *                 relevance ("what applies here"); this answers "what else did
+ *                 we learn at the same time". Append-only, so line adjacency is
+ *                 chronological adjacency.
  *   show       --id <id> [--repo-slug <slug>]
  *                 Print the full row behind a [L:id] pointer.
  *   from-triage --triage <path> --task <id> [--repo-slug <slug>]
@@ -91,6 +96,7 @@ for (let i = 1; i < argv.length; i++) {
 
 const KINDS = new Set(["fact", "convention", "rejected-preference"]);
 const CONFIDENCES = new Set(["low", "medium", "high"]);
+const SOURCES = new Set(["triage", "transcript-mining", "manual"]);
 
 function die(msg, code = 1) {
   process.stderr.write(`learnings-ledger: ${msg}\n`);
@@ -192,7 +198,7 @@ function writeRow(slug, row) {
 
 /** Append one entry unless an entry with the same kind + normalized statement
  *  already exists (idempotent). Returns true when written. */
-function addEntry(slug, { kind, statement, scope, task, confidence, diagnosis }, existing) {
+function addEntry(slug, { kind, statement, scope, task, confidence, diagnosis, source }, existing) {
   // One line, enforced here rather than hoped for. The schema says "the
   // knowledge itself, in one line", and both blocks render one entry per line -
   // a statement carrying a newline breaks out of its bullet, and since
@@ -218,6 +224,11 @@ function addEntry(slug, { kind, statement, scope, task, confidence, diagnosis },
   // one; a bare outcome does not. Stored only when supplied.
   const diag = oneLine(diagnosis);
   if (diag) row.diagnosis = diag;
+  // Who found it. Optional so old rows stay valid, but written whenever the
+  // caller knows: a machine-mined path correction and a model's architectural
+  // claim are different evidence, and a metric that pools them can rise while
+  // the useful half is flat.
+  if (SOURCES.has(source)) row.source = source;
   writeRow(slug, row);
   existing.add(seenKey);
   return true;
@@ -239,6 +250,7 @@ function cmdAdd() {
       confidence:
         flags.confidence && flags.confidence !== true ? String(flags.confidence) : "medium",
       diagnosis: flags.diagnosis && flags.diagnosis !== true ? String(flags.diagnosis) : null,
+      source: flags.source && flags.source !== true ? String(flags.source) : "manual",
     },
     existing,
   );
@@ -284,7 +296,14 @@ function cmdFromTriage() {
     if (
       addEntry(
         slug,
-        { kind: "rejected-preference", statement, scope, task, confidence: "low" },
+        {
+          kind: "rejected-preference",
+          statement,
+          scope,
+          task,
+          confidence: "low",
+          source: "triage",
+        },
         existing,
       )
     ) {
@@ -292,7 +311,8 @@ function cmdFromTriage() {
     }
   }
   process.stdout.write(JSON.stringify({ ok: true, slug, added: written, skippedBlocking }) + "\n");
-  process.exit(0);
+  process.exitCode = 0;
+  return;
 }
 
 function cmdForget() {
@@ -303,7 +323,8 @@ function cmdForget() {
   const p = ledgerPath(slug);
   if (!existsSync(p)) {
     process.stdout.write(JSON.stringify({ ok: true, slug, removed: 0 }) + "\n");
-    process.exit(0);
+    process.exitCode = 0;
+    return;
   }
   const rows = readLedger(slug);
   const kept = rows.filter((r) => {
@@ -322,7 +343,8 @@ function cmdForget() {
   writeFileSync(tmp, kept.length ? body + "\n" : "", "utf8");
   renameSync(tmp, p);
   process.stdout.write(JSON.stringify({ ok: true, slug, removed, remaining: kept.length }) + "\n");
-  process.exit(0);
+  process.exitCode = 0;
+  return;
 }
 
 const KIND_ORDER = ["fact", "convention", "rejected-preference"];
@@ -469,7 +491,8 @@ function cmdBrief() {
   process.stdout.write(
     ["<task-relevant-memory>", header, ...body, "</task-relevant-memory>"].join("\n") + "\n",
   );
-  process.exit(0);
+  process.exitCode = 0;
+  return;
 }
 
 /**
@@ -534,7 +557,8 @@ function cmdProfile() {
   }
   lines.push("</repo-profile>");
   process.stdout.write(lines.join("\n") + "\n");
-  process.exit(0);
+  process.exitCode = 0;
+  return;
 }
 
 function cmdShow() {
@@ -545,17 +569,63 @@ function cmdShow() {
   const row = readLedger(slug).find((r) => rowId(r) === want);
   if (!row) {
     process.stdout.write(JSON.stringify({ ok: false, slug, id: want, found: false }) + "\n");
-    process.exit(2);
+    process.exitCode = 2;
+    return;
   }
   process.stdout.write(JSON.stringify({ ok: true, slug, id: want, row }) + "\n");
-  process.exit(0);
+  process.exitCode = 0;
+  return;
+}
+
+/**
+ * Neighbourhood: what was learned around an entry.
+ *
+ * `brief` and `profile` rank by relevance, which answers "what applies here".
+ * That is a different question from "what else did we learn at the same time",
+ * and the second one has no answer without this: the only route was to read the
+ * whole ledger, so nobody asked it.
+ *
+ * The ledger is append-only, so line adjacency is chronological adjacency. No
+ * index, no timestamp arithmetic - the file's own order is the answer.
+ */
+function cmdTimeline() {
+  const id = flags.anchor && flags.anchor !== true ? String(flags.anchor) : null;
+  if (!id) die("timeline needs --anchor <id>", 1);
+  const slug = flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug();
+  const before = flags.before && flags.before !== true ? Math.max(0, Number(flags.before)) : 3;
+  const after = flags.after && flags.after !== true ? Math.max(0, Number(flags.after)) : 3;
+  const want = id.startsWith("L:") ? id : `L:${id}`;
+  const rows = readLedger(slug);
+  const at = rows.findIndex((r) => rowId(r) === want);
+  if (at === -1) {
+    process.stdout.write(JSON.stringify({ ok: false, slug, anchor: want, found: false }) + "\n");
+    process.exitCode = 2;
+    return;
+  }
+  const from = Math.max(0, at - before);
+  const to = Math.min(rows.length, at + after + 1);
+  const window = rows.slice(from, to).map((r, i) => ({
+    id: rowId(r),
+    offset: from + i - at,
+    kind: r.kind,
+    scope: r.scope,
+    source: r.source || null,
+    source_task: r.source_task || null,
+    statement: r.statement,
+  }));
+  process.stdout.write(
+    JSON.stringify({ ok: true, slug, anchor: want, before, after, rows: window }, null, 2) + "\n",
+  );
+  process.exitCode = 0;
+  return;
 }
 
 function cmdPath() {
   process.stdout.write(
     ledgerPath(flags["repo-slug"] ? String(flags["repo-slug"]) : repoSlug()) + "\n",
   );
-  process.exit(0);
+  process.exitCode = 0;
+  return;
 }
 
 function cmdStats() {
@@ -566,7 +636,8 @@ function cmdStats() {
   const out = { ok: true, slug, path: ledgerPath(slug), rows: rows.length, counts };
   if (existsSync(out.path)) out.bytes = statSync(out.path).size;
   process.stdout.write(JSON.stringify(out) + "\n");
-  process.exit(0);
+  process.exitCode = 0;
+  return;
 }
 
 switch (SUB) {
@@ -585,6 +656,9 @@ switch (SUB) {
   case "profile":
     cmdProfile();
     break;
+  case "timeline":
+    cmdTimeline();
+    break;
   case "show":
     cmdShow();
     break;
@@ -596,7 +670,7 @@ switch (SUB) {
     break;
   default:
     process.stderr.write(
-      "usage: learnings-ledger.mjs <add|from-triage|forget|brief|profile|show|path|stats> [flags]\n",
+      "usage: learnings-ledger.mjs <add|from-triage|forget|brief|profile|show|timeline|path|stats> [flags]\n",
     );
     process.exit(64);
 }

package/pipeline/scripts/note-session.sh

@@ -0,0 +1,187 @@
+#!/usr/bin/env bash
+#
+# note-session.sh  -  record what a NON-pipeline session ran into.
+#
+# WHY THIS EXISTS
+#
+# rules/outside-the-pipeline.md actively sends the user to work outside a
+# pipeline run: read a ticket, use a stack skill, call an MCP tool. That is the
+# right advice, and it meant every lesson learned in those sessions landed
+# nowhere - none of the five durable stores ever saw them, because all five are
+# written by pipeline phases.
+#
+# So this reads the session's own transcript and keeps the mechanical facts:
+# which repo was touched, which commands failed, which tool calls the user
+# refused. No model, no interpretation.
+#
+# WHAT IS DELIBERATELY NOT KEPT
+#
+# Not the prose. Not command arguments, not file contents, not tool output. A
+# transcript is the least redacted artefact on the machine - it holds whatever
+# the session read, tokens and customer data included - so what survives here is
+# the shape of an event and nothing that carries a payload: a command's first
+# word, a tool's name, an exit code, a count. That is enough for
+# learn-from-transcripts.mjs to correlate later, and it cannot leak a secret
+# because it never copies a value.
+#
+# Usage:
+#   ./note-session.sh [--transcript <path>] [--json] [--dry-run]
+#
+# Exit 0 always. It runs from SessionEnd; a hook that fails a session over
+# bookkeeping is worse than the bookkeeping it protects.
+
+set -uo pipefail
+
+TRANSCRIPT=""
+JSON=0
+DRY=0
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --transcript) TRANSCRIPT="${2:-}"; shift 2 || shift ;;
+    --json)       JSON=1; shift ;;
+    --dry-run)    DRY=1; shift ;;
+    -h|--help)    echo "usage: $0 [--transcript <path>] [--json] [--dry-run]" >&2; exit 0 ;;
+    *)            shift ;;
+  esac
+done
+
+# Claude Code exports the active transcript to the hook environment; falling back
+# to "newest under the project's own transcript dir" keeps the script runnable by
+# hand and in a gate.
+if [ -z "$TRANSCRIPT" ]; then
+  TRANSCRIPT="${CLAUDE_TRANSCRIPT_PATH:-}"
+fi
+if [ -z "$TRANSCRIPT" ]; then
+  SLUG_DIR="$HOME/.claude/projects/$(pwd | sed 's/[^A-Za-z0-9]/-/g')"
+  TRANSCRIPT=$(ls -t "$SLUG_DIR"/*.jsonl 2>/dev/null | head -1)
+fi
+
+if [ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ]; then
+  [ "$JSON" -eq 1 ] && printf '{"status":"noop","reason":"no-transcript"}\n'
+  exit 0
+fi
+
+REPO_SLUG=$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
+OUT_DIR="$HOME/.claude/memory/multi-agent/$REPO_SLUG"
+OUT="$OUT_DIR/session-notes.jsonl"
+
+TRANSCRIPT="$TRANSCRIPT" REPO_SLUG="$REPO_SLUG" OUT="$OUT" DRY="$DRY" JSON="$JSON" \
+python3 - <<'PY'
+import json, os, re, sys
+from collections import Counter
+from datetime import datetime, timezone
+
+path = os.environ["TRANSCRIPT"]
+
+# Only the head word of a command survives, and only when it looks like a plain
+# program name. `rm -rf /Users/<name>/secret` becomes `rm`; a command that starts
+# with a path or a variable becomes nothing at all.
+SAFE_HEAD = re.compile(r"^[a-z][a-z0-9_.-]{0,31}$")
+
+def head_word(cmd):
+    """The first real program in a command, or None.
+
+    `cd` swallows its argument: nearly every command in this codebase opens with
+    `cd <repo>`, and a version that skipped only the `cd` then hit the path and
+    redacted the whole line - so every failure was recorded with no command at
+    all. The path is what must not survive; the program after it is the signal.
+    """
+    if not isinstance(cmd, str):
+        return None
+    toks = cmd.strip().split()
+    i = 0
+    while i < len(toks):
+        tok = toks[i]
+        if tok in ("sudo", "env", "time", "command", "exec"):
+            i += 1
+            continue
+        if tok in ("cd", "pushd"):
+            i += 2          # drop the directory with it
+            continue
+        if tok in ("&&", ";", "|", "\\"):
+            i += 1
+            continue
+        if tok.startswith(("-", "/", "$", "(", "{", '"', "'", "!")):
+            return None
+        base = tok.split("/")[-1]
+        return base if SAFE_HEAD.match(base) else None
+    return None
+
+def result_text(block):
+    c = block.get("content")
+    if isinstance(c, list):
+        return " ".join(x.get("text", "") for x in c if isinstance(x, dict))
+    return c if isinstance(c, str) else ""
+
+pending = {}          # tool_use_id -> (tool name, command head)
+failed = Counter()    # command head -> failures
+denied = Counter()    # tool name -> refusals
+tools = Counter()     # tool name -> calls
+errors = 0
+
+try:
+    fh = open(path, encoding="utf-8")
+except Exception:
+    print(json.dumps({"status": "noop", "reason": "unreadable-transcript"}))
+    sys.exit(0)
+
+with fh:
+    for line in fh:
+        try:
+            d = json.loads(line)
+        except Exception:
+            continue
+        content = (d.get("message") or {}).get("content")
+        if not isinstance(content, list):
+            continue
+        for b in content:
+            if not isinstance(b, dict):
+                continue
+            if b.get("type") == "tool_use":
+                name = b.get("name") or "?"
+                tools[name] += 1
+                cmd = (b.get("input") or {}).get("command") if isinstance(b.get("input"), dict) else None
+                pending[b.get("id")] = (name, head_word(cmd))
+            elif b.get("type") == "tool_result":
+                name, cmd_head = pending.pop(b.get("tool_use_id"), ("?", None))
+                text = result_text(b)
+                # A refusal is not an error: the tool never ran. It says what the
+                # user does not want done, which is the more durable signal.
+                if "has been denied" in text:
+                    denied[name] += 1
+                elif b.get("is_error"):
+                    errors += 1
+                    if cmd_head:
+                        failed[cmd_head] += 1
+
+row = {
+    "v": "1.0.0",
+    "ts": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    "repo": os.environ["REPO_SLUG"],
+    "transcript": os.path.basename(path),
+    "source": "outside-pipeline",
+    "tool_calls": sum(tools.values()),
+    "tools": dict(tools.most_common(8)),
+    "errors": errors,
+    "failed_commands": dict(failed.most_common(8)),
+    "denied_tools": dict(denied),
+}
+
+# Nothing happened worth a row. An empty session should not grow the file.
+if row["tool_calls"] == 0 and errors == 0 and not denied:
+    print(json.dumps({"status": "noop", "reason": "nothing-observed"}))
+    sys.exit(0)
+
+if os.environ.get("DRY") == "1":
+    print(json.dumps({"status": "dry-run", "row": row}))
+    sys.exit(0)
+
+out = os.environ["OUT"]
+os.makedirs(os.path.dirname(out), exist_ok=True)
+with open(out, "a", encoding="utf-8") as fh:
+    fh.write(json.dumps(row, ensure_ascii=False) + "\n")
+
+print(json.dumps({"status": "written", "path": out, "errors": errors,
+                  "denied": sum(denied.values()), "toolCalls": row["tool_calls"]}))
+PY
+exit 0