portawhip 0.1.0

package/core/state/feedback.mjs

@@ -0,0 +1,129 @@
+// PLAN.md Phase 4 step 1/2: append-only usage log + bounded weight
+// adjustment. Append-only JSONL, never rewritten in place — matches the
+// "no daemon, cheap, live-probed" style already used elsewhere in this
+// repo, and avoids concurrent-write corruption risk from two hook
+// processes editing the same file.
+//
+// Simplification (documented, not hidden): correlation is per-capability-id
+// across all events, not strictly scoped to one session — a "used" event
+// for id X counts as a hit for whatever the most recent unresolved
+// "suggested" event for X was, regardless of which session logged either
+// one. Good enough for the boost/decay signal this phase asks for; revisit
+// only if cross-session bleed is actually observed causing a wrong weight.
+
+import { appendFileSync, readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isSyntheticPrompt } from "../router/prompt-hygiene.mjs";
+
+// Unbounded append-only growth was a real gap (found during a project
+// review, not a live incident): this log has no rotation, so heavy daily
+// use would grow it forever and slow computeFactors()'s full-file scan.
+// Cheap fix: check file SIZE (no read) on every append — only pay the cost
+// of a full read+rewrite the rare time the file actually crosses the cap.
+const PRUNE_CHECK_BYTES = 512 * 1024; // ~512KB before we even look closer
+const MAX_EVENTS = 5000; // keep the most recent N events after a prune
+
+export function feedbackPathFor(root) {
+  return join(root, ".hp-state", "feedback", "events.jsonl");
+}
+
+function pruneIfOversized(path) {
+  let size;
+  try {
+    size = statSync(path).size;
+  } catch {
+    return;
+  }
+  if (size < PRUNE_CHECK_BYTES) return;
+
+  const lines = readFileSync(path, "utf8").split("\n").filter((line) => line.trim());
+  if (lines.length <= MAX_EVENTS) return;
+  writeFileSync(path, lines.slice(-MAX_EVENTS).join("\n") + "\n");
+}
+
+export function logEvent(root, event) {
+  const path = feedbackPathFor(root);
+  mkdirSync(dirname(path), { recursive: true });
+  pruneIfOversized(path);
+  appendFileSync(path, JSON.stringify({ ts: Date.now(), ...event }) + "\n");
+}
+
+export function readEvents(root) {
+  const path = feedbackPathFor(root);
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf8")
+    .split("\n")
+    .filter((line) => line.trim())
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+// Bounded per PLAN.md spec: x0.5 (ignored streak) .. x2.0 (used streak).
+// Streak = consecutive most-recent suggestions for this id with the same
+// used/ignored outcome, walking back from the newest event.
+export function computeFactors(root) {
+  const events = readEvents(root).sort((a, b) => a.ts - b.ts);
+  const byId = new Map();
+  for (const e of events) {
+    if (e.type !== "suggested" && e.type !== "used") continue;
+    // Read-side hygiene, not a log rewrite: suggestions fired against
+    // harness-generated payloads (the hook now skips them at the source, but
+    // 21/26 historical suggested events were exactly this) must not count as
+    // "ignored" outcomes - that decayed genuinely good capabilities on noise.
+    // Filtering here retroactively cleans history while keeping the JSONL
+    // append-only.
+    if (e.type === "suggested" && isSyntheticPrompt(e.prompt)) continue;
+    if (!byId.has(e.id)) byId.set(e.id, []);
+    byId.get(e.id).push(e);
+  }
+
+  const factors = new Map();
+  for (const [id, idEvents] of byId) {
+    // Resolve each "suggested" against the next "used" that follows it in
+    // time for the same id -> a bounded sequence of hit/miss outcomes.
+    //
+    // Asymmetric credit (2026-07-09): suggestions with source:"pull" (MCP
+    // route() results - Claude asked) count toward boost when followed by a
+    // "used", but an unused pull suggestion resolves to NO outcome, not an
+    // ignored one. Pull is recall-generous by design - most returned
+    // candidates going unused is normal operation, not negative signal.
+    // Only push suggestions (unsolicited injections the model definitely
+    // saw) earn decay when ignored.
+    const outcomes = [];
+    let pending = null; // null | "push" | "pull"
+    const resolveIgnored = () => {
+      if (pending === "push") outcomes.push(false);
+      pending = null;
+    };
+    for (const e of idEvents) {
+      if (e.type === "suggested") {
+        resolveIgnored();
+        pending = e.source === "pull" ? "pull" : "push";
+      } else if (e.type === "used" && pending) {
+        outcomes.push(true);
+        pending = null;
+      }
+    }
+    resolveIgnored();
+
+    if (outcomes.length === 0) {
+      factors.set(id, 1.0);
+      continue;
+    }
+    let streak = 0;
+    const last = outcomes[outcomes.length - 1];
+    for (let i = outcomes.length - 1; i >= 0 && outcomes[i] === last; i -= 1) streak += 1;
+
+    const factor = last
+      ? Math.min(2.0, 1 + 0.2 * streak)
+      : Math.max(0.5, 1 - 0.15 * streak);
+    factors.set(id, Number(factor.toFixed(3)));
+  }
+  return factors;
+}

package/core/state/feedback.test.mjs

@@ -0,0 +1,181 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { logEvent, readEvents, computeFactors } from "./feedback.mjs";
+
+function tempRoot() {
+  return mkdtempSync(join(tmpdir(), "harness-feedback-"));
+}
+
+test("feedback: no events -> neutral factor", () => {
+  const root = tempRoot();
+  try {
+    const factors = computeFactors(root);
+    assert.equal(factors.size, 0);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("feedback: a single used suggestion boosts above 1.0", () => {
+  const root = tempRoot();
+  try {
+    logEvent(root, { type: "suggested", id: "ripgrep" });
+    logEvent(root, { type: "used", id: "ripgrep", tool: "Bash" });
+    const factors = computeFactors(root);
+    assert.equal(factors.get("ripgrep"), 1.2);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("feedback: repeated ignores decay toward the 0.5 floor, never below it", () => {
+  const root = tempRoot();
+  try {
+    for (let i = 0; i < 10; i += 1) logEvent(root, { type: "suggested", id: "ripgrep" });
+    const factors = computeFactors(root);
+    assert.equal(factors.get("ripgrep"), 0.5);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("feedback: repeated uses cap at the 2.0 ceiling, never above it", () => {
+  const root = tempRoot();
+  try {
+    for (let i = 0; i < 10; i += 1) {
+      logEvent(root, { type: "suggested", id: "ripgrep" });
+      logEvent(root, { type: "used", id: "ripgrep", tool: "Bash" });
+    }
+    const factors = computeFactors(root);
+    assert.equal(factors.get("ripgrep"), 2.0);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("feedback: unrelated capability ids don't affect each other's factor", () => {
+  const root = tempRoot();
+  try {
+    for (let i = 0; i < 6; i += 1) logEvent(root, { type: "suggested", id: "pdf" }); // ignored
+    logEvent(root, { type: "suggested", id: "context7" });
+    logEvent(root, { type: "used", id: "context7", tool: "mcp__context7__resolve-library-id" });
+    const factors = computeFactors(root);
+    assert.ok(factors.get("pdf") < 1.0);
+    assert.ok(factors.get("context7") > 1.0);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("feedback: readEvents reflects logged events in order", () => {
+  const root = tempRoot();
+  try {
+    logEvent(root, { type: "suggested", id: "a" });
+    logEvent(root, { type: "used", id: "a" });
+    const events = readEvents(root);
+    assert.equal(events.length, 2);
+    assert.equal(events[0].type, "suggested");
+    assert.equal(events[1].type, "used");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("feedback: log file is pruned once it crosses the size threshold", () => {
+  const root = tempRoot();
+  const TOTAL = 12000;
+  try {
+    // Force many small events so the file crosses the prune-check size
+    // (~512KB) at least once — pruning is a size-triggered, approximate
+    // cap (checked on append, not re-checked until the next 512KB of
+    // growth), not an exact "never more than 5000 lines" guarantee.
+    for (let i = 0; i < TOTAL; i += 1) logEvent(root, { type: "suggested", id: `cap-${i % 5}` });
+    const events = readEvents(root);
+    assert.ok(events.length < TOTAL, `expected pruning to have happened, got ${events.length} of ${TOTAL}`);
+    assert.ok(events.length > 0);
+    // Most recent event must survive the prune.
+    assert.equal(events[events.length - 1].id, `cap-${(TOTAL - 1) % 5}`);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("feedback: suggestions fired on synthetic prompts are ignored, not counted as decay", () => {
+  const root = tempRoot();
+  try {
+    // 21/26 historical suggested events were harness task-notifications
+    // (2026-07-09 audit) - each would count as an "ignored" outcome and
+    // decay the capability on pure noise. The read-side filter must skip
+    // them without touching the append-only log.
+    for (let i = 0; i < 5; i += 1) {
+      logEvent(root, {
+        type: "suggested",
+        id: "ripgrep",
+        prompt: "<task-notification>\n<task-id>x</task-id>\n<summary>done</summary>\n</task-notification>",
+      });
+    }
+    // One genuine suggested->used pair: the only signal that should count.
+    logEvent(root, { type: "suggested", id: "ripgrep", prompt: "search codebase for foo" });
+    logEvent(root, { type: "used", id: "ripgrep", tool: "Bash" });
+    const factors = computeFactors(root);
+    assert.equal(factors.get("ripgrep"), 1.2); // single-hit boost, no noise decay mixed in
+    assert.equal(readEvents(root).length, 7); // log itself untouched
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("feedback: pull-suggested then used earns boost (asymmetric credit, hit side)", () => {
+  const root = tempRoot();
+  try {
+    logEvent(root, { type: "suggested", id: "exa", source: "pull", query: "web search" });
+    logEvent(root, { type: "used", id: "exa", tool: "mcp__exa__web_search_exa" });
+    const factors = computeFactors(root);
+    assert.equal(factors.get("exa"), 1.2);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("feedback: pull-suggested but never used stays neutral, no decay", () => {
+  const root = tempRoot();
+  try {
+    // Pull is recall-generous: unused pull results are normal operation.
+    for (let i = 0; i < 10; i += 1) {
+      logEvent(root, { type: "suggested", id: "exa", source: "pull", query: "web search" });
+    }
+    const factors = computeFactors(root);
+    assert.equal(factors.get("exa"), 1.0);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("feedback: push-suggested and ignored still decays (existing behavior preserved)", () => {
+  const root = tempRoot();
+  try {
+    logEvent(root, { type: "suggested", id: "ripgrep", prompt: "search codebase for foo" });
+    logEvent(root, { type: "suggested", id: "ripgrep", prompt: "search codebase again" });
+    const factors = computeFactors(root);
+    assert.ok(factors.get("ripgrep") < 1.0);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("feedback: mixed pull-ignored between push events doesn't break push decay", () => {
+  const root = tempRoot();
+  try {
+    // push ignored -> pull ignored (no outcome) -> push ignored: streak of 2 ignores.
+    logEvent(root, { type: "suggested", id: "x", prompt: "real prompt one here" });
+    logEvent(root, { type: "suggested", id: "x", source: "pull", query: "lookup" });
+    logEvent(root, { type: "suggested", id: "x", prompt: "real prompt two here" });
+    const factors = computeFactors(root);
+    assert.equal(factors.get("x"), Math.max(0.5, 1 - 0.15 * 2));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/core/state/runtime-root.test.mjs

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { resolveRuntimeRoot } from "./bundle-state.mjs";
+
+test("resolveRuntimeRoot prefers a workspace recipe and otherwise uses the package root", () => {
+  const workspace = mkdtempSync(join(tmpdir(), "portawhip-workspace-"));
+  const packageRoot = mkdtempSync(join(tmpdir(), "portawhip-package-"));
+  try {
+    writeFileSync(join(packageRoot, "recipe.yaml"), "[]\n");
+    assert.equal(resolveRuntimeRoot(workspace, packageRoot), packageRoot);
+
+    writeFileSync(join(workspace, "recipe.yaml"), "[]\n");
+    assert.equal(resolveRuntimeRoot(workspace, packageRoot), workspace);
+  } finally {
+    rmSync(workspace, { recursive: true, force: true });
+    rmSync(packageRoot, { recursive: true, force: true });
+  }
+});
+

package/core/state/stack-detect.mjs

@@ -0,0 +1,102 @@
+// Router gap found in review: nothing in the scoring pipeline knows what
+// language/stack the CALLING project actually is, even though the eval
+// harness's own failures are exactly cross-language mismatches (cpp-testing
+// outscoring python-testing on a literal "pytest" prompt). Detecting the
+// project's real stack from marker files and turning it into a per-id
+// score factor is a cheap, deterministic, zero-dependency fix — reuses the
+// same factor-multiplier seam core/feedback.mjs already established.
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+const STACK_MARKERS = {
+  python: ["requirements.txt", "pyproject.toml", "setup.py", "Pipfile"],
+  javascript: ["package.json"],
+  go: ["go.mod"],
+  rust: ["Cargo.toml"],
+  java: ["pom.xml", "build.gradle", "build.gradle.kts"],
+  ruby: ["Gemfile"],
+  php: ["composer.json"],
+  swift: ["Package.swift"],
+  dart: ["pubspec.yaml"],
+  cpp: ["CMakeLists.txt"],
+};
+
+const STACK_EXTENSIONS = {
+  csharp: [".csproj", ".sln"],
+};
+
+// What language a capability doc is ABOUT, inferred from its id — this
+// ecosystem consistently names language-scoped skills/agents "<lang>-...."
+// (python-testing, cpp-reviewer, golang-patterns) or names a framework that
+// implies one language (django-tdd implies python, quarkus-patterns implies
+// java). Only doc ids that hit one of these keywords are touched at all;
+// generic entries (code-review, tdd-workflow, git-workflow) are never
+// boosted or demoted by stack detection.
+const DOC_STACK_KEYWORDS = {
+  python: ["python", "django", "flask", "fastapi", "pytest"],
+  javascript: ["javascript", "typescript", "react", "vue", "node", "nextjs", "nuxt", "angular", "bun", "vite"],
+  go: ["golang", "go-"],
+  rust: ["rust", "cargo"],
+  java: ["java", "spring", "quarkus", "jpa"],
+  ruby: ["ruby", "rails"],
+  php: ["php", "laravel"],
+  swift: ["swift"],
+  dart: ["dart", "flutter"],
+  cpp: ["cpp"],
+  csharp: ["csharp", "dotnet"],
+  kotlin: ["kotlin"],
+};
+
+export function detectStack(cwd) {
+  const detected = new Set();
+  for (const [lang, markers] of Object.entries(STACK_MARKERS)) {
+    if (markers.some((marker) => existsSync(join(cwd, marker)))) detected.add(lang);
+  }
+  let entries = [];
+  try {
+    entries = readdirSync(cwd);
+  } catch {
+    entries = [];
+  }
+  for (const [lang, exts] of Object.entries(STACK_EXTENSIONS)) {
+    if (entries.some((name) => exts.some((ext) => name.endsWith(ext)))) detected.add(lang);
+  }
+  return detected;
+}
+
+function docStacks(id) {
+  const idLower = id.toLowerCase();
+  const stacks = new Set();
+  for (const [lang, keywords] of Object.entries(DOC_STACK_KEYWORDS)) {
+    if (keywords.some((kw) => idLower.includes(kw))) stacks.add(lang);
+  }
+  return stacks;
+}
+
+// Precision-first (PLAN.md: "precision over recall") — only ever touches
+// docs that are unambiguously about a specific stack, and only ever acts
+// once at least one stack was actually detected in cwd. An unrecognized or
+// empty project must not demote anything.
+export function stackFactors(index, cwd, { boost = 1.3, demote = 0.4 } = {}) {
+  const factors = new Map();
+  const detected = detectStack(cwd);
+  if (detected.size === 0) return factors;
+  for (const entry of index.entries) {
+    const stacks = docStacks(entry.id);
+    if (stacks.size === 0) continue;
+    const overlaps = [...stacks].some((lang) => detected.has(lang));
+    factors.set(entry.id, overlaps ? boost : demote);
+  }
+  return factors;
+}
+
+export function combineFactors(...maps) {
+  const combined = new Map();
+  for (const map of maps) {
+    for (const [id, value] of map) {
+      combined.set(id, (combined.get(id) ?? 1.0) * value);
+    }
+  }
+  return combined;
+}

package/core/state/stack-detect.test.mjs

@@ -0,0 +1,64 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { detectStack, stackFactors, combineFactors } from "./stack-detect.mjs";
+
+function tempDir() {
+  return mkdtempSync(join(tmpdir(), "stack-detect-test-"));
+}
+
+test("detectStack: empty dir detects nothing", () => {
+  const dir = tempDir();
+  try {
+    assert.deepEqual(detectStack(dir), new Set());
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("detectStack: requirements.txt marks python", () => {
+  const dir = tempDir();
+  try {
+    writeFileSync(join(dir, "requirements.txt"), "pytest\n");
+    assert.ok(detectStack(dir).has("python"));
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("stackFactors: empty cwd returns no factors (no demotion on unknown project)", () => {
+  const dir = tempDir();
+  try {
+    const index = { entries: [{ id: "cpp-testing" }, { id: "python-testing" }] };
+    const factors = stackFactors(index, dir);
+    assert.equal(factors.size, 0);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("stackFactors: python project demotes cpp-testing, boosts python-testing, leaves generic docs alone", () => {
+  const dir = tempDir();
+  try {
+    writeFileSync(join(dir, "requirements.txt"), "pytest\n");
+    const index = {
+      entries: [{ id: "cpp-testing" }, { id: "python-testing" }, { id: "code-review" }],
+    };
+    const factors = stackFactors(index, dir);
+    assert.equal(factors.get("cpp-testing"), 0.4);
+    assert.equal(factors.get("python-testing"), 1.3);
+    assert.equal(factors.has("code-review"), false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("combineFactors: multiplies overlapping ids, keeps non-overlapping ones", () => {
+  const a = new Map([["x", 2.0], ["y", 0.5]]);
+  const b = new Map([["x", 1.3]]);
+  const combined = combineFactors(a, b);
+  assert.equal(combined.get("x"), 2.6);
+  assert.equal(combined.get("y"), 0.5);
+});