@kontourai/flow-agents 2.4.0 → 3.1.0

package/kits/knowledge/providers/work-item/index.js

@@ -0,0 +1,204 @@
+/**
+ * work-item knowledge-store provider (source/sink adapter, not storage).
+ *
+ * Maps a GitHub issue backlog into the typed graph so backlog hygiene becomes a
+ * knowledge-health pass:
+ *   - issues                         -> `issue` nodes (state / labels / title).
+ *   - flow-agents:work-item-metadata `blockers` -> `blocks` edges.
+ *   - prose "blocked by #N"          -> `blocks` edges; other #N refs -> `relates`.
+ *
+ * Reads via an INJECTABLE runner so tests drive it from recorded fixtures and
+ * never touch the real board. Write side is proposals-only: proposeWrite renders
+ * a draft issue comment / label change for an operator to file — it never calls
+ * a mutating gh command.
+ *
+ * @module providers/work-item
+ */
+
+import { execFile } from "node:child_process";
+import { node, edge, proposal, provenance } from "../lib/model.js";
+
+const PROVIDER_ID = "work-item";
+
+/** Default runner: shells out to `gh` (read-only list). */
+function defaultRunner(args) {
+  return new Promise((resolve, reject) => {
+    execFile("gh", args, { maxBuffer: 32 * 1024 * 1024 }, (err, stdout, stderr) => {
+      if (err) return reject(new Error(`gh ${args.join(" ")} failed: ${stderr || err.message}`));
+      resolve(stdout);
+    });
+  });
+}
+
+/** Parse the flow-agents:work-item-metadata JSON block from an issue body. */
+export function parseWorkItemMetadata(body) {
+  if (!body) return null;
+  const start = body.indexOf("flow-agents:work-item-metadata");
+  if (start === -1) return null;
+  const jsonStart = body.indexOf("{", start);
+  const end = body.indexOf("-->", jsonStart);
+  if (jsonStart === -1 || end === -1) return null;
+  try {
+    return JSON.parse(body.slice(jsonStart, end).trim());
+  } catch {
+    return null;
+  }
+}
+
+/** Extract a blocker issue number from a metadata blocker entry. */
+function blockerNumber(entry) {
+  if (typeof entry === "number") return entry;
+  if (typeof entry === "string") {
+    const m = entry.match(/#?(\d+)/);
+    return m ? Number(m[1]) : null;
+  }
+  if (entry && typeof entry === "object") {
+    if (typeof entry.number === "number") return entry.number;
+    if (typeof entry.issue === "number") return entry.issue;
+    if (typeof entry.ref === "string") {
+      const m = entry.ref.match(/#?(\d+)/);
+      return m ? Number(m[1]) : null;
+    }
+  }
+  return null;
+}
+
+export class WorkItemProvider {
+  constructor({ repo, runner, agent } = {}) {
+    this.repo = repo || "";
+    this.runner = runner || defaultRunner;
+    this.agent = agent;
+    this.id = PROVIDER_ID;
+    this._cache = null;
+  }
+
+  capabilities() {
+    return {
+      id: PROVIDER_ID,
+      node_types: ["issue"],
+      edge_types: ["blocks", "relates"],
+      writable: false,
+      write_mode: "proposals-only",
+      proposal_targets: ["comment", "label"],
+      source_of_truth: "GitHub issues (read via gh; write = draft comments/labels)",
+    };
+  }
+
+  async _issues() {
+    if (this._cache) return this._cache;
+    const args = ["issue", "list"];
+    if (this.repo) args.push("--repo", this.repo);
+    args.push("--state", "all", "--json", "number,title,state,labels,body", "--limit", "200");
+    const out = await this.runner(args);
+    const parsed = JSON.parse(out);
+    this._cache = Array.isArray(parsed) ? parsed : [];
+    return this._cache;
+  }
+
+  async readNodes(options = {}) {
+    const issues = await this._issues();
+    const now = new Date().toISOString();
+    const nodes = issues.map((iss) =>
+      node({
+        id: `issue:${iss.number}`,
+        type: "issue",
+        title: iss.title || `issue #${iss.number}`,
+        body: iss.body || "",
+        attributes: {
+          number: iss.number,
+          state: iss.state || "OPEN",
+          labels: (iss.labels || []).map((l) => (typeof l === "string" ? l : l.name)),
+        },
+        provenance: provenance({
+          provider: PROVIDER_ID,
+          source: this.repo ? `${this.repo}#${iss.number}` : `#${iss.number}`,
+          retrievedAt: now,
+          agent: this.agent,
+        }),
+      }),
+    );
+    if (options.type) return nodes.filter((n) => n.type === options.type);
+    return nodes;
+  }
+
+  async readEdges() {
+    const issues = await this._issues();
+    const now = new Date().toISOString();
+    const edges = [];
+    const seen = new Set();
+    const push = (e) => {
+      if (seen.has(e.id)) return;
+      seen.add(e.id);
+      edges.push(e);
+    };
+
+    for (const iss of issues) {
+      const self = `issue:${iss.number}`;
+      const prov = (loc) => provenance({ provider: PROVIDER_ID, source: this.repo ? `${this.repo}#${iss.number}` : `#${iss.number}`, locator: loc, retrievedAt: now, agent: this.agent });
+
+      // metadata blockers -> blocks (blocker blocks this)
+      const md = parseWorkItemMetadata(iss.body);
+      for (const b of (md && Array.isArray(md.blockers) ? md.blockers : [])) {
+        const n = blockerNumber(b);
+        if (n == null) continue;
+        push(edge({ id: `issue:${n}--blocks--${iss.number}`, type: "blocks", from: `issue:${n}`, to: self, attributes: { origin: "metadata" }, provenance: prov("metadata.blockers") }));
+      }
+
+      const body = iss.body || "";
+      // prose "blocked by #N" / "depends on #N" -> blocks
+      for (const m of body.matchAll(/\b(?:blocked by|depends on|blocker:)\s*#(\d+)/gi)) {
+        const n = Number(m[1]);
+        push(edge({ id: `issue:${n}--blocks--${iss.number}`, type: "blocks", from: `issue:${n}`, to: self, attributes: { origin: "prose" }, provenance: prov("body.prose") }));
+      }
+      // other bare #N prose refs -> relates
+      for (const m of body.matchAll(/(?<![\w/])#(\d+)\b/g)) {
+        const n = Number(m[1]);
+        if (n === iss.number) continue;
+        const bid = `issue:${iss.number}--relates--${n}`;
+        if (seen.has(`issue:${n}--blocks--${iss.number}`)) continue; // already a stronger blocks edge
+        push(edge({ id: bid, type: "relates", from: self, to: `issue:${n}`, attributes: { origin: "prose" }, provenance: prov("body.prose") }));
+      }
+    }
+    return edges;
+  }
+
+  async queryByType(type) {
+    return this.readNodes({ type });
+  }
+
+  async readGraph() {
+    const [nodes, edges] = await Promise.all([this.readNodes(), this.readEdges()]);
+    return { nodes, edges };
+  }
+
+  /**
+   * Propose an issue comment or label change. Renders the draft an operator
+   * would file with gh — the provider never runs a mutating gh command.
+   */
+  async proposeWrite(intent = {}) {
+    const { issue, kind = "comment", commentBody, labels = [] } = intent;
+    if (issue == null) throw new Error("work-item proposeWrite requires intent.issue (number)");
+    if (kind === "label") {
+      return proposal({
+        provider: PROVIDER_ID,
+        kind: "label",
+        target: { repo: this.repo, issue },
+        payload: { labels },
+        rendered: `gh issue edit ${issue}${this.repo ? ` --repo ${this.repo}` : ""} ${labels.map((l) => `--add-label ${JSON.stringify(l)}`).join(" ")}`,
+        rationale: intent.rationale || "Proposed label change (draft — operator files it).",
+        provenance: provenance({ provider: PROVIDER_ID, source: this.repo ? `${this.repo}#${issue}` : `#${issue}`, agent: this.agent }),
+      });
+    }
+    return proposal({
+      provider: PROVIDER_ID,
+      kind: "comment",
+      target: { repo: this.repo, issue },
+      payload: { body: commentBody || "" },
+      rendered: `gh issue comment ${issue}${this.repo ? ` --repo ${this.repo}` : ""} --body ${JSON.stringify(commentBody || "")}`,
+      rationale: intent.rationale || "Proposed issue comment (draft — operator files it).",
+      provenance: provenance({ provider: PROVIDER_ID, source: this.repo ? `${this.repo}#${issue}` : `#${issue}`, agent: this.agent }),
+    });
+  }
+}
+
+export default WorkItemProvider;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "2.4.0",
+  "version": "3.1.0",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",
@@ -110,6 +110,8 @@
     "workflow:sidecar": "npm run build --silent && node build/src/cli/workflow-sidecar.js",
     "workflow:validate-artifacts": "npm run build --silent && node build/src/cli/validate-workflow-artifacts.js",
     "effective-backlog-settings": "npm run build --silent && node build/src/cli.js effective-backlog-settings",
+    "assignment-provider": "npm run build --silent && node build/src/cli.js assignment-provider",
+    "effective-assignment-provider-settings": "npm run build --silent && node build/src/cli.js effective-assignment-provider-settings",
     "pull-work-provider": "npm run build --silent && node build/src/cli.js pull-work-provider",
     "publish-change": "npm run build --silent && node build/src/cli.js publish-change",
     "promote-workflow-artifact": "npm run build --silent && node build/src/cli.js promote-workflow-artifact",
@@ -137,11 +139,12 @@
     "check:content-boundary": "node scripts/check-content-boundary.cjs",
     "check:decisions": "node scripts/check-decisions.cjs check",
     "gen:decisions-index": "node scripts/check-decisions.cjs gen-index",
+    "freeze:adrs": "node scripts/freeze-adrs.mjs",
     "prepack": "npm run build --silent && npm run validate:source --",
     "kit": "npm run build --silent && node build/src/cli.js kit"
   },
   "devDependencies": {
-    "@types/node": "^26.0.1",
+    "@types/node": "^26.1.0",
     "promptfoo": "^0.121.17",
     "typescript": "^6.0.3"
   },
@@ -150,6 +153,7 @@
   },
   "optionalDependencies": {
     "@kontourai/surface": "^2.0.0",
-    "hachure": "^0.9.0"
+    "hachure": "^0.9.0",
+    "neo4j-driver": "^5.28.0"
   }
 }

package/schemas/assignment-provider-settings.schema.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flow-agents.dev/schemas/assignment-provider-settings.schema.json",
+  "title": "Flow Agents Assignment Provider Settings",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schema_version": { "const": "1.0" },
+    "defaults": { "$ref": "#/$defs/assignment_settings" },
+    "projects": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/project_assignment_settings" }
+    }
+  },
+  "anyOf": [{ "required": ["defaults"] }, { "required": ["projects"] }],
+  "$defs": {
+    "project_assignment_settings": {
+      "allOf": [
+        { "$ref": "#/$defs/assignment_settings" },
+        { "type": "object", "required": ["project"] }
+      ]
+    },
+    "assignment_settings": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "policy"],
+      "properties": {
+        "project": { "$ref": "#/$defs/project_match" },
+        "provider": { "$ref": "#/$defs/provider" },
+        "policy": { "$ref": "#/$defs/policy" }
+      }
+    },
+    "project_match": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repo"],
+      "properties": {
+        "repo": { "$ref": "#/$defs/repo" },
+        "paths": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "provider": {
+      "oneOf": [
+        { "$ref": "#/$defs/github_provider" },
+        { "$ref": "#/$defs/local_file_provider" }
+      ]
+    },
+    "github_provider": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "repo", "capabilities"],
+      "properties": {
+        "kind": { "const": "github" },
+        "repo": { "$ref": "#/$defs/repo" },
+        "capabilities": { "$ref": "#/$defs/capabilities" }
+      }
+    },
+    "local_file_provider": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "capabilities"],
+      "properties": {
+        "kind": { "const": "local-file" },
+        "capabilities": { "$ref": "#/$defs/capabilities" }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["label_name", "claim_comment_marker", "human_assignee_policy"],
+      "properties": {
+        "label_name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Label attached to a claimed subject on providers that support labels. Default: \"agent:claimed\"."
+        },
+        "claim_comment_marker": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Fixed marker used to locate the machine-readable claim comment among human comments. Default: \"<!-- flow-agents:assignment-claim -->\"."
+        },
+        "human_assignee_policy": { "$ref": "#/$defs/human_assignee_policy" },
+        "comment_refresh_on_phase_transition": {
+          "type": "boolean",
+          "description": "Whether an explicit render-claim/render-supersede call at a phase transition also refreshes the claim comment body. Default: false. No new mechanism; this reuses the same render path already built for claim."
+        }
+      }
+    },
+    "human_assignee_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["behavior", "idle_threshold_days"],
+      "properties": {
+        "behavior": {
+          "enum": ["ask_first", "never_reclaim"],
+          "description": "Default: \"ask_first\". A human assignee is never auto-superseded regardless of this value; this knob only governs whether idle human assignments are ever surfaced for possible reclaim confirmation (ask_first) or left untouched (never_reclaim)."
+        },
+        "idle_threshold_days": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Days of no linked activity before an idle human assignment is surfaced for confirmation. Default: 3."
+        }
+      }
+    },
+    "capabilities": {
+      "type": "array",
+      "items": {
+        "enum": ["assignees", "labels", "comments"]
+      },
+      "uniqueItems": true
+    },
+    "repo": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["owner", "name"],
+      "properties": {
+        "owner": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "url": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/knowledge/edge.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://flow-agents.dev/schemas/knowledge/edge.schema.json",
+  "title": "Knowledge Graph Edge",
+  "description": "A typed, directed edge between two nodes. The edge-type vocabulary is CLOSED (unlike node types): supersedes, merged-into, blocks, evidence-of, mentions, relates. Every edge carries provenance. The `to` endpoint MAY reference a node that is not present in the graph (an external or dangling reference); `resolved` records whether the provider expects the target to resolve, which the dependency-link-integrity health verb uses to separate deliberate external refs from broken links.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "from", "to", "provenance"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Provider-scoped stable identifier for the edge."
+    },
+    "type": {
+      "type": "string",
+      "enum": ["supersedes", "merged-into", "blocks", "evidence-of", "mentions", "relates"],
+      "description": "supersedes: from replaces to. merged-into: from was folded into to. blocks: from must complete before to. evidence-of: from is provenance/evidence for to. mentions: from references to in prose. relates: general undirected-ish association."
+    },
+    "from": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Source node id."
+    },
+    "to": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Target node id. MAY be a node id not present in the graph when `resolved` is false (external ref)."
+    },
+    "resolved": {
+      "type": "boolean",
+      "description": "true (default when omitted) means the provider expects `to` to resolve to a node in the same graph; a missing target is then a broken link. false means `to` is a deliberate external reference (e.g. evidence-of a PR outside the store) and MUST NOT be flagged as broken."
+    },
+    "attributes": {
+      "type": "object",
+      "description": "Provider-specific structured fields for the edge."
+    },
+    "provenance": { "$ref": "#/$defs/provenance" }
+  },
+  "$defs": {
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "source", "retrieved_at"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "locator": { "type": "string" },
+        "retrieved_at": { "type": "string", "minLength": 1 },
+        "agent": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/knowledge/health-report.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://flow-agents.dev/schemas/knowledge/health-report.schema.json",
+  "title": "Knowledge Health Report",
+  "description": "The schema-valid output of a provider-agnostic health verb (duplicate detection, dependency-link integrity). The same report shape is produced regardless of which provider supplied the graph, which is what lets one health command run identically over vault, git-repo, and work-item.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "check", "provider", "generated_at", "summary", "findings"],
+  "properties": {
+    "schema_version": { "const": "1.0" },
+    "check": {
+      "type": "string",
+      "enum": ["duplicate-detection", "dependency-link-integrity"],
+      "description": "Which health verb produced the report."
+    },
+    "provider": { "type": "string", "minLength": 1, "description": "Provider id the graph was read from." },
+    "generated_at": { "type": "string", "minLength": 1 },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["nodes_examined", "edges_examined", "finding_count"],
+      "properties": {
+        "nodes_examined": { "type": "integer" },
+        "edges_examined": { "type": "integer" },
+        "finding_count": { "type": "integer" }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "severity", "message", "evidence"],
+        "properties": {
+          "kind": { "type": "string", "minLength": 1 },
+          "severity": { "type": "string", "enum": ["info", "warning", "error"] },
+          "node_ids": { "type": "array", "items": { "type": "string" } },
+          "edge_ids": { "type": "array", "items": { "type": "string" } },
+          "message": { "type": "string", "minLength": 1 },
+          "evidence": { "type": "object" }
+        }
+      }
+    }
+  }
+}

package/schemas/knowledge/node.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://flow-agents.dev/schemas/knowledge/node.schema.json",
+  "title": "Knowledge Graph Node",
+  "description": "A typed node in the Knowledge Kit graph model. type is EXTENSIBLE: the recommended core vocabulary is note, decision, issue, session, person, but providers MAY emit additional types. Every node carries provenance so any assertion can be traced back to the store it came from.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "type", "title", "provenance"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Provider-scoped stable identifier, unique within a single readGraph result."
+    },
+    "type": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Node type. Recommended core vocabulary: note, decision, issue, session, person. Extensible — unknown types MUST NOT be rejected."
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable title used for display and duplicate detection."
+    },
+    "body": {
+      "type": "string",
+      "description": "Primary content. Format is provider/type-specific."
+    },
+    "attributes": {
+      "type": "object",
+      "description": "Provider-specific structured fields (e.g. issue state/labels, decision status, note category/tags)."
+    },
+    "provenance": { "$ref": "#/$defs/provenance" }
+  },
+  "$defs": {
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "source", "retrieved_at"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1, "description": "Provider id that produced this element (e.g. markdown-vault, git-repo, work-item)." },
+        "source": { "type": "string", "minLength": 1, "description": "The concrete origin: a file path, an issue ref, or a URL." },
+        "locator": { "type": "string", "description": "Optional finer locator within the source (line, anchor, frontmatter field)." },
+        "retrieved_at": { "type": "string", "minLength": 1, "description": "ISO-8601 timestamp the element was read." },
+        "agent": { "type": "string", "description": "Optional agent/process id that performed the read." }
+      }
+    }
+  }
+}

package/schemas/knowledge/proposal.schema.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://flow-agents.dev/schemas/knowledge/proposal.schema.json",
+  "title": "Knowledge Store Write Proposal",
+  "description": "The ONLY write artifact a knowledge store provider may emit. Providers over human-curated stores are proposals-only: proposeWrite() never mutates the store and can only ever return a Proposal whose status is the const \"proposed\". Enactment happens downstream (a human edit, the decision-registry promote step, or a gh comment/label the operator files) — never inside the provider. The `rendered` field carries the provider-native form the enactor would apply (decision-registry topic frontmatter for git-repo; an issue comment/label body for work-item; a vault note with frontmatter+wikilinks for markdown-vault).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "provider", "kind", "target", "status", "provenance"],
+  "properties": {
+    "schema_version": { "const": "1.0" },
+    "provider": { "type": "string", "minLength": 1 },
+    "kind": {
+      "type": "string",
+      "enum": ["create-node", "update-node", "add-edge", "comment", "label", "decision-topic"],
+      "description": "The shape of the proposed change."
+    },
+    "target": {
+      "type": "object",
+      "description": "Where the change would land if enacted (file path, issue number, store id). Descriptive only — the provider does not touch it."
+    },
+    "payload": {
+      "type": "object",
+      "description": "The structured node/edge/field the proposal would introduce."
+    },
+    "rendered": {
+      "type": "string",
+      "description": "The provider-native rendered form an enactor would apply (topic-file frontmatter, gh comment body, vault note)."
+    },
+    "status": {
+      "const": "proposed",
+      "description": "Always the literal \"proposed\". A provider can NEVER return an applied proposal — this const is the structural expression of proposals-only discipline."
+    },
+    "rationale": {
+      "type": "string",
+      "description": "Why the change is proposed."
+    },
+    "provenance": { "$ref": "#/$defs/provenance" }
+  },
+  "$defs": {
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["provider", "source", "retrieved_at"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "locator": { "type": "string" },
+        "retrieved_at": { "type": "string", "minLength": 1 },
+        "agent": { "type": "string" }
+      }
+    }
+  }
+}

package/scripts/README.md

@@ -70,6 +70,7 @@ renamed, or changes category, update the table and the validator together.
 | `lib/actor-identity.js` | shared hook library | `evals/integration/test_actor_identity.sh` | Shared runtime-agnostic actor identity resolver (`resolveActor`) consumed by `workflow-steering.js` and `workflow-sidecar.js` to retire the shared `"local"` liveness-actor default (issue #287). |
 | `lib/audit-transport.sh` | shared hook library | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Shared audit event transport functions. |
 | `lib/config-protection-remedies.js` | shared hook library | `evals/integration/test_hook_category_behaviors.sh` | Sanctioned-remedy table for `config-protection.js` (WS8/ADR 0020 extraction). |
+| `lib/current-pointer.js` | shared hook library | `evals/integration/test_current_json_per_actor.sh` | Shared per-actor "current" pointer reader/writer (`readCurrentPointer`, `writePerActorCurrent`) — the compat-shim fallback (per-actor `current/<actor>.json` first, legacy global `current.json` fallback) every actor-aware consumer routes through (issue #291). |
 | `lib/hook-flags.js` | shared hook library | `evals/integration/test_hook_category_behaviors.sh` | Shared profile/disable flag parsing. |
 | `lib/liveness-heartbeat.js` | shared hook library | `evals/integration/test_liveness_heartbeat.sh` | Shared tool-activity liveness heartbeat (`maybeEmitHeartbeat`); rides `postToolUse` across all four telemetry hook wrappers, throttled and fail-open (issue #288). |
 | `lib/liveness-policy.js` | shared hook library | `evals/integration/test_workflow_sidecar_writer.sh`, `evals/integration/test_liveness_heartbeat.sh` | Shared liveness on/off predicate (`isLivenessEnabled`, default-on/opt-out) and TTL/heartbeat-throttle default resolution (issue #288). |