{
  "id": "page:library-common-utilities",
  "_kind": "Page",
  "_file": "wiki/library/common-utilities.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "title": "common-utilities (Library)",
    "displayName": "common-utilities (Library)",
    "slug": "library/common-utilities",
    "articlePath": "wiki/library/common-utilities.md",
    "article": "\n# common-utilities\n\nShared composition utilities for babysitter processes. These modules package the\ncurrent quality bar — routed breakpoints, adversarial evidence-mandatory gates,\nparallel fan-out, kip recall/assert checkpoints — as importable helpers so\nprocesses stop re-implementing the patterns by hand.\n\nImport pattern (from a process file elsewhere in the library):\n\n```js\nimport {\n  routedBreakpoint,\n  adversarialGate,\n  kipRecall,\n  kipAssert,\n  KIP_CLI_NOTE,\n} from '../common-utilities/routed-gate-combinators.js';\n// or via the barrel:\nimport { fanOutFanIn, pipeline, routedBreakpoint } from '../common-utilities/index.js';\n```\n\n## Module catalog\n\n| Module | Exports | Purpose |\n| --- | --- | --- |\n| `docx-conversion.js` | `convertToDocxTask` | Convert an HTML artifact to .docx via pandoc |\n| `parallel-combinator.js` | `fanOutFanIn`, `pipeline` | Fan-out/fan-in and phased pipelines for concurrent tasks |\n| `routed-gate-combinators.js` | `routedBreakpoint`, `adversarialGate`, `adversarialCriticTask`, `gateFixerTask`, `kipRecall`, `kipAssert`, `kipRecallTask`, `kipAssertTask`, `KIP_CLI_NOTE` | Routed breakpoints, adversarial IRON-LAW quality gates, kip checkpoints |\n| `routed-gate-combinators-demo.js` | `routedGateCombinatorsDemo`, `draftUsageGuideTask` | Exemplar process exercising all three combinators end-to-end |\n\n### docx-conversion\n\nA shared HTML-to-DOCX conversion task using pandoc with graceful fallback.\n\n**Usage:**\n```javascript\nimport { convertToDocxTask } from '../common-utilities/index.js';\n\n// In your process:\nconst result = await ctx.task(convertToDocxTask, {\n  htmlPath: '/path/to/input.html',\n  docxPath: '/path/to/output.docx'\n});\n// result: { success: true, path: '...', converter: 'pandoc' }\n// or:     { success: false, path: '...', reason: 'pandoc not installed', converter: 'none' }\n```\n\n### parallel-combinator\n\nUtility functions for parallel task execution with fan-out/fan-in patterns.\n\n**fanOutFanIn** - Run multiple tasks in parallel with shared input:\n```javascript\nimport { fanOutFanIn } from '../common-utilities/index.js';\n\nconst [strengths, weaknesses] = await fanOutFanIn(ctx, { essay, analysis }, [\n  { task: evaluateStrengthsTask },\n  { task: evaluateWeaknessesTask }\n]);\n```\n\n**pipeline** - Sequential phases with optional parallel steps (a nested array\nmeans the steps inside it run in parallel as one phase):\n```javascript\nimport { pipeline } from '../common-utilities/index.js';\n\nconst result = await pipeline(ctx, { essay }, [\n  { task: analyzeTask, key: 'analysis' },\n  [\n    { task: strengthsTask, key: 'strengths' },\n    { task: weaknessesTask, key: 'weaknesses' }\n  ],\n  { task: synthesizeTask, key: 'document' }\n]);\n```\n\n## routedBreakpoint\n\nThin wrapper over `ctx.breakpoint` that makes routing metadata non-optional:\n`breakpointId`, `expert`, and non-empty `tags` are **required** (the helper\nthrows if any is missing — no fallbacks), `strategy` defaults to `'single'`,\nand `label` defaults to the `breakpointId`. Real call site from the demo\nprocess:\n\n```js\nconst acceptance = await routedBreakpoint(ctx, {\n  question: 'Usage guide passed the adversarial gate. Approve the combinators API ergonomics and accept the demo?',\n  artifactPath,\n  gate,\n}, {\n  breakpointId: 'common-utilities.demo.owner-acceptance',\n  expert: 'owner',\n  tags: ['common-utilities', 'combinators', 'acceptance'],\n  strategy: 'single',\n});\n```\n\nOptional routing fields: `label`, `autoApproveAfterN`, `presentAlwaysApprove`.\nThe `BreakpointResult` is returned unchanged.\n\n## adversarialGate\n\nFans out independent IRON-LAW critics over an artifact (concurrently, via\n`ctx.parallel.all` thunks), reduces their verdicts, runs a bounded fixer loop\nbetween rounds, and escalates to a routed owner breakpoint\n(`<gateId>.gate-escalation`) when the fix budget is exhausted. Real call site\nfrom the demo process:\n\n```js\nconst gate = await adversarialGate(ctx, {\n  gateId: 'common-utilities.demo.usage-guide',\n  artifact: {\n    path: artifactPath,\n    description: 'Usage guide for the routed-gate combinators',\n  },\n  critics: [\n    {\n      name: 'accuracy-critic',\n      role: 'API accuracy reviewer',\n      focus: 'every documented signature, default, and contract must match the module source exactly',\n    },\n    {\n      name: 'ergonomics-critic',\n      role: 'API ergonomics reviewer',\n      focus: 'call sites must be shorter and safer than hand-rolled ctx.breakpoint/ctx.parallel equivalents; flag any awkward required argument or footgun',\n    },\n  ],\n  ironLaw: [\n    'Verify every code snippet in the guide against the actual exports in library/specializations/common-utilities/routed-gate-combinators.js — cite file and line for each verified claim.',\n  ],\n  maxFixAttempts,\n  fixer: {},\n});\n```\n\nGate contract — the result is always\n`{ passed, issues: [{critic, severity, description}], evidence: [{critic, evidence: string[]}], attempts, escalated }`.\n**Evidence is mandatory for a pass**: a critic verdict counts as passed only\nwhen `passed === true` AND its `evidence` array is non-empty; an\nevidence-empty pass is coerced to a `severity: 'protocol'` failure\n(`PASS verdict rejected: no evidence supplied`). `gateId`, a non-empty\n`critics` array, and an `artifact.path` are required — the combinator throws\notherwise. `fixer: {}` opts into the built-in `gateFixerTask`; pass\n`fixer: { task, args }` for a custom fixer; omit `fixer` entirely to skip the\nfix loop and escalate directly on failure.\n\n## kipRecall / kipAssert\n\nRecall-at-start and assert-at-end checkpoints wrapping agent tasks whose\nprompts embed `KIP_CLI_NOTE`. `kipRecall` requires a `topic` (throws if\nmissing); a fresh or missing store is initialized and reported as\n`factCount: 0` / `storeInitialized: true`, never an error. `kipAssert`\nrequires a **non-empty** `facts` array (asserting nothing is a caller bug and\nthrows); per-fact failures are reported in `failed`, never swallowed. Real\ncall sites from the demo process:\n\n```js\nconst recall = await kipRecall(ctx, {\n  kipDir,\n  topic: 'routed-gate-combinators usage',\n  kipModel,\n  kind: 'library-enrichment',\n});\n\nconst assertResult = await kipAssert(ctx, {\n  kipDir,\n  kipModel,\n  kind: 'library-enrichment',\n  facts: [\n    {\n      subject: 'process:routed-gate-combinators-demo',\n      predicate: 'exercised',\n      object: 'combinator:adversarialGate',\n      props: { gateId: 'common-utilities.demo.usage-guide' },\n    },\n  ],\n});\n```\n\n## kip CLI note (Windows-safe)\n\nEmbedded verbatim into every kip-touching agent prompt as `KIP_CLI_NOTE`:\n\n> kip CLI resolution: use `kip` if on PATH; otherwise invoke Windows-safe as\n> `node packages/kip-sdk/dist/cli/kip.js` (npm exec bin resolution is\n> unreliable on Windows). Always pass `--dir <kipDir>` and `--json`. If the\n> store does not exist yet, run `kip init --dir <kipDir> --create` first and\n> treat an empty recall as a fresh brain, not an error. For `kip ask` /\n> `kip resolve` structured paths always pass `--model <kipModel>` explicitly\n> (weak default models under-fire on JSON-schema adjudication).\n\n## Why these helpers exist (quality-bar rationale)\n\nThe `docx-conversion` and `parallel-combinator` utilities were extracted from\na retrospective analysis of essay-critique, extract-oral-prep, and\nessay-grading processes where identical patterns were duplicated across\nmultiple files.\n\nA census of the library found only ~15 of ~2035 breakpoint-using files pass\nrouting options to `ctx.breakpoint`, and common-utilities had no gate or\nbreakpoint combinators at all. Every future retrofit batch and new process\nshould import these helpers instead of re-implementing routing metadata,\nIRON-LAW critic prompts, evidence reduction, and Windows-safe kip invocation\nby hand — the combinators make the quality bar the path of least resistance.\n\n## Running the demo process\n\nThe exemplar process `routedGateCombinatorsDemo` exercises all three\ncombinators end-to-end and writes its artifact under `ctx.artifactsDir`\n(no repo files are touched by demo runs):\n\n```bash\nbabysitter run:create \\\n  --process specializations/common-utilities/routed-gate-combinators-demo#routedGateCombinatorsDemo \\\n  --inputs '{\"kipEnabled\": true, \"maxFixAttempts\": 2}'\nbabysitter run:iterate <runId>\n```\n\nInputs (all optional): `topic`, `kipEnabled` (default `true`), `kipDir`\n(default `.a5c/kip`), `kipModel` (default `sonnet`), `maxFixAttempts`\n(default `2`). The run pauses at the\n`common-utilities.demo.owner-acceptance` breakpoint for owner review, and —\nonly if the gate exhausts its fix budget — at the routed\n`common-utilities.demo.usage-guide.gate-escalation` breakpoint.\n",
    "documents": [
      "specialization:common-utilities"
    ]
  },
  "outgoingEdges": [
    {
      "from": "page:library-common-utilities",
      "to": "specialization:common-utilities",
      "kind": "documents"
    }
  ],
  "incomingEdges": [
    {
      "from": "page:index",
      "to": "page:library-common-utilities",
      "kind": "contains_page"
    }
  ]
}