vouchington-tooling 0.17.0 → 0.18.1

package/README.md

@@ -238,6 +238,10 @@ import { runCiLocal } from 'vouchington-tooling/ci-local'
 import { rateLimitDelay } from 'vouchington-tooling/gha-rate-limit'
 import { parseCheckpoint } from 'vouchington-tooling/gha-pr-checkpoint'
 import { checkWorkspaceGatesPolicy } from 'vouchington-tooling/workspace-gates'
+import {
+  collectPnpmLicenseReport,
+  evaluatePnpmLicenseReport,
+} from 'vouchington-tooling/dependency-license-policy'
 import { checkGhaWorkspacePolicy } from 'vouchington-tooling/gha-workspace-policy'
 import { requireUpToDate } from 'vouchington-tooling/require-up-to-date'
 import { runGitleaksDirectoryScan } from 'vouchington-tooling/gitleaks-directory-scan'
@@ -306,6 +310,17 @@ policy out of this package.
 dependency declared by a non-fixture package manifest. Assert dependency membership or placement,
 or derive a configuration or documentation package spec from that manifest instead.
 
+`dependency-license-policy` keeps legal policy in the consumer. `collectPnpmLicenseReport` creates
+an isolated, script-free temporary workspace and store, expands pnpm's supported architectures to
+every `os`, `cpu`, and `libc` selector represented in the lockfile, and validates the JSON report.
+Pass explicit denied SPDX IDs and prefixes, exact aliases, and justified allowlist scopes to
+`evaluatePnpmLicenseReport`. Unknown, malformed, and custom SPDX references fail closed. Allowlist
+scopes are either intentionally global or an exact package-name set; the library returns structured
+violations and does not format CI-provider diagnostics.
+When present, the repository `.npmrc` is copied into the owner-private temporary directory so pnpm
+can authenticate to the same registries; normal cleanup removes the copy, and the caller remains
+responsible for terminating the process normally rather than abandoning temporary audit state.
+
 `session-friction` is an opt-in capture and reporting library. Callers supply the session id,
 absolute log directory, host-independent observation, and journal loader; it does not inspect host
 environment variables, install hooks, or connect to a journal service by itself. Invoking

package/dist/dependency-license-policy/collect.d.mts

@@ -0,0 +1,9 @@
+import type { PnpmExecutor, PnpmLicenseReport } from './types.mts';
+import { type PnpmLicenseAuditWorkspace } from './workspace.mts';
+export interface CollectPnpmLicenseReportOptions {
+    readonly execute?: PnpmExecutor;
+    readonly prepareWorkspace?: (repoRoot: string, lockfileSource: string, workspaceSource: string) => PnpmLicenseAuditWorkspace;
+    readonly readFile?: (path: string, encoding: 'utf8') => string;
+}
+/** Collects licenses for every platform represented in a pnpm lockfile. */
+export declare function collectPnpmLicenseReport(repoRoot: string, options?: CollectPnpmLicenseReportOptions): PnpmLicenseReport;

package/dist/dependency-license-policy/collect.mjs

@@ -0,0 +1,48 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parsePnpmLicenseReport } from './report.mjs';
+import { preparePnpmLicenseAuditWorkspace } from './workspace.mjs';
+const DEFAULT_OPTIONS = {
+    execute: spawnSync,
+    prepareWorkspace: preparePnpmLicenseAuditWorkspace,
+    readFile: readFileSync,
+};
+function commandFailureOutput(result) {
+    return result.stderr.trim() || result.stdout.trim();
+}
+function assertCommandSucceeded(label, result) {
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0) {
+        throw new Error(`${label} exited with status ${String(result.status)}: ${commandFailureOutput(result)}`);
+    }
+}
+/** Collects licenses for every platform represented in a pnpm lockfile. */
+export function collectPnpmLicenseReport(repoRoot, options = {}) {
+    const { execute, prepareWorkspace, readFile } = { ...DEFAULT_OPTIONS, ...options };
+    const lockfilePath = join(repoRoot, 'pnpm-lock.yaml');
+    const workspacePath = join(repoRoot, 'pnpm-workspace.yaml');
+    const auditWorkspace = prepareWorkspace(repoRoot, readFile(lockfilePath, 'utf8'), readFile(workspacePath, 'utf8'));
+    try {
+        const storeConfig = `--config.store-dir=${join(auditWorkspace.cwd, '.pnpm-store')}`;
+        const fetchResult = execute('pnpm', [storeConfig, '--config.force=true', 'fetch', '--ignore-scripts'], { cwd: auditWorkspace.cwd, encoding: 'utf8' });
+        assertCommandSucceeded('pnpm fetch', fetchResult);
+        const result = execute('pnpm', [storeConfig, 'licenses', 'list', '--json'], {
+            cwd: auditWorkspace.cwd,
+            encoding: 'utf8',
+        });
+        assertCommandSucceeded('pnpm licenses list --json', result);
+        try {
+            return parsePnpmLicenseReport(JSON.parse(result.stdout));
+        }
+        catch (error) {
+            throw new Error(`pnpm licenses list --json produced unparseable output: ${String(error)}`, {
+                cause: error,
+            });
+        }
+    }
+    finally {
+        auditWorkspace.cleanup();
+    }
+}

package/dist/dependency-license-policy/index.d.mts

@@ -0,0 +1,4 @@
+export { collectPnpmLicenseReport, type CollectPnpmLicenseReportOptions } from './collect.mts';
+export { evaluatePackageLicenseExpression, evaluatePnpmLicenseReport } from './policy.mts';
+export { parsePnpmLicenseReport } from './report.mts';
+export type { DependencyLicenseAllowlistEntry, DependencyLicenseEvaluation, DependencyLicensePolicy, DependencyLicenseViolation, PnpmExecutor, PnpmLicenseReport, PnpmLicenseReportEntry, } from './types.mts';

package/dist/dependency-license-policy/index.mjs

@@ -0,0 +1,3 @@
+export { collectPnpmLicenseReport } from './collect.mjs';
+export { evaluatePackageLicenseExpression, evaluatePnpmLicenseReport } from './policy.mjs';
+export { parsePnpmLicenseReport } from './report.mjs';

package/dist/dependency-license-policy/policy.d.mts

@@ -0,0 +1,3 @@
+import type { DependencyLicenseEvaluation, DependencyLicensePolicy, DependencyLicenseViolation, PnpmLicenseReport } from './types.mts';
+export declare function evaluatePackageLicenseExpression(licenseExpression: string, packageName: string, policy: DependencyLicensePolicy): DependencyLicenseEvaluation;
+export declare function evaluatePnpmLicenseReport(report: PnpmLicenseReport, policy: DependencyLicensePolicy): DependencyLicenseViolation[];

package/dist/dependency-license-policy/policy.mjs

@@ -0,0 +1,40 @@
+import { collectSpdxAtoms, evaluateSpdxExpression, parseSpdxExpression } from './spdx.mjs';
+function isAllowlisted(atomId, packageName, policy) {
+    return (policy.allowlist ?? []).some((entry) => entry.licenseId === atomId &&
+        (entry.scope.kind === 'all' || entry.scope.packageNames.includes(packageName)));
+}
+function isDenied(atomId, policy) {
+    return (policy.deniedLicenseIds.includes(atomId) ||
+        policy.deniedLicensePrefixes.some((prefix) => atomId.startsWith(prefix)));
+}
+export function evaluatePackageLicenseExpression(licenseExpression, packageName, policy) {
+    const normalized = policy.knownLicenseAliases?.[licenseExpression] ?? licenseExpression;
+    let node;
+    try {
+        node = parseSpdxExpression(normalized);
+    }
+    catch {
+        return { ok: false, deniedAtoms: [licenseExpression] };
+    }
+    const isAtomAllowed = (atomId) => isAllowlisted(atomId, packageName, policy) || !isDenied(atomId, policy);
+    const ok = evaluateSpdxExpression(node, isAtomAllowed);
+    const deniedAtoms = ok ? [] : collectSpdxAtoms(node).filter((atomId) => !isAtomAllowed(atomId));
+    return { ok, deniedAtoms };
+}
+export function evaluatePnpmLicenseReport(report, policy) {
+    const violations = [];
+    for (const [licenseExpression, entries] of Object.entries(report)) {
+        for (const entry of entries) {
+            const evaluation = evaluatePackageLicenseExpression(licenseExpression, entry.name, policy);
+            if (evaluation.ok)
+                continue;
+            violations.push({
+                ...evaluation,
+                licenseExpression,
+                packageName: entry.name,
+                ...(entry.versions === undefined ? {} : { versions: entry.versions }),
+            });
+        }
+    }
+    return violations;
+}

package/dist/dependency-license-policy/report.d.mts

@@ -0,0 +1,2 @@
+import type { PnpmLicenseReport } from './types.mts';
+export declare function parsePnpmLicenseReport(value: unknown): PnpmLicenseReport;

package/dist/dependency-license-policy/report.mjs

@@ -0,0 +1,30 @@
+function getStringList(value, path) {
+    if (!Array.isArray(value) || !value.every((entry) => typeof entry === 'string')) {
+        throw new Error(`expected ${path} to be an array of strings`);
+    }
+    return value;
+}
+export function parsePnpmLicenseReport(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error('expected a JSON object keyed by license expression');
+    }
+    const report = Object.create(null);
+    for (const [licenseExpression, entries] of Object.entries(value)) {
+        if (!Array.isArray(entries)) {
+            throw new Error(`expected license group ${JSON.stringify(licenseExpression)} to be an array`);
+        }
+        report[licenseExpression] = entries.map((entry, index) => {
+            const path = `license group ${JSON.stringify(licenseExpression)} entry ${String(index)}`;
+            if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+                throw new Error(`expected ${path} to be an object`);
+            }
+            const { name, versions } = entry;
+            if (typeof name !== 'string')
+                throw new Error(`expected ${path}.name to be a string`);
+            if (versions === undefined)
+                return { name };
+            return { name, versions: getStringList(versions, `${path}.versions`) };
+        });
+    }
+    return report;
+}

package/dist/dependency-license-policy/spdx.d.mts

@@ -0,0 +1,13 @@
+export type SpdxNode = {
+    type: 'AND';
+    children: SpdxNode[];
+} | {
+    type: 'OR';
+    children: SpdxNode[];
+} | {
+    type: 'ATOM';
+    id: string;
+};
+export declare function parseSpdxExpression(expression: string): SpdxNode;
+export declare function evaluateSpdxExpression(node: SpdxNode, isAtomAllowed: (atomId: string) => boolean): boolean;
+export declare function collectSpdxAtoms(node: SpdxNode): string[];

package/dist/dependency-license-policy/spdx.mjs

@@ -0,0 +1,40 @@
+import parseSpdx from 'spdx-expression-parse';
+function isCustomLicenseReference(licenseId) {
+    return licenseId.startsWith('LicenseRef-') || licenseId.startsWith('DocumentRef-');
+}
+function convertParsedNode(parsed) {
+    if ('license' in parsed) {
+        if (isCustomLicenseReference(parsed.license)) {
+            throw new Error(`Custom SPDX license references are not allowed: ${parsed.license}`);
+        }
+        const id = `${parsed.license}${parsed.plus ? '+' : ''}${parsed.exception ? ` WITH ${parsed.exception}` : ''}`;
+        return { type: 'ATOM', id };
+    }
+    const type = parsed.conjunction === 'and' ? 'AND' : 'OR';
+    const children = [convertParsedNode(parsed.left), convertParsedNode(parsed.right)].flatMap((child) => (child.type === type ? child.children : [child]));
+    return { type, children };
+}
+export function parseSpdxExpression(expression) {
+    if (expression.trim().length === 0) {
+        throw new Error('Invalid SPDX license expression: expression is empty');
+    }
+    try {
+        return convertParsedNode(parseSpdx(expression));
+    }
+    catch (error) {
+        throw new Error(`Invalid SPDX license expression: ${String(error)}`, { cause: error });
+    }
+}
+export function evaluateSpdxExpression(node, isAtomAllowed) {
+    if (node.type === 'ATOM')
+        return isAtomAllowed(node.id);
+    if (node.type === 'OR') {
+        return node.children.some((child) => evaluateSpdxExpression(child, isAtomAllowed));
+    }
+    return node.children.every((child) => evaluateSpdxExpression(child, isAtomAllowed));
+}
+export function collectSpdxAtoms(node) {
+    if (node.type === 'ATOM')
+        return [node.id];
+    return node.children.flatMap(collectSpdxAtoms);
+}

package/dist/dependency-license-policy/types.d.mts

@@ -0,0 +1,43 @@
+export interface PnpmLicenseReportEntry {
+    readonly name: string;
+    readonly versions?: readonly string[];
+}
+/** Shape emitted by `pnpm licenses list --json`. */
+export type PnpmLicenseReport = Record<string, PnpmLicenseReportEntry[]>;
+export type PnpmExecutor = (command: string, args: string[], options: {
+    cwd: string;
+    encoding: 'utf8';
+}) => {
+    error?: Error;
+    status: number | null;
+    stderr: string;
+    stdout: string;
+};
+export interface DependencyLicenseAllowlistEntry {
+    /** Exact SPDX atom allowed by this entry. */
+    readonly licenseId: string;
+    /** Human-readable evidence for the exception. */
+    readonly reason: string;
+    /** Explicit package scope for this allowance. */
+    readonly scope: {
+        readonly kind: 'all';
+    } | {
+        readonly kind: 'exact';
+        readonly packageNames: readonly string[];
+    };
+}
+export interface DependencyLicensePolicy {
+    readonly allowlist?: readonly DependencyLicenseAllowlistEntry[];
+    readonly deniedLicenseIds: readonly string[];
+    readonly deniedLicensePrefixes: readonly string[];
+    readonly knownLicenseAliases?: Readonly<Record<string, string>>;
+}
+export interface DependencyLicenseEvaluation {
+    readonly deniedAtoms: readonly string[];
+    readonly ok: boolean;
+}
+export interface DependencyLicenseViolation extends DependencyLicenseEvaluation {
+    readonly licenseExpression: string;
+    readonly packageName: string;
+    readonly versions?: readonly string[];
+}

package/dist/dependency-license-policy/types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/dependency-license-policy/workspace.d.mts

@@ -0,0 +1,9 @@
+export interface PnpmLicenseAuditWorkspace {
+    readonly cleanup: () => void;
+    readonly cwd: string;
+}
+export declare function renderPnpmLicenseAuditWorkspace(lockfileSource: string, workspaceSource: string, paths: {
+    lockfile: string;
+    workspace: string;
+}): string;
+export declare function preparePnpmLicenseAuditWorkspace(repoRoot: string, lockfileSource: string, workspaceSource: string): PnpmLicenseAuditWorkspace;

package/dist/dependency-license-policy/workspace.mjs

@@ -0,0 +1,77 @@
+import { copyFileSync, existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+const PLATFORM_KEYS = ['os', 'cpu', 'libc'];
+function parseYamlObject(source, path) {
+    let parsed;
+    try {
+        parsed = parseYaml(source);
+    }
+    catch (error) {
+        throw new Error(`failed to parse ${path}: ${String(error)}`, { cause: error });
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`expected ${path} to contain a YAML object`);
+    }
+    return parsed;
+}
+function getStringList(value, path) {
+    if (typeof value === 'string')
+        return [value];
+    if (!Array.isArray(value) || !value.every((entry) => typeof entry === 'string')) {
+        throw new Error(`expected ${path} to be a string or an array of strings`);
+    }
+    return value;
+}
+export function renderPnpmLicenseAuditWorkspace(lockfileSource, workspaceSource, paths) {
+    const lockfile = parseYamlObject(lockfileSource, paths.lockfile);
+    const workspace = parseYamlObject(workspaceSource, paths.workspace);
+    const packages = lockfile.packages;
+    if (typeof packages !== 'object' || packages === null || Array.isArray(packages)) {
+        throw new Error(`expected ${paths.lockfile} to contain a packages object`);
+    }
+    const supportedArchitectures = {
+        cpu: ['current'],
+        libc: ['current'],
+        os: ['current'],
+    };
+    for (const key of PLATFORM_KEYS) {
+        const values = new Set();
+        for (const snapshot of Object.values(packages)) {
+            if (typeof snapshot !== 'object' || snapshot === null || Array.isArray(snapshot))
+                continue;
+            const value = snapshot[key];
+            if (value === undefined)
+                continue;
+            for (const platform of getStringList(value, `${paths.lockfile} packages.*.${key}`)) {
+                values.add(platform);
+            }
+        }
+        supportedArchitectures[key].push(...[...values].filter((value) => value !== 'current').sort());
+    }
+    return stringifyYaml({ ...workspace, packages: [], supportedArchitectures });
+}
+export function preparePnpmLicenseAuditWorkspace(repoRoot, lockfileSource, workspaceSource) {
+    const auditRoot = mkdtempSync(join(tmpdir(), 'dependency-license-audit-'));
+    try {
+        for (const filename of ['package.json', 'pnpm-lock.yaml']) {
+            copyFileSync(join(repoRoot, filename), join(auditRoot, filename));
+        }
+        const npmrc = join(repoRoot, '.npmrc');
+        if (existsSync(npmrc))
+            copyFileSync(npmrc, join(auditRoot, '.npmrc'));
+        writeFileSync(join(auditRoot, 'pnpm-workspace.yaml'), renderPnpmLicenseAuditWorkspace(lockfileSource, workspaceSource, {
+            lockfile: join(repoRoot, 'pnpm-lock.yaml'),
+            workspace: join(repoRoot, 'pnpm-workspace.yaml'),
+        }), 'utf8');
+    }
+    catch (error) {
+        rmSync(auditRoot, { force: true, recursive: true });
+        throw error;
+    }
+    return {
+        cwd: auditRoot,
+        cleanup: () => rmSync(auditRoot, { force: true, recursive: true }),
+    };
+}

package/dist/index.d.mts

@@ -86,6 +86,8 @@ export { CHECKPOINT_MARKER, isTrustedCheckpointComment, parseCheckpoint, renderC
 export type { Checkpoint, CheckpointCodecOptions, GitHubComment, } from './gha-pr-checkpoint/index.mts';
 export { checkWorkspaceGatesPolicy } from './workspace-gates/index.mts';
 export type { WorkspaceGatesOptions } from './workspace-gates/index.mts';
+export { collectPnpmLicenseReport, evaluatePackageLicenseExpression, evaluatePnpmLicenseReport, parsePnpmLicenseReport, } from './dependency-license-policy/index.mts';
+export type { CollectPnpmLicenseReportOptions, DependencyLicenseAllowlistEntry, DependencyLicenseEvaluation, DependencyLicensePolicy, DependencyLicenseViolation, PnpmLicenseReport, PnpmLicenseReportEntry, } from './dependency-license-policy/index.mts';
 export { validateNugetUpdate } from './nuget-central-version/index.mts';
 export { normalizeSwiftSource } from './swift-semantic-equal/index.mts';
 export { isSwiftCodeOffset, parseUniqueSwiftBinaryTargetChecksum, } from './swift-source-offset/index.mts';

package/dist/index.mjs

@@ -46,6 +46,7 @@ export { assertWorkflowCommandDrift, parseCiLocalArgs, runCiLocal } from './ci-l
 export { GitHubRateLimitError, isRateLimited, isRetryableCancellationError, MAX_RATE_LIMIT_WAIT_MS, rateLimitDelay, reserveRateLimitDelay, } from './gha-rate-limit/index.mjs';
 export { CHECKPOINT_MARKER, isTrustedCheckpointComment, parseCheckpoint, renderCheckpoint, sortedCheckpointCandidates, validateCheckpoint, } from './gha-pr-checkpoint/index.mjs';
 export { checkWorkspaceGatesPolicy } from './workspace-gates/index.mjs';
+export { collectPnpmLicenseReport, evaluatePackageLicenseExpression, evaluatePnpmLicenseReport, parsePnpmLicenseReport, } from './dependency-license-policy/index.mjs';
 export { validateNugetUpdate } from './nuget-central-version/index.mjs';
 export { normalizeSwiftSource } from './swift-semantic-equal/index.mjs';
 export { isSwiftCodeOffset, parseUniqueSwiftBinaryTargetChecksum, } from './swift-source-offset/index.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.17.0",
+  "version": "0.18.1",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -268,6 +268,11 @@
       "import": "./dist/workspace-gates/index.mjs",
       "default": "./dist/workspace-gates/index.mjs"
     },
+    "./dependency-license-policy": {
+      "types": "./dist/dependency-license-policy/index.d.mts",
+      "import": "./dist/dependency-license-policy/index.mjs",
+      "default": "./dist/dependency-license-policy/index.mjs"
+    },
     "./nuget-central-version": {
       "types": "./dist/nuget-central-version/index.d.mts",
       "import": "./dist/nuget-central-version/index.mjs",
@@ -328,11 +333,13 @@
     "remark": "15.0.1",
     "remark-gfm": "4.0.1",
     "smol-toml": "1.8.0",
+    "spdx-expression-parse": "5.0.0",
     "yaml": "2.9.0"
   },
   "devDependencies": {
     "@ast-grep/cli": "0.45.3",
     "@types/picomatch": "^4.0.3",
+    "@types/spdx-expression-parse": "4.0.0",
     "agent-blackboard": "^0.5.0"
   },
   "peerDependencies": {

package/scripts/gha/write-github-multiline-output.sh

@@ -26,17 +26,17 @@ delimiter_prefix=$(printf '%s' "$output_name" | tr '[:lower:]-' '[:upper:]_')
 delimiter=''
 attempt=1
 while [[ $attempt -le 10 ]]; do
-  if ! uuid=$(uuidgen); then
-    echo 'uuidgen failed while creating a GitHub output delimiter' >&2
+  if ! random_suffix=$(LC_ALL=C od -An -v -N16 -tx1 /dev/urandom | LC_ALL=C tr -d '[:space:]'); then
+    echo 'random suffix generation failed while creating a GitHub output delimiter' >&2
     exit 1
   fi
-  if [[ -z "$uuid" ]]; then
-    echo 'uuidgen returned an empty GitHub output delimiter suffix' >&2
+  if [[ ! "$random_suffix" =~ ^[[:xdigit:]]{32}$ ]]; then
+    echo 'random suffix generator returned an invalid GitHub output delimiter suffix' >&2
     exit 1
   fi
 
-  normalized_uuid=$(printf '%s' "$uuid" | tr '[:lower:]-' '[:upper:]_')
-  delimiter="${delimiter_prefix}_${normalized_uuid}"
+  normalized_suffix=$(printf '%s' "$random_suffix" | tr '[:lower:]-' '[:upper:]_')
+  delimiter="${delimiter_prefix}_${normalized_suffix}"
   if ! grep -Fq -- "$delimiter" "$payload_file"; then
     break
   fi

package/skills/github-issue/SKILL.md

@@ -55,7 +55,10 @@ repository.
    areas, validation, and external context. A discovered blocker does not widen implementation scope.
 4. Fetch the complete live taxonomy, including open projects. Apply matching existing labels and a
    selected existing milestone without separate approval. Select an existing open project for
-   cross-repo initiative work and a milestone for single-repo initiative work; an issue belongs to at
+   strategic, initiative-level tracking and a milestone for repo-local release or sequencing
+   tracking — the choice turns on the initiative's nature, not how many repositories it touches, so a
+   single-repo strategic initiative can carry a project, and an initiative that needs both a
+   cross-cutting strategic view and repo-local sequencing may carry both; an issue belongs to at
    most one project and not every issue needs one. Before adding an item, check its project
    membership and that of any item the project's own automation could pull in alongside it, such as
    a parent issue's sub-issues; skip the add and report the conflict if any of them already belongs

package/skills/review-github-issue-taxonomy/SKILL.md

@@ -14,8 +14,9 @@ local configuration edits or live taxonomy mutation; read local `AGENTS.md` and
    deletion, or rule change.
 3. Audit aliases, ambiguity, unused labels, missing descriptions, color consistency, milestone
    overlap, delivery gaps, and path-label coverage. Audit projects too: a milestone theme duplicated
-   across repositories is a candidate project, and a project confined to one repository is a
-   candidate milestone. Flag a project with no description, an empty or stale project, a closed
+   across repositories is a candidate project, and a project holding only routine, non-initiative
+   work — regardless of how many repositories it touches — is a candidate milestone; repository count
+   alone is not a miscategorization signal. Flag a project with no description, an empty or stale project, a closed
    project with open items, an issue that belongs to more than one project, and a project's own
    automation for auto-adding a parent issue's sub-issues left enabled where the at-most-one-project
    rule applies — it can silently duplicate membership.