@forwardimpact/libwiki 0.2.30 → 0.2.32

package/README.md

@@ -2,8 +2,9 @@
 
 <!-- BEGIN:description — Do not edit. Generated from package.json. -->
 
-Wiki lifecycle primitives — stable memory for agent teams so coordination
-persists across sessions.
+Wiki lifecycle for agent teams — persistent memory, declarative integrity
+audits, and a collision ledger so coordination survives across sessions and
+parallel work.
 
 <!-- END:description -->
 
@@ -157,3 +158,5 @@ import {
 
 - [Operate a Predictable Agent Team](https://www.forwardimpact.team/docs/libraries/predictable-team/index.md)
 - [Send a Memo or Update a Storyboard](https://www.forwardimpact.team/docs/libraries/predictable-team/wiki-operations/index.md)
+- [Audit and Auto-Fix the Wiki](https://www.forwardimpact.team/docs/libraries/predictable-team/wiki-integrity/index.md)
+- [Allocate Collision-Ledger Entries for Parallel Work](https://www.forwardimpact.team/docs/libraries/predictable-team/collision-ledger/index.md)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@forwardimpact/libwiki",
-  "version": "0.2.30",
-  "description": "Wiki lifecycle primitives — stable memory for agent teams so coordination persists across sessions.",
+  "version": "0.2.32",
+  "description": "Wiki lifecycle for agent teams — persistent memory, declarative integrity audits, and a collision ledger so coordination survives across sessions and parallel work.",
   "keywords": [
     "wiki",
     "memo",
@@ -23,7 +23,7 @@
       "goal": "Operate a Predictable Agent Team",
       "trigger": "An agent finishes a session and its findings vanish because there is no shared memory to write them to.",
       "bigHire": "give agent teams stable memory that persists across sessions.",
-      "littleHire": "send a memo or update a storyboard without managing the wiki infrastructure.",
+      "littleHire": "send a memo, run an integrity audit, or refresh a storyboard without managing the wiki infrastructure.",
       "competesWith": "git commit messages as memory; ephemeral conversation context; starting every session from scratch"
     }
   ],
@@ -47,7 +47,7 @@
   "dependencies": {
     "@forwardimpact/libcli": "^0.1.0",
     "@forwardimpact/libconfig": "^0.1.77",
-    "@forwardimpact/libeval": "^0.1.49",
+    "@forwardimpact/libharness": "^1.0.0",
     "@forwardimpact/libpreflight": "^0.1.0",
     "@forwardimpact/libtelemetry": "^0.1.47",
     "@forwardimpact/libutil": "^0.1.0",

package/src/cli-definition.js

@@ -9,6 +9,7 @@ import { runClaimCommand, runReleaseCommand } from "./commands/claim.js";
 import { runInboxCommand } from "./commands/inbox.js";
 import { runRotateCommand } from "./commands/rotate.js";
 import { runAuditCommand } from "./commands/audit.js";
+import { runCurateCommand } from "./commands/curate.js";
 import { runFixCommand } from "./commands/fix.js";
 import { runLedgerCommand } from "./commands/ledger.js";
 
@@ -174,6 +175,25 @@ export function createDefinition() {
           },
         },
       },
+      {
+        name: "curate",
+        description:
+          "Audit the shared wiki and route any findings to the single wiki-curation issue (create or comment), addressed to the technical-writer",
+        handler: runCurateCommand,
+        options: {
+          ...wikiRootOpt,
+          ...todayOpt,
+          repo: {
+            type: "string",
+            description: "owner/repo slug (default: origin remote)",
+          },
+          "dry-run": {
+            type: "boolean",
+            description:
+              "Print the issue body and intended action without calling gh",
+          },
+        },
+      },
       {
         name: "fix",
         description:
@@ -335,6 +355,7 @@ export function createDefinition() {
       "fit-wiki inbox list --agent staff-engineer",
       "fit-wiki rotate --agent staff-engineer",
       "fit-wiki audit",
+      "fit-wiki curate",
       "fit-wiki fix",
       'fit-wiki memo --from staff-engineer --to security-engineer --message "audit d642ff0c"',
       "fit-wiki refresh",
@@ -354,7 +375,19 @@ export function createDefinition() {
         title: "Send a Memo or Update a Storyboard",
         url: "https://www.forwardimpact.team/docs/libraries/predictable-team/wiki-operations/index.md",
         description:
-          "Send cross-team memos, refresh storyboard charts, and sync the wiki.",
+          "Send cross-team memos, refresh storyboard charts, sync the wiki, and record the product-mix metric.",
+      },
+      {
+        title: "Audit and Auto-Fix the Wiki",
+        url: "https://www.forwardimpact.team/docs/libraries/predictable-team/wiki-integrity/index.md",
+        description:
+          "Check the wiki against the rule catalogue, auto-fix what is safe, and flag the rest for a human.",
+      },
+      {
+        title: "Allocate Collision-Ledger Entries for Parallel Work",
+        url: "https://www.forwardimpact.team/docs/libraries/predictable-team/collision-ledger/index.md",
+        description:
+          "Assign stable, collision-free ids to parallel work and rebuild the ledger projections.",
       },
     ],
   };

package/src/commands/audit.js

@@ -9,8 +9,14 @@ import { buildContext, resolveScope } from "../audit/scopes.js";
 import { currentDayIso } from "../util/clock.js";
 import { resolveProjectRoot } from "../util/wiki-dir.js";
 
-/** Run the wiki audit and emit findings. JSON via --format json. */
-export function runAuditCommand(ctx) {
+/**
+ * Run the wiki audit and return its findings plus the resolved project root.
+ * Shared by `runAuditCommand` (emits them) and `runCurateCommand` (routes
+ * them to an issue) so the two cannot drift.
+ * @param {import("@forwardimpact/libcli").InvocationContext} ctx
+ * @returns {{ findings: object[], projectRoot: string }}
+ */
+export function auditWiki(ctx) {
   const { runtime } = ctx.deps;
   const options = ctx.options;
   const projectRoot = resolveProjectRoot(runtime);
@@ -23,7 +29,14 @@ export function runAuditCommand(ctx) {
     fs: runtime.fsSync,
     subprocess: runtime.subprocess,
   });
-  const findings = runRules(RULES, auditCtx, { resolveScope });
+  return { findings: runRules(RULES, auditCtx, { resolveScope }), projectRoot };
+}
+
+/** Run the wiki audit and emit findings. JSON via --format json. */
+export function runAuditCommand(ctx) {
+  const { runtime } = ctx.deps;
+  const options = ctx.options;
+  const { findings, projectRoot } = auditWiki(ctx);
 
   runtime.proc.stdout.write(
     options.format === "json"

package/src/commands/curate.js

@@ -0,0 +1,185 @@
+import path from "node:path";
+import { emitFindingsJson } from "@forwardimpact/libutil";
+import { createLogger } from "@forwardimpact/libtelemetry";
+import { createScriptConfig } from "@forwardimpact/libconfig";
+import { parseRepoSlug } from "../issue-list-renderer.js";
+import { resolveProjectRoot } from "../util/wiki-dir.js";
+import { auditWiki } from "./audit.js";
+
+// The routing contract: a single open issue, addressed to the technical-writer,
+// holding the audit findings. The title is matched verbatim on every run so a
+// dirty wiki appends to one issue rather than opening a new one each day.
+const LABEL = {
+  name: "wiki-curation",
+  color: "BFD4F2",
+  description: "Shared-wiki audit findings from scheduled curation",
+};
+const TITLE = "Wiki curation: shared-state audit findings";
+
+/**
+ * Compose the issue body from the audit's JSON findings. The findings ride a
+ * fenced ```json block; the body is passed to `gh` via `--body-file` (a temp
+ * file), never argv, so untrusted finding text cannot be misread as a flag.
+ * @param {string} findingsJson
+ * @returns {string}
+ */
+function buildBody(findingsJson) {
+  return [
+    "Scheduled `curate-wiki` audit found shared-wiki violations.",
+    "",
+    "Owner: **technical-writer** (service these via the curation shift; the per-PR `wiki` gate no longer reads shared wiki state).",
+    "",
+    "```json",
+    findingsJson,
+    "```",
+    "",
+  ].join("\n");
+}
+
+// Resolve the monorepo's `owner/repo` slug the way refresh.js/product-mix.js
+// do: an explicit FIT_GH_REPO override (sandbox proxy URLs), else the origin
+// remote parsed via the injected git client. Null lets `gh` fall back to its
+// own cwd resolution.
+async function deriveRepo(gitClient, cwd, env) {
+  if (env.FIT_GH_REPO) return env.FIT_GH_REPO;
+  if (!gitClient) return null;
+  try {
+    return parseRepoSlug(await gitClient.remoteGetUrl("origin", { cwd }));
+  } catch {
+    return null;
+  }
+}
+
+// A missing token is non-fatal: `gh` may still resolve ambient auth.
+async function resolveToken() {
+  try {
+    return (await createScriptConfig("wiki")).ghToken();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Audit the shared wiki and, when it is dirty, route the findings to the
+ * single `wiki-curation` issue (create or comment) addressed to the
+ * technical-writer. This is the SOLE home of the shared-wiki audit verdict; the
+ * per-PR `wiki` gate no longer reads live wiki state. A clean wiki routes
+ * nothing. The label/search/create-or-comment logic lives here, not in the
+ * workflow, so the curation step is one CLI call.
+ *
+ * @param {import("@forwardimpact/libcli").InvocationContext} ctx
+ * @returns {Promise<{ok: boolean}>}
+ */
+export async function runCurateCommand(ctx) {
+  const { runtime, gitClient } = ctx.deps;
+  const logger = createLogger("wiki", runtime);
+  const { findings } = auditWiki(ctx);
+
+  if (!findings.some((f) => f.level === "fail")) {
+    runtime.proc.stdout.write("wiki audit clean — no curation issue routed\n");
+    return { ok: true };
+  }
+
+  const body = buildBody(emitFindingsJson(findings));
+
+  if (ctx.options["dry-run"]) {
+    runtime.proc.stdout.write(
+      `[dry-run] would route findings to issue "${TITLE}":\n\n${body}`,
+    );
+    return { ok: true };
+  }
+
+  const cwd = resolveProjectRoot(runtime);
+  const repo =
+    ctx.options.repo || (await deriveRepo(gitClient, cwd, runtime.proc.env));
+  const token = await resolveToken();
+  const env = token
+    ? { ...runtime.proc.env, GH_TOKEN: token }
+    : runtime.proc.env;
+  const repoArgs = repo ? ["--repo", repo] : [];
+
+  // Ensure the label exists; a re-create on an existing label exits non-zero,
+  // which is expected and ignored.
+  await runtime.subprocess.run(
+    "gh",
+    [
+      "label",
+      "create",
+      LABEL.name,
+      "--color",
+      LABEL.color,
+      "--description",
+      LABEL.description,
+      ...repoArgs,
+    ],
+    { cwd, env },
+  );
+
+  const list = await runtime.subprocess.run(
+    "gh",
+    [
+      "issue",
+      "list",
+      "--search",
+      `${TITLE} in:title`,
+      "--state",
+      "open",
+      "--json",
+      "number",
+      ...repoArgs,
+    ],
+    { cwd, env },
+  );
+  let number = null;
+  try {
+    number = JSON.parse(list.stdout || "[]")[0]?.number ?? null;
+  } catch {
+    number = null;
+  }
+
+  // Pass the body through a temp file, not argv — robust to length and immune
+  // to finding text being read as a flag.
+  const tmp = runtime.proc.env.RUNNER_TEMP || runtime.proc.env.TMPDIR || "/tmp";
+  const bodyFile = path.join(tmp, "wiki-curation-body.md");
+  runtime.fsSync.writeFileSync(bodyFile, body);
+
+  const result = number
+    ? await runtime.subprocess.run(
+        "gh",
+        [
+          "issue",
+          "comment",
+          String(number),
+          "--body-file",
+          bodyFile,
+          ...repoArgs,
+        ],
+        { cwd, env },
+      )
+    : await runtime.subprocess.run(
+        "gh",
+        [
+          "issue",
+          "create",
+          "--title",
+          TITLE,
+          "--body-file",
+          bodyFile,
+          "--label",
+          LABEL.name,
+          ...repoArgs,
+        ],
+        { cwd, env },
+      );
+
+  if (result.exitCode !== 0) {
+    logger.warn("curate", `gh issue ${number ? "comment" : "create"} failed`);
+    return { ok: false };
+  }
+  runtime.proc.stdout.write(
+    number
+      ? `Commented curation findings on issue #${number}\n`
+      : "Opened a new wiki-curation issue\n",
+  );
+  return { ok: true };
+}

package/src/commands/fix.js

@@ -5,7 +5,7 @@ import {
   createAgentRunner,
   composeProfilePrompt,
   createRedactor,
-} from "@forwardimpact/libeval";
+} from "@forwardimpact/libharness";
 import { RULES } from "../audit/rules.js";
 import { buildContext, resolveScope } from "../audit/scopes.js";
 import {

package/src/wiki-sync.js

@@ -7,6 +7,24 @@ import { scanPushWindow, appendOverrideRecord } from "./secret-gate.js";
 import { runBudgetGate } from "./budget-gate.js";
 import { currentDayIso } from "./util/clock.js";
 
+/**
+ * A git `insteadOf` rule that maps a URL to itself. Some sandboxed
+ * environments install a broad global rewrite —
+ * `url.<local-proxy>.insteadOf = https://github.com/` — that diverts every
+ * github.com URL, the wiki included, to a proxy that serves only the main repo
+ * and returns 403 for the wiki. An identity rule keyed to the full wiki URL is
+ * a longer prefix match than the broad `https://github.com/` rule, so git wins
+ * it by longest-match and leaves the URL untouched; the request then reaches
+ * github.com over the ambient HTTPS proxy. Where no such broad rewrite exists,
+ * the rule is a harmless no-op. Applied inline on clone and persisted into the
+ * clone's local config for every later network op (see {@link WikiSync#pinTransport}).
+ * @param {string} url - The wiki clone URL.
+ * @returns {string} A `-c`-form `url.<url>.insteadOf=<url>` entry.
+ */
+function selfInsteadOf(url) {
+  return `url.${url}.insteadOf=${url}`;
+}
+
 /** The branch the wiki clone publishes (hard-coded in fetch / rebase / push). */
 const BRANCH = "master";
 const REMOTE = "origin";
@@ -215,15 +233,36 @@ export class WikiSync {
 
   /** Clone the wiki from `url` if it is not already cloned. */
   async ensureCloned(url) {
-    if (this.isCloned()) return { cloned: true, reason: "already-cloned" };
+    if (this.isCloned()) {
+      await this.#pinTransport(url);
+      return { cloned: true, reason: "already-cloned" };
+    }
     try {
-      await this.#authed().clone(url, this.#wikiDir);
+      await this.#authed().clone(url, this.#wikiDir, {
+        config: [selfInsteadOf(url)],
+      });
+      await this.#pinTransport(url);
       return { cloned: true, reason: "cloned" };
     } catch (err) {
       return { cloned: false, reason: err.stderr?.trim() || err.message };
     }
   }
 
+  /**
+   * Persist the identity-`insteadOf` for the wiki's own URL into the clone's
+   * local config, so every later network op (fetch / push / ls-remote) that
+   * runs against the stored remote URL — and re-applies `insteadOf` at
+   * transport time — is covered without threading `-c` through each call. The
+   * clone command itself takes the same rule inline (the `.git/config` does not
+   * exist yet). Idempotent; safe to re-run on a resumed clone. See
+   * {@link selfInsteadOf} for why the rule is needed.
+   */
+  async #pinTransport(url) {
+    await this.#git.configSet(`url.${url}.insteadOf`, url, {
+      cwd: this.#wikiDir,
+    });
+  }
+
   /** Copy git user.name and user.email from the parent repository into the wiki repository. */
   async inheritIdentity() {
     const name = await this.#git.configGet("user.name", {