vouchington-tooling 0.2.0 → 0.3.1

package/dist/retrospective-facts/exec.mjs

@@ -0,0 +1,19 @@
+import { spawn } from 'node:child_process';
+export const shell = (command, args) => new Promise((resolve) => {
+    const child = spawn(command, args);
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (data) => {
+        stdout += data;
+    });
+    child.stderr.on('data', (data) => {
+        stderr += data;
+    });
+    child.on('close', (exitCode) => resolve({ ok: exitCode === 0, stdout, stderr, exitCode }));
+    child.on('error', (error) => resolve({ ok: false, stdout, stderr: error.message, exitCode: null }));
+});
+export function rawBlock(command, args, result) {
+    return `$ ${command} ${args.join(' ')}\n${result.stdout}${result.stderr ? `${result.stdout ? '\n' : ''}stderr:\n${result.stderr}` : ''}\n\n`;
+}

package/dist/retrospective-facts/foreign.d.mts

@@ -0,0 +1,2 @@
+import { type CommandExecutor, type RetrospectiveFactsOptions } from './shared.mts';
+export declare function foreignFacts(options: RetrospectiveFactsOptions, execute: CommandExecutor): Promise<string>;

package/dist/retrospective-facts/foreign.mjs

@@ -0,0 +1,36 @@
+import { rawBlock } from './exec.mjs';
+import { apiFiles, count, dirs, format, objectField, readJson, stringField } from './format.mjs';
+import { PR_JSON_FIELDS } from './shared.mjs';
+export async function foreignFacts(options, execute) {
+    const args = ['pr', 'view', options.pr, '--repo', options.repo, '--json', PR_JSON_FIELDS];
+    const result = await execute('gh', args);
+    const data = result.ok ? readJson(result.stdout) : undefined;
+    const state = stringField(data, 'state', result.ok ? 'unavailable' : 'gh failed');
+    const base = stringField(data, 'baseRefName');
+    const merged = state === 'MERGED'
+        ? base === 'main'
+            ? 'yes (GitHub reports PR MERGED into main)'
+            : base === 'unavailable'
+                ? 'unavailable'
+                : `no (GitHub reports PR MERGED into ${base})`
+        : state === 'OPEN' || state === 'CLOSED'
+            ? `no (GitHub reports PR ${state})`
+            : 'unavailable';
+    return format({
+        fetch: 'not run (scoped GitHub repository)',
+        fetchStatus: 'not run',
+        fetchNote: 'scoped GitHub state is authoritative',
+        branch: stringField(data, 'headRefName'),
+        pr: stringField(data, 'number'),
+        state,
+        mergedAt: stringField(data, 'mergedAt'),
+        mergeCommit: objectField(data, 'mergeCommit', 'oid'),
+        merged,
+        commits: 'unavailable',
+        prCommits: count(data, 'commits'),
+        files: apiFiles(data),
+        dirs: dirs(data),
+        changeSource: 'api',
+        scoped: `${options.repo}#${options.pr}`,
+    }, options.raw ? rawBlock('gh', args, result) : '');
+}

package/dist/retrospective-facts/format.d.mts

@@ -0,0 +1,10 @@
+export declare function format(f: Record<string, string | undefined> & {
+    changeSource?: 'api' | 'local';
+}, raw: string): string;
+export declare function readJson(value: string): Record<string, unknown> | undefined;
+export declare function stringField(value: Record<string, unknown> | undefined, key: string, fallback?: string): string;
+export declare function objectField(value: Record<string, unknown> | undefined, key: string, child: string): string | undefined;
+export declare function count(value: Record<string, unknown> | undefined, key: string): string;
+export declare function topDirs(files: string): string;
+export declare function dirs(value: Record<string, unknown> | undefined): string;
+export declare function apiFiles(value: Record<string, unknown> | undefined): string;

package/dist/retrospective-facts/format.mjs

@@ -0,0 +1,64 @@
+export function format(f, raw) {
+    const scoped = f.scoped ? `n/a (scoped to ${f.scoped})` : undefined;
+    const fileSource = f.changeSource === 'api' ? 'GitHub API' : 'origin/main';
+    return `=== Retrospective Facts ===\nFetch: ${f.fetch}\nFetch status: ${f.fetchStatus}\nFetch note: ${f.fetchNote}\nBranch: ${f.branch}\nPR: ${f.pr ?? 'unavailable'}\nPR state: ${f.state}\nPR merged at: ${f.mergedAt ?? 'unavailable'}\nPR merge commit: ${f.mergeCommit ?? 'unavailable'}\nMerged to main: ${f.merged}\nCommits ahead of origin/main: ${f.commits ?? 'unavailable'}\nPR commits: ${f.prCommits ?? 'unavailable'}\nRemote updates for origin/${f.branch}: ${f.remote ?? scoped ?? 'unavailable'}\nPush-like updates for origin/${f.branch}: ${f.pushes ?? scoped ?? 'unavailable'}\nFiles changed from ${fileSource}: ${f.files}\nTop-level dirs changed from ${fileSource}: ${f.dirs}\nWorking tree changes: ${scoped ?? f.working ?? 'unavailable'}\n${raw}`;
+}
+export function readJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function stringField(value, key, fallback = 'unavailable') {
+    const field = value?.[key];
+    return typeof field === 'string' || typeof field === 'number' ? String(field) : fallback;
+}
+export function objectField(value, key, child) {
+    const field = value?.[key];
+    return field && typeof field === 'object'
+        ? stringField(field, child)
+        : undefined;
+}
+export function count(value, key) {
+    const length = listLength(value, key);
+    if (length === undefined)
+        return 'unavailable';
+    return length >= 100
+        ? "100+ (gh's commits list caps at 100; actual count may be higher)"
+        : String(length);
+}
+function listLength(value, key) {
+    return Array.isArray(value?.[key]) ? value[key].length : undefined;
+}
+export function topDirs(files) {
+    const dirs = [
+        ...new Set(files
+            .split('\n')
+            .filter(Boolean)
+            .map((file) => (file.includes('/') ? file.split('/')[0] : 'root'))),
+    ];
+    return dirs.length ? dirs.sort().join(',') : 'none';
+}
+export function dirs(value) {
+    const files = value?.files;
+    if (!Array.isArray(files))
+        return 'unavailable';
+    const result = topDirs(files
+        .map((file) => typeof file === 'object' && file
+        ? stringField(file, 'path', '')
+        : '')
+        .join('\n'));
+    const total = stringField(value, 'changedFiles');
+    return total !== 'unavailable' && Number(total) > files.length
+        ? `${result} (partial: gh returned ${files.length} of ${total} changed files)`
+        : result;
+}
+export function apiFiles(value) {
+    const total = stringField(value, 'changedFiles');
+    const listed = listLength(value, 'files');
+    return total !== 'unavailable' && listed !== undefined && Number(total) !== listed
+        ? `${total} (partial: gh returned ${listed} of ${total} changed files)`
+        : total;
+}

package/dist/retrospective-facts/index.d.mts

@@ -0,0 +1,3 @@
+import type { RetrospectiveFactsOptions } from './shared.mts';
+export type { CommandExecutor, CommandResult, RetrospectiveFactsOptions } from './shared.mts';
+export declare function runRetrospectiveFacts(options: RetrospectiveFactsOptions): Promise<string>;

package/dist/retrospective-facts/index.mjs

@@ -0,0 +1,26 @@
+import { shell } from './exec.mjs';
+import { foreignFacts } from './foreign.mjs';
+import { localFacts } from './local.mjs';
+export async function runRetrospectiveFacts(options) {
+    validate(options);
+    const execute = options.execute ?? shell;
+    return options.repo ? foreignFacts(options, execute) : localFacts(options, execute);
+}
+function validate(options) {
+    if (options.pr !== undefined && !/^\d+$/.test(options.pr))
+        throw new Error('--pr requires a number');
+    if (options.branch !== undefined && (!options.branch || options.branch.startsWith('-')))
+        throw new Error('--branch requires a name');
+    if (options.repo !== undefined && !/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(options.repo))
+        throw new Error('--repo requires an owner/name value');
+    if (options.pr && options.noPr)
+        throw new Error('--pr and --no-pr are mutually exclusive');
+    if (options.repo && options.branch)
+        throw new Error('--branch cannot be combined with --repo');
+    if (options.repo && options.noPr)
+        throw new Error('--no-pr cannot be combined with --repo');
+    if (options.repo && !options.pr)
+        throw new Error('--repo requires --pr (a foreign repo has no current PR for this local branch)');
+    if (!options.pr && !options.branch && !options.noPr)
+        throw new Error('pass --pr <number>, --branch <name>, or --no-pr');
+}

package/dist/retrospective-facts/local.d.mts

@@ -0,0 +1,2 @@
+import { type CommandExecutor, type RetrospectiveFactsOptions } from './shared.mts';
+export declare function localFacts(options: RetrospectiveFactsOptions, execute: CommandExecutor): Promise<string>;

package/dist/retrospective-facts/local.mjs

@@ -0,0 +1,144 @@
+import { rawBlock } from './exec.mjs';
+import { apiFiles, count, dirs, format, objectField, readJson, stringField, topDirs, } from './format.mjs';
+import { PR_JSON_FIELDS, } from './shared.mjs';
+export async function localFacts(options, execute) {
+    const calls = [];
+    const run = async (command, args) => {
+        const result = await execute(command, args);
+        calls.push({ command, args, result });
+        return result;
+    };
+    const mainSpec = 'main:refs/remotes/origin/main';
+    const branchSpec = options.branch
+        ? `${options.branch}:refs/remotes/origin/${options.branch}`
+        : undefined;
+    const fetch = await run('git', ['fetch', 'origin', mainSpec]);
+    const branchFetch = branchSpec ? await run('git', ['fetch', 'origin', branchSpec]) : undefined;
+    const originMain = fetch.ok ||
+        (await run('git', ['rev-parse', '--verify', '--quiet', 'refs/remotes/origin/main'])).ok;
+    const branchResult = await run('git', ['branch', '--show-current']);
+    const localBranch = text(branchResult) || 'unavailable';
+    const selector = options.noPr ? undefined : (options.pr ?? options.branch);
+    const ghArgs = selector ? ['pr', 'view', selector, '--json', PR_JSON_FIELDS] : undefined;
+    const gh = ghArgs ? await run('gh', ghArgs) : undefined;
+    const data = gh?.ok ? readJson(gh.stdout) : undefined;
+    const state = options.noPr
+        ? 'none'
+        : stringField(data, 'state', gh?.ok ? 'unavailable' : gh ? 'gh failed' : 'unavailable');
+    const head = stringField(data, 'headRefName');
+    const branch = options.branch ??
+        (options.pr && head !== 'unavailable' ? head : options.noPr ? localBranch : 'unavailable');
+    const rangeName = options.branch ?? (options.noPr ? localBranch : undefined);
+    const localRange = options.noPr && options.branch === undefined && localBranch === 'unavailable'
+        ? 'HEAD'
+        : rangeName;
+    const resolved = localRange
+        ? await resolveNamedRef(localRange, run, localRange === options.branch && branchFetch?.ok === true)
+        : unresolvedRange();
+    const range = resolved.range;
+    const commitsResult = !data && range && originMain
+        ? await run('git', ['rev-list', '--count', `origin/main..${range}`])
+        : undefined;
+    const diffResult = !data && range && originMain
+        ? await run('git', ['diff', '--name-only', `origin/main...${range}`])
+        : undefined;
+    const scoped = Boolean(options.branch &&
+        (localBranch !== options.branch || (head !== 'unavailable' && head !== options.branch))) || Boolean(options.pr && !options.branch && (head === 'unavailable' || head !== localBranch));
+    const scope = options.branch ?? `#${options.pr}`;
+    const status = scoped
+        ? undefined
+        : await run('git', ['status', '--porcelain', '--untracked-files=normal']);
+    const reflog = scoped || branch === 'unavailable'
+        ? undefined
+        : await run('git', ['reflog', 'show', `origin/${branch}`]);
+    const merge = objectField(data, 'mergeCommit', 'oid');
+    const merged = await mergeFact(data, state, merge, resolved.range, originMain, options, run);
+    const filesText = diffResult?.ok ? text(diffResult) : undefined;
+    const raw = options.raw
+        ? `\n=== Raw Command Output ===\n${calls.map((call) => rawBlock(call.command, call.args, call.result)).join('')}`
+        : '';
+    return format({
+        fetch: `git fetch origin ${mainSpec}${branchSpec ? `; git fetch origin ${branchSpec}` : ''}`,
+        fetchStatus: fetch.ok ? 'ok' : 'failed',
+        fetchNote: `${fetch.ok
+            ? 'origin/main refreshed'
+            : originMain
+                ? 'using existing local origin/main ref after failed fetch'
+                : 'origin/main unavailable after failed fetch'}${resolved.refreshed ? `; origin/${localRange} refreshed` : ''}`,
+        branch,
+        pr: options.noPr ? 'none' : stringField(data, 'number'),
+        state,
+        mergedAt: stringField(data, 'mergedAt'),
+        mergeCommit: merge,
+        merged,
+        commits: data ? 'unavailable' : commitsResult?.ok ? text(commitsResult) : 'unavailable',
+        prCommits: data ? count(data, 'commits') : undefined,
+        files: data
+            ? apiFiles(data)
+            : filesText === undefined
+                ? 'unavailable'
+                : String(lines(filesText).length),
+        dirs: data ? dirs(data) : filesText === undefined ? 'unavailable' : topDirs(filesText),
+        changeSource: data ? 'api' : 'local',
+        remote: reflog === undefined
+            ? undefined
+            : reflog.ok
+                ? String(lines(text(reflog)).length)
+                : 'unavailable',
+        pushes: reflog === undefined
+            ? undefined
+            : reflog.ok
+                ? String(lines(text(reflog)).filter((line) => line.includes('update by push')).length)
+                : 'unavailable',
+        ...(scoped ? { scoped: scope } : {}),
+        working: status === undefined
+            ? undefined
+            : status.ok
+                ? String(lines(text(status)).length)
+                : 'unavailable',
+    }, raw);
+}
+function text(result) {
+    return result.stdout.trim();
+}
+function lines(value) {
+    return value.split('\n').filter(Boolean);
+}
+async function resolveNamedRef(name, run, fetched = false) {
+    if (name === 'HEAD')
+        return { range: name, refreshed: false };
+    if ((await run('git', ['rev-parse', '--verify', '--quiet', `refs/heads/${name}`])).ok)
+        return { range: name, refreshed: false };
+    const fetch = fetched
+        ? { ok: true, stdout: '', stderr: '' }
+        : await run('git', ['fetch', 'origin', `${name}:refs/remotes/origin/${name}`]);
+    if (!fetch.ok)
+        return { range: undefined, refreshed: false };
+    if ((await run('git', ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${name}`])).ok)
+        return { range: `origin/${name}`, refreshed: true };
+    return { range: undefined, refreshed: false };
+}
+function unresolvedRange() {
+    return { range: undefined, refreshed: false };
+}
+async function mergeFact(data, state, merge, range, originMain, options, run) {
+    if (merge && originMain) {
+        const inOrigin = await run('git', ['merge-base', '--is-ancestor', merge, 'origin/main']);
+        if (!inOrigin.ok)
+            return inOrigin.exitCode === 1 ? `no (origin/main lacks ${merge})` : 'unavailable';
+        const inLocalMain = await run('git', ['merge-base', '--is-ancestor', merge, 'main']);
+        if (!inLocalMain.ok && inLocalMain.exitCode === 1)
+            options.onWarning?.(`Warning: local main lacks PR merge commit ${merge}, but origin/main contains it.`);
+        return `yes (origin/main contains ${merge})`;
+    }
+    if (data && (state === 'OPEN' || state === 'CLOSED'))
+        return 'unmerged at time of retro';
+    if (!data && range && originMain) {
+        const rangeInOrigin = await run('git', ['merge-base', '--is-ancestor', range, 'origin/main']);
+        if (rangeInOrigin.ok)
+            return `yes (origin/main contains ${range})`;
+        if (rangeInOrigin.exitCode === 1)
+            return `no (origin/main lacks ${range})`;
+    }
+    return 'unavailable';
+}

package/dist/retrospective-facts/shared.d.mts

@@ -0,0 +1,17 @@
+export declare const PR_JSON_FIELDS = "number,state,mergedAt,mergeCommit,changedFiles,files,commits,headRefName,baseRefName";
+export type CommandResult = {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode?: number | null;
+};
+export type CommandExecutor = (command: string, args: string[]) => Promise<CommandResult>;
+export type RetrospectiveFactsOptions = {
+    pr?: string;
+    branch?: string;
+    noPr?: boolean;
+    repo?: string;
+    raw?: boolean;
+    execute?: CommandExecutor;
+    onWarning?: (message: string) => void;
+};

package/dist/retrospective-facts/shared.mjs

@@ -0,0 +1 @@
+export const PR_JSON_FIELDS = 'number,state,mergedAt,mergeCommit,changedFiles,files,commits,headRefName,baseRefName';

package/dist/skill-discovery/index.mjs

@@ -8,7 +8,16 @@ export async function linkSkill(options) {
         throw new Error(`Invalid skill name: ${options.name}`);
     const sourceRoot = resolve(options.sourceRoot);
     const canonicalSourceRoot = await realpath(sourceRoot);
-    const manifest = await readSkillManifest(sourceRoot);
+    let manifest;
+    try {
+        manifest = await readSkillManifest(sourceRoot);
+    }
+    catch (error) {
+        if (!isMissingManifest(error))
+            throw error;
+        const targetRoot = await resolveTargetDirectory(options.targetRoot);
+        return linkResult(targetRoot, options.name, sourceRoot, canonicalSourceRoot, `${options.name}/SKILL.md`);
+    }
     const entry = manifest.skills.find((candidate) => candidate.name === options.name);
     if (entry === undefined)
         throw new Error(`Unknown skill: ${options.name}`);
@@ -17,6 +26,9 @@ export async function linkSkill(options) {
     const linking = new Set();
     return linkManifestSkill(sourceRoot, canonicalSourceRoot, targetRoot, manifest, entry, linked, linking);
 }
+function isMissingManifest(error) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
+}
 async function linkManifestSkill(sourceRoot, canonicalSourceRoot, targetRoot, manifest, entry, linked, linking) {
     if (linked.has(entry.name))
         return linkResult(targetRoot, entry.name, sourceRoot, canonicalSourceRoot, entry.path);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -46,6 +46,16 @@
       "import": "./dist/retrospective-transcript/index.mjs",
       "default": "./dist/retrospective-transcript/index.mjs"
     },
+    "./retrospective-facts": {
+      "types": "./dist/retrospective-facts/index.d.mts",
+      "import": "./dist/retrospective-facts/index.mjs",
+      "default": "./dist/retrospective-facts/index.mjs"
+    },
+    "./agent-blackboard": {
+      "types": "./dist/agent-blackboard/index.d.mts",
+      "import": "./dist/agent-blackboard/index.mjs",
+      "default": "./dist/agent-blackboard/index.mjs"
+    },
     "./session-friction": {
       "types": "./dist/session-friction/index.d.mts",
       "import": "./dist/session-friction/index.mjs",
@@ -239,7 +249,16 @@
     "yaml": "2.9.0"
   },
   "devDependencies": {
-    "@types/picomatch": "^4.0.3"
+    "@types/picomatch": "^4.0.3",
+    "agent-blackboard": "^0.3.1"
+  },
+  "peerDependencies": {
+    "agent-blackboard": "^0.3.1"
+  },
+  "peerDependenciesMeta": {
+    "agent-blackboard": {
+      "optional": true
+    }
   },
   "optionalDependencies": {
     "@libpg-query/parser": "^18.0.0"

package/scripts/gha/harness-admission-lane.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ "${#}" -ne 1 ]; then
+  echo "usage: harness-admission-lane.sh <lanes>" >&2
+  exit 2
+fi
+
+if [ -z "${GITHUB_OUTPUT:-}" ]; then
+  echo 'GITHUB_OUTPUT must be set' >&2
+  exit 2
+fi
+
+LANES="$1"
+if ! [[ "$LANES" =~ ^[1-9][0-9]*$ ]]; then
+  echo "::error::admission lane count must be a positive integer, got: '$LANES'"
+  exit 1
+fi
+
+RUN_ID="${GITHUB_RUN_ID:-}"
+if ! [[ "$RUN_ID" =~ ^[0-9]+$ ]]; then
+  echo "::error::GITHUB_RUN_ID must be a non-negative integer, got: '${RUN_ID}'"
+  exit 1
+fi
+
+echo "lane=$(( RUN_ID % LANES ))" >> "$GITHUB_OUTPUT"

package/scripts/gha/harness-assert-gates.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ "$#" -eq 0 ]; then
+  echo "usage: harness-assert-gates.sh <gate>..." >&2
+  exit 2
+fi
+
+for gate in "$@"; do
+  if ! [[ "$gate" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]]; then
+    echo "::error::invalid gate name: '$gate'"
+    exit 1
+  fi
+done
+
+for gate in "$@"; do
+  value="${!gate:-}"
+  if [ "$value" = "true" ]; then
+    echo "::error::$gate must be disabled but is enabled"
+    exit 1
+  fi
+done
+
+exit 0