backpass 0.1.12 → 0.1.14

package/README.md

@@ -158,8 +158,9 @@ strict JSON: which instructions helped, which were violated, and what mistakes n
 instruction covers. Every negative carries a class - `harm` (following the instruction
 caused damage), `non-compliance` (the agent ignored it), or `irrelevant` - because those
 argue for opposite fates: harm argues against an instruction, non-compliance argues for
-reinforcing it. Every gap carries a domain - `project` for this repository's own
-engineering, `orchestration` for the task-management layer around the session - and the
+reinforcing it. Every gap carries a domain - `orchestration` when the mistake was caused
+not by this repository but by an external agent harness or tooling that orchestrated the
+task, `project` for every other mistake - and the
 analysis is shown the ledger's open gaps so it can cite an existing gap id instead of
 coining a paraphrase of it.
 
@@ -193,8 +194,9 @@ consolidation call sees the full open gap set and merges entries that describe t
 mistake. That second judgment is what lets two sightings of a brand-new gap in the same
 run's parallel fan-out corroborate. A failed consolidation call degrades the run to
 lexical identity and says so; it never aborts. Orchestration-domain gaps are counted and
-reported but never cluster: mistakes about the task harness around a session do not
-become instructions in the project's memory file.
+reported but never cluster: a mistake caused not by this repository but by the external
+agent harness or tooling that orchestrated a session does not become an instruction in the
+project's memory file.
 
 Only evidence judged against the _current_ memory-file set hash is folded into a proposal. A
 transcript that fell out of this run's sample - the time window, `maxTranscripts`, or the
@@ -311,7 +313,10 @@ not duplicate content.
 
 `backpass apply` is the only command that writes. It serves a review surface through
 [`lavish-axi`](https://github.com/kunchenguid/lavish-axi): one card per edit with the diff,
-the evidence quotes and their sources, a live budget gauge, and ACCEPT / REJECT.
+the evidence quotes and their sources, a live budget gauge, and ACCEPT / REJECT. A compact
+gap funnel shows how accumulated sightings narrowed through domain filtering, clustering,
+and the corroboration floor to the gaps eligible for a proposal; older proposals without
+recorded funnel counts omit it.
 
 The surface is a static template shipped in the package - the CLI injects one JSON payload,
 so it is instant, deterministic, and identical every run. Nothing there is model-generated.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backpass",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "packageManager": "pnpm@11.5.0",
   "description": "Gradient descent for your agent memory - analyzes past agent session transcripts and proposes evidence-backed edits to AGENTS.md / CLAUDE.md",
   "type": "module",

package/src/fold.js

@@ -91,9 +91,9 @@ export function foldEvidence(evidenceRecords, { minGapEvidence = 2, memoryFile =
     }
   }
 
-  // Orchestration-domain sightings are about the task-management layer around the
-  // session, not this repository's engineering; they are counted for legibility but
-  // never cluster, so they can never corroborate into a project proposal.
+  // Orchestration-domain sightings are mistakes caused not by this repository but by the
+  // external agent harness or tooling that orchestrated the session; they are counted for
+  // legibility but never cluster, so they can never corroborate into a project proposal.
   const allObservations = gapObservations ?? recordObservations;
   const projectObservations = allObservations.filter((obs) => obs?.domain !== "orchestration");
   const orchestrationGapSightings = allObservations.length - projectObservations.length;
@@ -143,6 +143,10 @@ export function foldEvidence(evidenceRecords, { minGapEvidence = 2, memoryFile =
     totals: {
       positive: positiveCount,
       negative: negativeCount,
+      // The gap funnel's top: every sighting this fold clustered over (the pruned ledger
+      // when one is passed, this run's records otherwise). Orchestration sightings are the
+      // slice excluded before clustering; project-domain is the difference.
+      gapSightings: allObservations.length,
       gapClusters: gaps.length,
       droppedGapSingletons,
       orchestrationGapSightings,
@@ -230,8 +234,8 @@ export function renderEvidenceForPrompt(summary) {
   lines.push("### Gap clusters (mistakes no current instruction covers)");
   if (summary.totals.orchestrationGapSightings) {
     lines.push(
-      `- ${summary.totals.orchestrationGapSightings} orchestration-domain sighting(s) about the ` +
-        `task-management layer were excluded; they never enter this repository's memory file`,
+      `- ${summary.totals.orchestrationGapSightings} orchestration-domain sighting(s) caused by the ` +
+        `orchestrating harness or tooling were excluded; they never enter this repository's memory file`,
     );
   }
   if (!summary.gaps.length) {

package/src/gap-ledger.js

@@ -26,9 +26,9 @@ import { sha256 } from "./state.js";
  *    merged by the pre-synthesis consolidation pass (`mergeGapEntries`, driven by
  *    `src/consolidate.js`), which is what lets two same-run parallel sightings - neither
  *    of which could cite the other - still corroborate.
- *  - Every observation carries the `domain` the analysis judged: `project` for mistakes
- *    about this repository's own engineering, `orchestration` for mistakes about the
- *    task-management layer around it (briefs, scout scope, status records, approvals).
+ *  - Every observation carries the `domain` the analysis judged: `orchestration` when the
+ *    mistake was not caused by this repository but by an external agent harness or tooling
+ *    that orchestrated the task, `project` for every other mistake.
  *    Orchestration sightings are recorded for legibility but never counted toward
  *    corroboration and never surface in a proposal; a missing domain counts as project,
  *    so evidence from before the field existed keeps its old behavior.

package/src/prompts/analysis.md

@@ -53,12 +53,12 @@ Rules, in order of importance:
    or violated the instruction - evidence the instruction failed to steer, which argues
    for reinforcing it, never for deleting it. `irrelevant`: on inspection the moment
    does not actually bear on this instruction. Never report a skipped rule as `harm`.
-4. **`domain` states whose mistake a gap is.** `project`: about this repository's own
-   engineering - its code, tests, build, docs, releases, conventions. `orchestration`:
-   about the task-management layer around the session - task briefs and their scope
-   (scout/read-only rules), status reporting to a supervisor, approval and authorization
-   flows, delivery-lifecycle process imposed from outside the repository. Orchestration
-   gaps are counted but never proposed into this repository's memory file.
+4. **`domain` states what caused a gap.** A gap is `orchestration` when the mistake was
+   not caused by this repository, but by an external agent harness or tooling that
+   orchestrated the task (a task brief, a supervisor's process, the harness itself - by
+   way of illustration only, not a list to match against); every other gap is `project`.
+   Ask the causal question, not which category the wording resembles. Orchestration gaps
+   are counted but never proposed into this repository's memory file.
 5. **Do not confabulate influence.** Only call something positive when the trace shows
    the agent doing the specific thing the instruction asks for. An outcome that would
    have happened anyway is not evidence.

package/src/prompts/synthesis.md

@@ -81,7 +81,7 @@ analyzed sessions in which an instruction drew any evidence at all.
 5. **Every edit must be backed by at least one verbatim quote** from the evidence. You
    will attach the quotes in the next step, so only make changes you can back.
 6. **Budget:** {{BUDGET_RULE}}
-7. Prefer extracting a long, narrow, crisply-triggered section over deleting anything:
+7. You can extract a long, narrow, crisply-triggered section instead of deleting it:
    extraction frees the same always-loaded tokens and loses nothing.
 8. Change only `./{{MEMORY_PATH}}` and files under `./{{SKILLS_DIR}}/`. Never delete a
    file. Do not create notes, scripts, or scratch files.
@@ -94,7 +94,7 @@ analyzed sessions in which an instruction drew any evidence at all.
 | Conditional / narrow     | **skill** (the description is the condition) | deletion candidate |
 
 A skill's description is always loaded and its body is free until triggered, so moving a
-long, narrow, crisply-triggered section into a skill is nearly pure budget profit.
+section into a skill trades its always-loaded cost for that one description line.
 
 **Skill descriptions are weights too.** If the evidence shows an agent lacked knowledge
 an existing skill already contains, that is a failed trigger: rewrite that skill's

package/src/proposal.js

@@ -489,6 +489,13 @@ export function buildProposal(rawResult, context) {
       positive: summary?.totals?.positive ?? 0,
       negative: summary?.totals?.negative ?? 0,
       gapClusters: summary?.totals?.gapClusters ?? 0,
+      // The gap funnel, for the apply surface: sightings -> project-domain (sightings
+      // minus orchestration) -> distinct gaps (clusters + dropped) -> eligible
+      // (clusters). `null`, never 0, when the summary predates a count - the surface
+      // hides what was not recorded rather than showing an invented zero.
+      gapSightings: summary?.totals?.gapSightings ?? null,
+      orchestrationGapSightings: summary?.totals?.orchestrationGapSightings ?? null,
+      droppedGapSingletons: summary?.totals?.droppedGapSingletons ?? null,
       skillExtractions: accepted.reduce((n, e) => n + editSkills(e).length, 0),
     },
     edits: accepted,

package/templates/apply.html

@@ -126,6 +126,124 @@
         margin-top: 3px;
       }
 
+      /* ---------- gap funnel ---------- */
+      /* The template's own display rules (.statrow's grid) would beat the UA
+         stylesheet's [hidden]; this keeps the hidden attribute authoritative. */
+      [hidden] {
+        display: none !important;
+      }
+      .run-context {
+        border: 1px solid var(--line);
+        background: var(--line);
+        display: grid;
+        grid-template-columns: minmax(0, 3fr) minmax(280px, 2fr);
+        gap: 1px;
+        margin-bottom: 36px;
+      }
+      .ctx-funnel {
+        background: var(--panel);
+        padding: 13px 18px 14px;
+        min-width: 0;
+      }
+      .ctx-stats {
+        display: grid;
+        grid-template-columns: 1fr 1fr;
+        grid-auto-rows: 1fr;
+        gap: 1px;
+        min-width: 0;
+      }
+      .funnel-head {
+        display: flex;
+        justify-content: space-between;
+        align-items: baseline;
+        flex-wrap: wrap;
+        gap: 8px;
+        margin-bottom: 10px;
+      }
+      .funnel-head .t {
+        font-size: 13px;
+        color: var(--dim);
+      }
+      .funnel-head .facts {
+        font-family: var(--mono);
+        font-size: 11px;
+        color: var(--faint);
+      }
+      .funnel-head .facts b {
+        color: var(--text);
+        font-weight: 500;
+      }
+      .frow {
+        display: flex;
+        align-items: center;
+        gap: 12px;
+        margin: 4px 0;
+      }
+      .frow .fl {
+        width: 148px;
+        flex: none;
+        font-family: var(--mono);
+        font-size: 10px;
+        letter-spacing: 0.11em;
+        text-transform: uppercase;
+        color: var(--faint);
+        white-space: nowrap;
+        overflow: hidden;
+        text-overflow: ellipsis;
+      }
+      .frow .fb {
+        flex: 1;
+        min-width: 0;
+        display: flex;
+        align-items: center;
+        height: 16px;
+        background: var(--panel-2);
+        border: 1px solid var(--line-soft);
+      }
+      .frow .fb i {
+        display: block;
+        height: 100%;
+        background: rgba(110, 168, 255, 0.38);
+        border-right: 1px solid rgba(110, 168, 255, 0.75);
+      }
+      .frow.lit .fb i {
+        background: rgba(79, 227, 193, 0.4);
+        border-right-color: var(--accent);
+      }
+      .frow.zero .fb i {
+        border-right: none;
+      }
+      .frow .fv {
+        flex: none;
+        width: 34px;
+        font-family: var(--mono);
+        font-size: 12.5px;
+        color: var(--text);
+      }
+      .frow.zero .fv {
+        color: var(--faint);
+      }
+      .frow.lit .fv {
+        color: var(--accent);
+      }
+      .fdrop {
+        margin: 1px 0 6px 160px;
+        font-size: 12px;
+        color: var(--dim);
+      }
+      .fdrop b {
+        font-family: var(--mono);
+        font-weight: 500;
+        color: var(--faint);
+      }
+      .funnel-note {
+        margin-top: 10px;
+        padding-top: 9px;
+        border-top: 1px dashed var(--line-soft);
+        font-size: 12.5px;
+        color: var(--dim);
+      }
+
       /* ---------- budget gauge ---------- */
       .gauge-block {
         border: 1px solid var(--line);
@@ -564,7 +682,7 @@
         cursor: not-allowed;
       }
 
-      @media (max-width: 640px) {
+      @media (max-width: 760px) {
         .wrap {
           padding: 28px 16px 170px;
         }
@@ -572,6 +690,15 @@
           padding: 12px 16px;
           gap: 12px;
         }
+        .run-context {
+          grid-template-columns: minmax(0, 1fr);
+        }
+        .frow .fl {
+          width: 92px;
+        }
+        .fdrop {
+          margin-left: 0;
+        }
       }
     </style>
   </head>
@@ -584,7 +711,19 @@
       </div>
       <div class="runline" id="runline"></div>
 
-      <div class="statrow" id="statrow"></div>
+      <div class="statrow" id="statrow" hidden></div>
+
+      <div class="run-context" id="ctx" hidden>
+        <div class="ctx-funnel">
+          <div class="funnel-head">
+            <span class="t">Gap funnel · counted across runs</span>
+            <span class="facts num" id="funnel-floor"></span>
+          </div>
+          <div id="funnel-bars"></div>
+          <div class="funnel-note" id="funnel-note" hidden></div>
+        </div>
+        <div class="ctx-stats" id="ctx-stats"></div>
+      </div>
 
       <div class="gauge-block">
         <div class="gauge-head">
@@ -668,26 +807,142 @@
           document.createTextNode(" transcripts" + (harnessBits.length ? " (" + harnessBits.join(" · ") + ")" : "")),
         );
 
-        // ---- stats ----
-        var stats = [
+        // ---- run context: one frame, the gap funnel beside the run stats ----
+        // A single bordered band. The left pane tells the gap story as proportional
+        // bars - sightings recorded by analysis -> project-domain (orchestration
+        // excluded) -> distinct gaps after clustering -> eligible to propose - with
+        // each drop-off explained in plain words. The right pane holds the run facts
+        // (edits, evidence, skills) as stat cells; a separate stat row would duplicate
+        // the funnel's last stage. Every count is recorded by the fold (`totals` in
+        // evidence-summary.json); a proposal saved before the counts existed falls
+        // back to the classic stat row rather than showing zeros nobody measured.
+        function funnelCounts() {
+          if (typeof (P.stats || {}).gapSightings !== "number") return null;
+          var eligible = P.stats.gapClusters || 0;
+          var dropped = P.stats.droppedGapSingletons || 0;
+          var orch = P.stats.orchestrationGapSightings || 0;
+          var project = Math.max(0, P.stats.gapSightings - orch);
+          return {
+            floor: Number((P.config || {}).minGapEvidence) || 2,
+            sighted: P.stats.gapSightings,
+            orch: orch,
+            project: project,
+            distinct: eligible + dropped,
+            merged: Math.max(0, project - (eligible + dropped)),
+            dropped: dropped,
+            eligible: eligible,
+          };
+        }
+        function funnelBar(host, value, label, max, lit) {
+          var row = el("div", "frow" + (value === 0 ? " zero" : lit ? " lit" : ""));
+          row.appendChild(el("span", "fl", label));
+          var track = el("div", "fb");
+          var fill = el("i");
+          fill.style.width = max > 0 ? Math.max((value / max) * 100, value > 0 ? 2 : 0) + "%" : "0%";
+          track.appendChild(fill);
+          row.appendChild(track);
+          row.appendChild(el("span", "fv num", fmt(value)));
+          host.appendChild(row);
+        }
+        function funnelDrop(host, n, text) {
+          if (!n) return;
+          var line = el("div", "fdrop");
+          line.appendChild(el("b", null, "− " + fmt(n) + " "));
+          line.appendChild(document.createTextNode(text));
+          host.appendChild(line);
+        }
+        var funnelNote = null;
+        var funnel = funnelCounts();
+        if (funnel) {
+          var bars = document.getElementById("funnel-bars");
+          funnelBar(bars, funnel.sighted, "sightings", funnel.sighted);
+          funnelDrop(
+            bars,
+            funnel.orch,
+            "orchestration: mistakes in how the task was run, not in this project - excluded from proposals by design",
+          );
+          funnelBar(bars, funnel.project, "project-domain", funnel.sighted);
+          funnelDrop(
+            bars,
+            funnel.merged,
+            "merged: repeat sightings of a gap already counted - they corroborate it rather than add a new one",
+          );
+          funnelBar(bars, funnel.distinct, "distinct gaps", funnel.sighted);
+          funnelDrop(
+            bars,
+            funnel.dropped,
+            "below the corroboration floor: seen in fewer than " +
+              funnel.floor +
+              " sessions so far - more transcripts can corroborate them",
+          );
+          funnelBar(bars, funnel.eligible, "eligible to propose", funnel.sighted, true);
+
+          document.getElementById("funnel-floor").textContent = "corroboration floor · " + funnel.floor + " sessions";
+          var statHost = document.getElementById("ctx-stats");
           [
-            String(edits.length) + "/" + String((P.config || {}).maxEditsPerRun || edits.length),
-            "edits proposed / cap",
-            null,
-          ],
-          [fmt(P.stats.positive), "positive evidence", "accent"],
-          [fmt(P.stats.negative), "negative evidence", "reject"],
-          [fmt(P.stats.gapClusters), "gap clusters", "defer"],
-          [fmt(P.stats.skillExtractions), "skill extractions", null],
-        ];
-        var statrow = document.getElementById("statrow");
-        stats.forEach(function (s) {
-          var box = el("div", "stat");
-          var v = el("div", "v num", s[0]);
-          box.appendChild(v);
-          box.appendChild(el("div", "k", s[1]));
-          statrow.appendChild(box);
-        });
+            [
+              String(edits.length) + "/" + String((P.config || {}).maxEditsPerRun || edits.length),
+              "edits proposed / cap",
+            ],
+            [fmt(P.stats.positive), "positive evidence"],
+            [fmt(P.stats.negative), "negative evidence"],
+            [fmt(P.stats.skillExtractions), "skill extractions"],
+          ].forEach(function (s) {
+            var box = el("div", "stat");
+            box.appendChild(el("div", "v num", s[0]));
+            box.appendChild(el("div", "k", s[1]));
+            statHost.appendChild(box);
+          });
+
+          // The drop lines carry the takeaway; the visible note only speaks when there
+          // are no bars to read. funnelNote itself still feeds the zero-edit empty state.
+          if (!funnel.sighted) {
+            funnelNote = "Analysis reported no uncovered gaps.";
+          } else if (!funnel.eligible && funnel.dropped) {
+            funnelNote =
+              funnel.dropped +
+              " distinct gap" +
+              (funnel.dropped === 1 ? " is" : "s are") +
+              " still below the " +
+              funnel.floor +
+              "-session corroboration floor - more transcripts may corroborate " +
+              (funnel.dropped === 1 ? "it." : "them.");
+          } else if (!funnel.eligible && funnel.orch >= funnel.sighted) {
+            funnelNote =
+              "All " +
+              funnel.sighted +
+              " sighting" +
+              (funnel.sighted === 1 ? " was" : "s were") +
+              " orchestration-domain (caused by the orchestrating harness, not this repository) and " +
+              (funnel.sighted === 1 ? "is" : "are") +
+              " excluded by design.";
+          }
+          if (funnelNote && !funnel.sighted) {
+            var noteEl = document.getElementById("funnel-note");
+            noteEl.textContent = funnelNote;
+            noteEl.hidden = false;
+          }
+          document.getElementById("ctx").hidden = false;
+        } else {
+          // A proposal from before the funnel counts existed: the classic stat row.
+          var statrow = document.getElementById("statrow");
+          statrow.hidden = false;
+          [
+            [
+              String(edits.length) + "/" + String((P.config || {}).maxEditsPerRun || edits.length),
+              "edits proposed / cap",
+            ],
+            [fmt(P.stats.positive), "positive evidence"],
+            [fmt(P.stats.negative), "negative evidence"],
+            [fmt(P.stats.gapClusters), "eligible gaps"],
+            [fmt(P.stats.skillExtractions), "skill extractions"],
+          ].forEach(function (s) {
+            var box = el("div", "stat");
+            box.appendChild(el("div", "v num", s[0]));
+            box.appendChild(el("div", "k", s[1]));
+            statrow.appendChild(box);
+          });
+        }
 
         // ---- budget gauge ----
         document.getElementById("gauge-title").textContent = "Always-loaded budget · " + (P.memoryFile.path || "");
@@ -700,8 +955,21 @@
           edits.length + " of " + ((P.config || {}).maxEditsPerRun || edits.length) + " (learning-rate cap)";
 
         if (!edits.length) {
+          var eligibleWithoutEdits = Number((P.stats || {}).gapClusters) || 0;
+          var emptyReason = funnelNote;
+          if (!emptyReason && eligibleWithoutEdits > 0) {
+            emptyReason =
+              fmt(eligibleWithoutEdits) +
+              " eligible gap" +
+              (eligibleWithoutEdits === 1 ? "" : "s") +
+              " reached synthesis, but no edit was proposed this run.";
+          }
           host.appendChild(
-            el("div", "empty", "No edits proposed. The evidence did not clear the thresholds this run."),
+            el(
+              "div",
+              "empty",
+              "No edits proposed. " + (emptyReason || "The evidence did not clear the thresholds this run."),
+            ),
           );
         }