pi-continual-harness 0.15.1 → 0.16.0

package/README.md

@@ -62,6 +62,7 @@ Durable I/O (round-trip with pi-reflect):
 
 ```
 /harness status                  # counts + durable layer presence/mtime
+/harness list [-f] [--kind <kind>] [--scope <global|project|all>]  # read items — compact rows, -f = full text + evidence
 /harness export [path]           # layered export (or full snapshot to a path)
 /harness export-corpus [path]    # calibration corpus JSONL for pi-reflex (local-only; dedupe pairs + lifecycle)
 /harness import [--prune] [path] # layered import (or single file from a path)
@@ -75,9 +76,9 @@ Durable I/O (round-trip with pi-reflect):
 /harness setup [--preset <quiet|recommended|power>] [--yes]  # guided config wizard
 ```
 
-Subcommands, flags, `--kind`/`--model`/`--from` values, `move` scopes, and
-`keep`/`drop`/`move` item ids all autocomplete in the TUI as you type after
-`/harness `.
+Subcommands, flags (`-f` included), `--kind`/`--model`/`--from`/`--scope`
+values, `move` scopes, and `keep`/`drop`/`move` item ids all autocomplete in
+the TUI as you type after `/harness `.
 
 **Durable layers.** Every item carries its own durable scope: `global`
 (the shared `~/.pi/agent/harness-state.md`) or `project`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-continual-harness",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "Online self-improvement layer for pi. A unified, in-trajectory harness-state store (prompt notes, memory, skill descriptions, sub-agent specs) with a manual /refine that proposes evidence-backed structured CRUD deltas. Composes with pi-reflect (offline) and pi-mem (storage); owns only the online optimizer layer. Inspired by Continual Harness (arXiv 2605.09998) and ACE (arXiv 2510.04618).",
   "keywords": [
     "pi-package",

package/src/harness.ts

@@ -1,6 +1,7 @@
 // /harness — durable I/O. The two-way round-trip seam with pi-reflect.
 //
 //   /harness status [path]               counts + durable layer presence/mtime
+//   /harness list [-f] [--kind] [--scope]  read items: compact rows, -f = full text
 //   /harness export [path]               layered export (or full snapshot to path)
 //   /harness import [--prune] [path]     layered import (or single file from path)
 //   /harness move <id> <global|project>  move an item between durable layers
@@ -59,6 +60,7 @@ import { buildCorpus } from "./corpus.js";
 import { buildStatusReport, renderStatusReport } from "./status.js";
 import { getInjectionStats } from "./inject.js";
 import { nextHint } from "./hints.js";
+import { preview, renderListReport, type ListScope } from "./list.js";
 import { handleSetup, PRESET_COMPLETIONS } from "./setup.js";
 
 /** One row of the /harness subcommand menu (label = name, value = name). */
@@ -72,6 +74,7 @@ const SUBCOMMANDS: CompletionEntry[] = [
   { name: "export", description: "Export active items to durable layers (or one file with a path)" },
   { name: "export-corpus", description: "Export calibration corpus JSONL for pi-reflex (dedupe pairs + lifecycle)" },
   { name: "status", description: "Show harness status (counts, audit-trail impact, injection stats, durable layers)" },
+  { name: "list", description: "Read items — compact rows, -f for full text (--kind/--scope filter)" },
   { name: "prune", description: "Decay & prune inactive items (--decay <days>)" },
   { name: "keep", description: "Bump item importance (+0.1)" },
   { name: "drop", description: "Lower item importance (−0.1)" },
@@ -84,6 +87,13 @@ const SUBCOMMANDS: CompletionEntry[] = [
 
 const KINDS: ComponentKind[] = ["prompt", "memory", "skill", "subagent"];
 
+/** `--scope` values /harness list offers (semantics in src/list.ts). */
+const LIST_SCOPES: Array<{ value: ListScope; description: string }> = [
+  { value: "global", description: "Global-scope items only (~/.pi/agent/harness-state.md)" },
+  { value: "project", description: "Project-scoped items (any project; rows carry the slug)" },
+  { value: "all", description: "Every item, foreign-project included" },
+];
+
 /** Flags each subcommand accepts, in menu order. */
 const FLAGS: Record<string, CompletionEntry[]> = {
   import: [{ name: "--prune", description: "Drop live items missing from the durable file" }],
@@ -97,17 +107,18 @@ const FLAGS: Record<string, CompletionEntry[]> = {
     { name: "--from", description: "Source model (provider/id) whose active items are up for adoption" },
     { name: "--all", description: "Adopt everything; skip the generalizes-vs-stays filter" },
   ],
+  list: [
+    { name: "-f", description: "Full item text + evidence instead of the compact preview rows" },
+    { name: "--kind", description: `Limit to one kind (${KINDS.join("|")})` },
+    { name: "--scope", description: "global | project | all (default: global + this project)" },
+  ],
   setup: [
     { name: "--preset", description: "Apply one preset: quiet | recommended | power" },
     { name: "--yes", description: "Scripted consent — skip every confirm prompt" },
   ],
 };
 
-function preview(text: string, max = 60): string {
-  // Single line + truncated so the menu row stays readable.
-  const flat = text.replace(/\s+/g, " ").trim();
-  return flat.length > max ? `${flat.slice(0, max)}…` : flat;
-}
+// preview() lives in src/list.ts (shared with /harness list rows).
 
 /**
  * Argument autocomplete for /harness (pi calls this with the FULL text after
@@ -141,7 +152,7 @@ function completions(argumentPrefix: string) {
   const sub = before[0]!.toLowerCase();
   // Flag-value completion: the token right before the one being typed.
   const prev = before.at(-1)!;
-  if (prev === "--kind" && sub === "push-mem") {
+  if (prev === "--kind" && (sub === "push-mem" || sub === "list")) {
     return filterValues(
       KINDS.map((k) => ({ value: k, description: KIND_LABEL[k] })),
       last,
@@ -162,6 +173,9 @@ function completions(argumentPrefix: string) {
   if (prev === "--preset" && sub === "setup") {
     return filterValues(PRESET_COMPLETIONS, last, before);
   }
+  if (prev === "--scope" && sub === "list") {
+    return filterValues(LIST_SCOPES, last, before);
+  }
   // --from completes from the model keys actually present in the store (the
   // adoption source pool), with each owner's active-item count as the help
   // line — the same store-backed completion style as --model above.
@@ -175,11 +189,12 @@ function completions(argumentPrefix: string) {
     );
   }
 
-  // Flag completion ("--…" prefix, or a fresh token for flag-taking subs).
-  // A fresh --kind/--model value was already completed above (early return),
-  // so a fresh token here means "offer the remaining flags".
-  if (last.startsWith("--") || (fresh && sub in FLAGS)) {
-    const used = new Set(before.filter((t) => t.startsWith("--")));
+  // Flag completion ("-…" prefix, or a fresh token for flag-taking subs —
+  // the "-" prefix also matches short flags like list's -f). A fresh
+  // --kind/--scope/--model value was already completed above (early
+  // return), so a fresh token here means "offer the remaining flags".
+  if (last.startsWith("-") || (fresh && sub in FLAGS)) {
+    const used = new Set(before.filter((t) => t.startsWith("-")));
     const rows = (FLAGS[sub] ?? []).filter((f) => !used.has(f.name));
     const items = rows
       .filter((f) => f.name.startsWith(last))
@@ -285,6 +300,9 @@ export function registerHarness(pi: ExtensionAPI): void {
         case "setup":
           await handleSetup(ctx, rest);
           return;
+        case "list":
+          await handleList(ctx, rest);
+          return;
         case "status":
         default:
           await handleStatus(ctx);
@@ -300,6 +318,59 @@ function explicitPath(rest: string[]): string | undefined {
   return rest.find((a) => !a.startsWith("-"));
 }
 
+/** `/harness list [-f] [--kind <kind>] [--scope <global|project|all>]`
+ *  (issue #31) — the read view: thin glue (flag parsing + one notify); every
+ *  selection/rendering rule lives in the pure src/list.ts. Read-only: no
+ *  store mutation, no durable writes. Invalid flag values AND unexpected
+ *  arguments warn instead of silently falling back — a filter that quietly
+ *  ignores its own argument would make the listing lie. */
+async function handleList(ctx: ExtensionCommandContext, rest: string[]): Promise<void> {
+  const full = rest.includes("-f");
+  let kind: ComponentKind | undefined;
+  const kindIdx = rest.indexOf("--kind");
+  if (kindIdx >= 0) {
+    const k = kindIdx + 1 < rest.length ? rest[kindIdx + 1]! : undefined;
+    if (!k || k.startsWith("-") || !KINDS.includes(k as ComponentKind)) {
+      ctx.ui.notify(`/harness list: --kind expects one of ${KINDS.join("|")}.`, "warning");
+      return;
+    }
+    kind = k as ComponentKind;
+  }
+  let scope: ListScope | undefined;
+  const scopeIdx = rest.indexOf("--scope");
+  if (scopeIdx >= 0) {
+    const s = scopeIdx + 1 < rest.length ? rest[scopeIdx + 1]! : undefined;
+    if (s !== "global" && s !== "project" && s !== "all") {
+      ctx.ui.notify("/harness list: --scope expects global|project|all.", "warning");
+      return;
+    }
+    scope = s;
+  }
+  // Unexpected arguments (unknown flags like --full, stray positionals,
+  // repeated flags) warn too — the same no-silent-fallback rule as invalid
+  // values. Anything but -f, --kind <value>, --scope <value> is refused.
+  const consumed = new Set<number>();
+  if (kindIdx >= 0) { consumed.add(kindIdx); consumed.add(kindIdx + 1); }
+  if (scopeIdx >= 0) { consumed.add(scopeIdx); consumed.add(scopeIdx + 1); }
+  const unexpected = rest.filter((t, idx) => t !== "-f" && !consumed.has(idx));
+  if (unexpected.length > 0) {
+    ctx.ui.notify(
+      `/harness list: unexpected argument(s): ${unexpected.join(" ")} — expected -f, --kind <kind>, --scope <global|project|all>.`,
+      "warning",
+    );
+    return;
+  }
+  ctx.ui.notify(
+    renderListReport(getState().items, {
+      ...(kind ? { kind } : {}),
+      ...(scope ? { scope } : {}),
+      ...(full ? { full } : {}),
+      slug: projectSlug(ctx.cwd),
+    }),
+    "info",
+  );
+}
+
 async function handleImport(
   pi: ExtensionAPI,
   ctx: ExtensionCommandContext,

package/src/index.ts

@@ -132,6 +132,17 @@ export {
 } from "./hints.js";
 export { getInjectionStats, resetInjectionStats, type InjectionStats } from "./inject.js";
 
+// /harness list (issue #31): pure selection + rendering for the read view of
+// the store (compact rows / full text + evidence). Re-exported for tests and
+// companions without reaching into internal paths.
+export {
+  preview,
+  renderListReport,
+  selectListItems,
+  type ListOptions,
+  type ListScope,
+} from "./list.js";
+
 // Injection selection policy (on by default). Re-exported so companion packages
 // and tests can reuse the pure selection/normalization without reaching into
 // internal paths.

package/src/list.ts

@@ -0,0 +1,157 @@
+// `/harness list` (issue #31) — the read view of the store. One compact row
+// per item (id, kind, importance, scope, preview) or, with `-f`, a
+// harness_list-style full text + evidence rendering (extended with the
+// scope). Read-only: selection
+// and rendering are pure; harness.ts's handleList stays thin glue (flag
+// parsing + one ctx.ui.notify).
+//
+// Scope semantics mirror the durable layers (issue #7): the default view is
+// the session's own layer set — global + the ACTIVE project — the same set
+// layered /harness import READS for this cwd (layered export writes more:
+// every project layer with active items, foreign included — store.ts).
+// Items scoped to a DIFFERENT project are hidden (and counted in a note,
+// listed or not) unless you ask for them:
+// `--scope project` lists every project-scoped item (rows carry the slug) and
+// `--scope all` lists everything. An item's undefined scope counts as global
+// (legacy snapshots / durable files — see types.ts).
+
+import type { ComponentKind, HarnessItem } from "./types.js";
+
+/** `--scope` values for /harness list. `undefined` (no flag) = the session's
+ *  layer set: global + the active project. */
+export type ListScope = "global" | "project" | "all";
+
+/** Options for selectListItems / renderListReport. */
+export interface ListOptions {
+  /** Filter by component kind (mirrors harness_list's kind parameter). */
+  kind?: ComponentKind;
+  /** Durable-scope filter; undefined = global + the active project. */
+  scope?: ListScope;
+  /** `-f`: full text + evidence per item (default: one compact row). */
+  full?: boolean;
+  /** The active project's slug (from the session cwd); selects the default
+   *  view and labels the header. */
+  slug: string;
+}
+
+/** Single-line, whitespace-flattened preview truncated to `max` chars — the
+ *  shared truncation style for one-line rows (menu entries, notifications). */
+export function preview(text: string, max = 60): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+}
+
+/** True when an item belongs to the durable layer(s) the options select. */
+function inScope(i: HarnessItem, opts: ListOptions): boolean {
+  switch (opts.scope) {
+    case "global":
+      return i.scope !== "project";
+    case "project":
+      return i.scope === "project";
+    case "all":
+      return true;
+    default:
+      // Session layer set: global + the active project (undefined scope is
+      // global; a project item only shows when its slug is the active one).
+      return i.scope !== "project" || i.project === opts.slug;
+  }
+}
+
+/** Select the listable items: kind filter, scope filter, then importance
+ *  desc with ties keeping store order — the same stable ranking policy as
+ *  injection selection and /harness adopt. Pure. */
+export function selectListItems(items: HarnessItem[], opts: ListOptions): HarnessItem[] {
+  return items
+    .filter((i) => (opts.kind ? i.kind === opts.kind : true) && inScope(i, opts))
+    .map((i, idx) => [i, idx] as const)
+    .sort((a, b) => b[0].importance - a[0].importance || a[1] - b[1])
+    .map(([i]) => i);
+}
+
+/** Compact row: `[id] kind importance scope preview` (issue #31's table);
+ *  inactive items carry an `(inactive)` marker so the row stays one line. */
+function row(i: HarnessItem): string {
+  const scope = i.scope === "project" ? `project:${i.project ?? "?"}` : "global";
+  return `[${i.id}] ${i.kind.padEnd(8)} ${i.importance.toFixed(2)} ${scope} ${
+    i.active ? "" : "(inactive) "
+  }${preview(i.content)}`;
+}
+
+/** Full row (`-f`): the harness_list rendering, scope-aware — the same
+ *  parenthetical the split/adopt prompts use, plus the evidence line. */
+function fullRow(i: HarnessItem): string {
+  const bits = [
+    i.kind,
+    `importance ${i.importance.toFixed(2)}`,
+    i.active ? "active" : "inactive",
+    `model ${i.ownerModel || "(orphan)"}`,
+    i.scope === "project" ? `project "${i.project ?? ""}"` : "global",
+  ];
+  return `[${i.id}] (${bits.join(", ")}) ${i.content}\n  evidence: ${i.evidence}`;
+}
+
+/** Tally `items` by a string key, rendered as "key (n), key (n)". */
+function tally<T>(items: T[], key: (i: T) => string): string {
+  const counts = new Map<string, number>();
+  for (const i of items) counts.set(key(i), (counts.get(key(i)) ?? 0) + 1);
+  return [...counts.entries()].map(([k, n]) => `${k} (${n})`).join(", ");
+}
+
+function scopeDescription(opts: ListOptions): string {
+  switch (opts.scope) {
+    case "global":
+      return "scope global";
+    case "project":
+      return 'scope project (any project\'s items; rows carry the slug)';
+    case "all":
+      return "scope all";
+    default:
+      return `scope global + project "${opts.slug}"`;
+  }
+}
+
+/** Render the whole `/harness list` notify string: header (count + active
+ *  filters), rows (compact by default, full text + evidence with `full`),
+ *  and distinct empty-state guidance for an empty store vs an empty filter
+ *  result (the emptyListMessage lesson: never collapse the two). Pure. */
+export function renderListReport(items: HarnessItem[], opts: ListOptions): string {
+  const shown = selectListItems(items, opts);
+  const header =
+    `Harness list: ${shown.length} item(s) — ${scopeDescription(opts)}` +
+    (opts.kind ? `, kind ${opts.kind}` : "") +
+    ` (${opts.full ? "full text" : "compact; -f for full text"}).`;
+  // The default view hides foreign-project items on purpose (they are not
+  // this session's layers) — say so instead of letting them look missing.
+  // Computed ONCE so the note rides along on every non-empty-store result,
+  // empty filter results included (a foreign-only store still gets it).
+  let foreignNote: string | undefined;
+  if (opts.scope === undefined) {
+    const foreign = items.filter(
+      (i) => i.scope === "project" && i.project !== opts.slug && (opts.kind ? i.kind === opts.kind : true),
+    ).length;
+    if (foreign > 0) {
+      foreignNote = `+ ${foreign} foreign-project item(s) hidden — re-run with --scope all to see them.`;
+    }
+  }
+  if (shown.length === 0) {
+    if (items.length === 0) {
+      return [
+        header,
+        "No harness items yet. Run `/refine` after a working session (or `/harness import`) — items appear here as they are created.",
+      ].join("\n");
+    }
+    // A store whose matching items are ALL foreign must not collapse into
+    // generic filter guidance: the hidden note explains where they went
+    // (review #32) — the default view hides them, no filter removed them.
+    // (No flag echo here: the header already names scope+kind, and a
+    // pseudo-flag like `--scope global+project` would not even parse.)
+    return [
+      header,
+      `Nothing matches the current filters. The store holds ${items.length} item(s): ${tally(items, (i) => i.kind)}. Widen --scope or drop --kind.`,
+      ...(foreignNote ? [foreignNote] : []),
+    ].join("\n");
+  }
+  const lines = [header, ...shown.map(opts.full ? fullRow : row)];
+  if (foreignNote) lines.push(foreignNote);
+  return lines.join("\n");
+}

package/src/tools.ts

@@ -88,7 +88,7 @@ export function registerTools(pi: ExtensionAPI): void {
     name: "harness_list",
     label: "List harness state",
     description:
-      "List items in the Continual Harness state (self-improved prompt notes, memory, skill descriptions, sub-agent specs). Optionally filter by kind.",
+      "List items in the Continual Harness state (self-improved prompt notes, memory, skill descriptions, sub-agent specs). Optionally filter by kind. (/harness list is the human-facing TUI view: compact rows + durable-scope filters.)",
     promptSnippet: "Read Continual Harness self-improvement state",
     promptGuidelines: [
       "Call harness_list before proposing changes so you operate on current state.",