@cleocode/core 2026.4.5 → 2026.4.7

package/src/scaffold.ts

@@ -12,14 +12,24 @@
 
 import { execFile } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
+import type { Dirent } from 'node:fs';
 import { existsSync, constants as fsConstants, readFileSync, statSync } from 'node:fs';
-import { access, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { access, copyFile, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { homedir as getHomedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
 import { generateProjectHash } from './nexus/hash.js';
-import { getCleoDirAbsolute, getCleoHome, getCleoTemplatesDir, getConfigPath } from './paths.js';
+import {
+  getCleoCantWorkflowsDir,
+  getCleoDirAbsolute,
+  getCleoGlobalAgentsDir,
+  getCleoGlobalRecipesDir,
+  getCleoHome,
+  getCleoPiExtensionsDir,
+  getCleoTemplatesDir,
+  getConfigPath,
+} from './paths.js';
 import { saveJson } from './store/json.js';
 
 const execFileAsync = promisify(execFile);
@@ -1334,7 +1344,15 @@ export function checkMemoryBridge(projectRoot: string): CheckResult {
  * Schemas are read at runtime from getPackageRoot()/schemas/ — no copy needed.
  * Project-level dirs (adrs/, rcasd/, agent-outputs/, backups/) live in .cleo/ only.
  */
-export const REQUIRED_GLOBAL_SUBDIRS = ['logs', 'templates'] as const;
+export const REQUIRED_GLOBAL_SUBDIRS = [
+  'logs',
+  'templates',
+  // CleoOS hub (Phase 1): cross-project recipe library, Pi extensions, CANT workflows
+  'global-recipes',
+  'pi-extensions',
+  'cant-workflows',
+  'agents',
+] as const;
 
 /**
  * Stale entries that must NOT exist at the global ~/.cleo/ level.
@@ -1532,11 +1550,229 @@ export async function ensureGlobalTemplates(): Promise<ScaffoldResult> {
 export async function ensureGlobalScaffold(): Promise<{
   home: ScaffoldResult;
   templates: ScaffoldResult;
+  cleoosHub: ScaffoldResult;
 }> {
   const home = await ensureGlobalHome();
   const templates = await ensureGlobalTemplates();
+  const cleoosHub = await ensureCleoOsHub();
+
+  return { home, templates, cleoosHub };
+}
+
+// ── CleoOS Hub scaffolding (Phase 1) ─────────────────────────────────
+
+/**
+ * Recursively copy a template tree from {@link srcDir} into {@link dstDir}.
+ *
+ * Never overwrites existing files: any file that already exists at the
+ * destination is left untouched, preserving user/agent edits. Missing
+ * subdirectories are created on demand. Symbolic links and special files
+ * are skipped silently.
+ *
+ * @param srcDir - Absolute path to the template source directory
+ * @param dstDir - Absolute path to the destination directory
+ * @returns Counts of files copied vs files that already existed and were kept
+ *
+ * @remarks
+ * Returns `{ copied: 0, kept: 0 }` if the source directory does not exist.
+ * Designed as the workhorse for {@link ensureCleoOsHub} and any other
+ * idempotent template scaffolding that ships with the npm package.
+ *
+ * @example
+ * ```typescript
+ * const { copied, kept } = await copyTemplateTree(
+ *   '/usr/lib/node_modules/@cleocode/cleo/templates/cleoos-hub/pi-extensions',
+ *   '/home/me/.local/share/cleo/pi-extensions',
+ * );
+ * console.log(`copied ${copied}, kept ${kept}`);
+ * ```
+ */
+async function copyTemplateTree(
+  srcDir: string,
+  dstDir: string,
+): Promise<{ copied: number; kept: number }> {
+  if (!existsSync(srcDir)) {
+    return { copied: 0, kept: 0 };
+  }
+
+  await mkdir(dstDir, { recursive: true });
+
+  let copied = 0;
+  let kept = 0;
+
+  let entries: Dirent[];
+  try {
+    entries = await readdir(srcDir, { withFileTypes: true });
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[CLEO] Could not read template dir ${srcDir}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return { copied: 0, kept: 0 };
+  }
+
+  for (const entry of entries) {
+    const srcPath = join(srcDir, entry.name);
+    const dstPath = join(dstDir, entry.name);
+
+    if (entry.isDirectory()) {
+      const sub = await copyTemplateTree(srcPath, dstPath);
+      copied += sub.copied;
+      kept += sub.kept;
+      continue;
+    }
+
+    if (!entry.isFile()) {
+      // Skip symlinks, sockets, devices, etc.
+      continue;
+    }
+
+    if (existsSync(dstPath)) {
+      kept += 1;
+      continue;
+    }
+
+    try {
+      await copyFile(srcPath, dstPath);
+      copied += 1;
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[CLEO] Could not copy template file ${srcPath} -> ${dstPath}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  return { copied, kept };
+}
+
+/**
+ * Resolve the absolute root directory of the bundled CleoOS hub templates.
+ *
+ * The templates ship inside the `@cleocode/cleo` package at
+ * `templates/cleoos-hub/`. Because `scaffold.ts` is authored in
+ * `@cleocode/core` but is also esbuilt directly into the `@cleocode/cleo`
+ * CLI bundle, the runtime location of `import.meta.url` (and therefore
+ * {@link getPackageRoot}) varies across deployment shapes. The candidate
+ * list below covers every layout we ship:
+ *
+ *   1. **Bundled cleo (npm install)** — `dist/cli/index.js` lives at
+ *      `node_modules/@cleocode/cleo/dist/cli/index.js`, so
+ *      `getPackageRoot()` resolves to `node_modules/@cleocode/cleo/dist`
+ *      and `../templates/cleoos-hub` reaches the package's templates dir.
+ *   2. **Bundled cleo (dev workspace via build.mjs)** — `dist/cli/index.js`
+ *      lives at `packages/cleo/dist/cli/index.js`; same `../templates/...`
+ *      candidate as above.
+ *   3. **Unbundled core (workspace tsc)** — scaffold.ts is loaded as
+ *      `packages/core/src/scaffold.ts`, so `getPackageRoot()` resolves to
+ *      `packages/core/` and `../cleo/templates/cleoos-hub` reaches the
+ *      sibling cleo package.
+ *   4. **Unbundled core (npm install of just @cleocode/core)** — the
+ *      scope-sibling layout puts both packages under
+ *      `node_modules/@cleocode/`, so the same `../cleo/templates/...`
+ *      candidate works.
+ *   5. **Legacy fallback** — if the cleo package ever bundles the templates
+ *      directly under core, fall through to
+ *      `getPackageRoot()/templates/cleoos-hub`.
+ *
+ * @returns Absolute path to the existing template root, or `null` if none found
+ *
+ * @remarks
+ * Returning `null` allows callers to skip the scaffold gracefully instead of
+ * crashing — important for the never-crash scaffold contract.
+ */
+function resolveCleoOsHubTemplateRoot(): string | null {
+  const packageRoot = getPackageRoot();
+  const candidates = [
+    // Bundled cleo: getPackageRoot() = .../@cleocode/cleo/dist
+    join(packageRoot, '..', 'templates', 'cleoos-hub'),
+    // Unbundled core in workspace or scope-sibling install
+    join(packageRoot, '..', 'cleo', 'templates', 'cleoos-hub'),
+    // Workspace from monorepo root resolution (defensive)
+    join(packageRoot, '..', '..', 'packages', 'cleo', 'templates', 'cleoos-hub'),
+    // Legacy in-place fallback
+    join(packageRoot, 'templates', 'cleoos-hub'),
+  ];
+  return candidates.find((p) => existsSync(p)) ?? null;
+}
+
+/**
+ * Ensure the CleoOS Hub subdirectories exist under the global CLEO home,
+ * and seed all bundled hub templates if they are not already present.
+ *
+ * This is the Phase 1 scaffolding entry point. Idempotent: re-running is
+ * safe and will never overwrite a file that already exists — human and
+ * agent edits to the installed copies are always preserved.
+ *
+ * @returns Scaffold result for the CleoOS hub root
+ *
+ * @remarks
+ * The CleoOS hub currently consists of:
+ *   - `global-recipes/` (Justfile Hub: justfile + README)
+ *   - `pi-extensions/`  (Pi extensions: orchestrator, stage-guide, cant-bridge)
+ *   - `cant-workflows/` (CANT workflow library — created empty for agents)
+ *   - `agents/`         (Global CANT agent definitions — created empty)
+ *
+ * Templates are sourced from the `@cleocode/cleo` package's bundled
+ * `templates/cleoos-hub/` tree. The directory is resolved at runtime through
+ * {@link resolveCleoOsHubTemplateRoot} so the same code path works in the
+ * monorepo workspace and in an installed npm package layout.
+ *
+ * @example
+ * ```typescript
+ * const result = await ensureCleoOsHub();
+ * console.log(result.action); // "created" or "skipped"
+ * ```
+ */
+export async function ensureCleoOsHub(): Promise<ScaffoldResult> {
+  const recipesDir = getCleoGlobalRecipesDir();
+  const piExtDir = getCleoPiExtensionsDir();
+  const cantWorkflowsDir = getCleoCantWorkflowsDir();
+  const agentsDir = getCleoGlobalAgentsDir();
+
+  // Always make sure the hub directory skeleton exists, even if templates
+  // can't be located (so downstream tools writing into them don't ENOENT).
+  try {
+    await mkdir(recipesDir, { recursive: true });
+    await mkdir(piExtDir, { recursive: true });
+    await mkdir(cantWorkflowsDir, { recursive: true });
+    await mkdir(agentsDir, { recursive: true });
+  } catch (err) {
+    return {
+      action: 'skipped',
+      path: recipesDir,
+      details: `Failed to create CleoOS hub directories: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  const templateRoot = resolveCleoOsHubTemplateRoot();
+  if (!templateRoot) {
+    return {
+      action: 'skipped',
+      path: recipesDir,
+      details: 'CleoOS hub template directory not found in any expected location',
+    };
+  }
 
-  return { home, templates };
+  let piResult: { copied: number; kept: number };
+  let recipesResult: { copied: number; kept: number };
+  try {
+    piResult = await copyTemplateTree(join(templateRoot, 'pi-extensions'), piExtDir);
+    recipesResult = await copyTemplateTree(join(templateRoot, 'global-recipes'), recipesDir);
+  } catch (err) {
+    return {
+      action: 'skipped',
+      path: recipesDir,
+      details: `Failed to seed CleoOS hub templates: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  const totalCopied = piResult.copied + recipesResult.copied;
+  return {
+    action: totalCopied > 0 ? 'created' : 'skipped',
+    path: recipesDir,
+    details: `pi-extensions: ${piResult.copied} created/${piResult.kept} kept, global-recipes: ${recipesResult.copied} created/${recipesResult.kept} kept`,
+  };
 }
 
 // ── Global check* functions (read-only diagnostics) ──────────────────

package/src/skills/dispatch.ts

@@ -4,7 +4,7 @@
  *
  * Implements multi-strategy dispatch:
  *   1. Label-based: task labels match skill tags
- *   2. Catalog-based: ct-skills dispatch matrix (via CAAMP catalog bridge)
+ *   2. Catalog-based: @cleocode/skills dispatch matrix (via CAAMP catalog bridge)
  *   3. Type-based: task type maps to protocol
  *   4. Keyword-based: title/description matches triggers
  *   5. Fallback: ct-task-executor
@@ -70,15 +70,15 @@ const TYPE_PROTOCOL_MAP: Record<string, { skill: string; protocol: SkillProtocol
 };
 
 // ============================================================================
-// Catalog Dispatch Matrix (from ct-skills via CAAMP)
+// Catalog Dispatch Matrix (from @cleocode/skills via CAAMP)
 // ============================================================================
 
-/** Cached dispatch matrix from the ct-skills catalog. */
+/** Cached dispatch matrix from the @cleocode/skills catalog. */
 let _catalogMatrix: CtDispatchMatrix | null = null;
 
 /**
  * Get the catalog dispatch matrix, caching on first access.
- * Returns null if ct-skills catalog is unavailable.
+ * Returns null if the @cleocode/skills catalog is unavailable.
  */
 function getCatalogMatrix(): CtDispatchMatrix | null {
   if (_catalogMatrix !== null) return _catalogMatrix;
@@ -123,7 +123,7 @@ function dispatchByLabels(task: Task, skills: Skill[]): DispatchResult | null {
 }
 
 /**
- * Attempt catalog-based dispatch: use ct-skills dispatch matrix.
+ * Attempt catalog-based dispatch: use the @cleocode/skills dispatch matrix.
  * Checks by_task_type and by_keyword from the catalog.
  * @task T4517
  */
@@ -220,7 +220,7 @@ export function autoDispatch(task: Task, cwd?: string): DispatchResult {
   const labelResult = dispatchByLabels(task, skills);
   if (labelResult) return labelResult;
 
-  // Strategy 2: Catalog-based (ct-skills dispatch matrix via CAAMP)
+  // Strategy 2: Catalog-based (@cleocode/skills dispatch matrix via CAAMP)
   const catalogResult = dispatchByCatalog(task);
   if (catalogResult) return catalogResult;
 

package/src/skills/skill-paths.ts

@@ -147,53 +147,57 @@ export function resolveSkillPath(skillName: string, projectRoot?: string): strin
 /**
  * Resolve a protocol .md file.
  *
- * Search order per base path:
- * 1. {base}/_ct-skills-protocols/{protocol_name}.md (Strategy B shared dir)
- * 2. {PROJECT_ROOT}/src/protocols/{protocol_name}.md (legacy embedded fallback)
+ * Search order:
+ * 1. `<core-package>/src/validation/protocols/protocols-markdown/{name}.md`
+ *    (canonical location, where the markdown lives in this monorepo)
+ * 2. `<base>/protocols/{name}.md` for each registered skill base path
+ *    (project-local protocol overrides)
  *
  * @task T4552
+ * @task T260 — drop dead Strategy B paths, point at the real protocols-markdown dir
  */
 export function resolveProtocolPath(protocolName: string, projectRoot?: string): string | null {
-  const searchPaths = getSkillSearchPaths(projectRoot);
+  // Canonical location in @cleocode/core
+  const root = getProjectRoot(projectRoot);
+  const canonical = join(
+    root,
+    'packages',
+    'core',
+    'src',
+    'validation',
+    'protocols',
+    'protocols-markdown',
+    `${protocolName}.md`,
+  );
+  if (existsSync(canonical)) {
+    return safeRealpath(canonical);
+  }
 
-  // Search Strategy B shared directories in each base path
+  // Per-skill-base override directory
+  const searchPaths = getSkillSearchPaths(projectRoot);
   for (const { path: searchPath } of searchPaths) {
-    const candidate = join(searchPath, '_ct-skills-protocols', `${protocolName}.md`);
+    const candidate = join(searchPath, 'protocols', `${protocolName}.md`);
     if (existsSync(candidate)) {
       return safeRealpath(candidate);
     }
   }
 
-  // Legacy fallback: project root protocols directory
-  const root = getProjectRoot(projectRoot);
-  const legacy = join(root, 'src', 'protocols', `${protocolName}.md`);
-  if (existsSync(legacy)) {
-    return safeRealpath(legacy);
-  }
-
   return null;
 }
 
 /**
  * Resolve a shared resource .md file.
  *
- * Search order per base path:
- * 1. {base}/_ct-skills-shared/{resource_name}.md (Strategy B shared dir)
- * 2. {base}/_shared/{resource_name}.md (legacy embedded layout)
+ * Search order per base path: `{base}/_shared/{resource_name}.md`. The
+ * `_shared/` directory is the canonical location in `@cleocode/skills`.
  *
  * @task T4552
+ * @task T260 — drop dead Strategy B path
  */
 export function resolveSharedPath(resourceName: string, projectRoot?: string): string | null {
   const searchPaths = getSkillSearchPaths(projectRoot);
 
   for (const { path: searchPath } of searchPaths) {
-    // Strategy B: _ct-skills-shared/ directory
-    const candidate = join(searchPath, '_ct-skills-shared', `${resourceName}.md`);
-    if (existsSync(candidate)) {
-      return safeRealpath(candidate);
-    }
-
-    // Legacy: _shared/ directory within each base path
     const legacy = join(searchPath, '_shared', `${resourceName}.md`);
     if (existsSync(legacy)) {
       return safeRealpath(legacy);

package/src/validation/protocols/_shared.ts

@@ -0,0 +1,88 @@
+/**
+ * Shared helpers for the per-protocol "load by task id" wrapper functions.
+ *
+ * The pure validators live in `orchestration/protocol-validators.ts` — this
+ * module is only about bridging the legacy taskId/manifestFile entry points
+ * (used by the CLI / dispatch layer) to those pure validators.
+ *
+ * @task T260
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { ExitCode } from '@cleocode/contracts';
+import { CleoError } from '../../errors.js';
+import type {
+  ManifestEntryInput,
+  ProtocolType,
+  ProtocolValidationResult,
+} from '../../orchestration/protocol-validators.js';
+import { PROTOCOL_EXIT_CODES } from '../../orchestration/protocol-validators.js';
+import { getManifestPath } from '../../paths.js';
+
+/**
+ * Locate the manifest line for a given task ID, reading from the end of the
+ * file so the most recent entry wins.
+ *
+ * @task T260
+ */
+export function findManifestEntry(taskId: string, manifestPath: string): string | null {
+  if (!existsSync(manifestPath)) return null;
+  const content = readFileSync(manifestPath, 'utf-8').trim();
+  if (content.length === 0) return null;
+  const lines = content.split('\n');
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (line && line.includes(`"${taskId}"`)) return line;
+  }
+  return null;
+}
+
+/**
+ * Load a manifest entry by task ID from the canonical manifest file.
+ *
+ * @task T260
+ */
+export function loadManifestEntryByTaskId(taskId: string): ManifestEntryInput {
+  const manifestPath = getManifestPath();
+  const entry = findManifestEntry(taskId, manifestPath);
+  if (!entry) {
+    throw new CleoError(ExitCode.NOT_FOUND, `No manifest entry found for task ${taskId}`);
+  }
+  return JSON.parse(entry) as ManifestEntryInput;
+}
+
+/**
+ * Load a manifest entry from an arbitrary JSON file (used by the `manifest`
+ * dispatch mode where the caller already has a serialized entry).
+ *
+ * @task T260
+ */
+export function loadManifestEntryFromFile(manifestFile: string): ManifestEntryInput {
+  if (!existsSync(manifestFile)) {
+    throw new CleoError(ExitCode.NOT_FOUND, `Manifest file not found: ${manifestFile}`);
+  }
+  return JSON.parse(readFileSync(manifestFile, 'utf-8')) as ManifestEntryInput;
+}
+
+/**
+ * Throw a CleoError with the protocol's canonical exit code when strict
+ * validation fails.
+ *
+ * @task T260
+ */
+export function throwIfStrictFailed(
+  result: ProtocolValidationResult,
+  opts: { strict?: boolean },
+  protocol: ProtocolType,
+  taskId: string,
+): void {
+  if (!opts.strict || result.valid) return;
+  const code = PROTOCOL_EXIT_CODES[protocol];
+  throw new CleoError(
+    code,
+    `${protocol} protocol violations for ${taskId}: ${result.violations
+      .filter((v) => v.severity === 'error')
+      .map((v) => v.message)
+      .join('; ')}`,
+  );
+}

package/src/validation/protocols/architecture-decision.ts

@@ -0,0 +1,52 @@
+/**
+ * Architecture Decision Record protocol — thin wrapper delegating to the
+ * canonical pure validator.
+ *
+ * This file fills a long-standing gap: every other CLEO pipeline stage had
+ * a TS validator, but the architecture_decision stage (added when RCSD was
+ * renamed to RCASD) never got one. The ADR markdown spec at
+ * `protocols-markdown/architecture-decision.md` defines ADR-001..008 MUST
+ * requirements — all enforced by the pure validator in
+ * `../../orchestration/protocol-validators.ts`.
+ *
+ * @task T260 — create the missing ADR protocol validator
+ */
+
+import {
+  type ArchitectureDecisionOptions,
+  type ManifestEntryInput,
+  type ProtocolValidationResult,
+  validateArchitectureDecisionProtocol,
+} from '../../orchestration/protocol-validators.js';
+import {
+  loadManifestEntryByTaskId,
+  loadManifestEntryFromFile,
+  throwIfStrictFailed,
+} from './_shared.js';
+
+/** Validate architecture-decision protocol for a task. */
+export async function validateArchitectureDecisionTask(
+  taskId: string,
+  opts: { strict?: boolean } & ArchitectureDecisionOptions,
+): Promise<ProtocolValidationResult> {
+  const entry = loadManifestEntryByTaskId(taskId) as ManifestEntryInput & {
+    consensus_manifest_id?: string;
+  };
+  const result = validateArchitectureDecisionProtocol(entry, opts);
+  throwIfStrictFailed(result, opts, 'architecture-decision', taskId);
+  return result;
+}
+
+/** Validate architecture-decision protocol from a manifest file. */
+export async function checkArchitectureDecisionManifest(
+  manifestFile: string,
+  opts: { strict?: boolean } & ArchitectureDecisionOptions,
+): Promise<ProtocolValidationResult> {
+  const entry = loadManifestEntryFromFile(manifestFile) as ManifestEntryInput & {
+    consensus_manifest_id?: string;
+  };
+  const taskId = entry.linked_tasks?.[0] ?? 'UNKNOWN';
+  const result = validateArchitectureDecisionProtocol(entry, opts);
+  throwIfStrictFailed(result, opts, 'architecture-decision', taskId);
+  return result;
+}

package/src/validation/protocols/artifact-publish.ts

@@ -0,0 +1,49 @@
+/**
+ * Artifact Publish protocol — thin wrapper delegating to the canonical pure validator.
+ *
+ * Artifact-publish is a cross-cutting protocol that composes with release:
+ * release triggers artifact-publish for the distribution phase (see release.md
+ * Pipeline Integration and release-engine.ts releaseShip()). Not every release
+ * needs artifact-publish — source-only releases can skip it.
+ *
+ * @task T260 — create the missing artifact-publish protocol wrapper
+ */
+
+import {
+  type ProtocolValidationResult,
+  validateArtifactPublishProtocol,
+} from '../../orchestration/protocol-validators.js';
+import {
+  loadManifestEntryByTaskId,
+  loadManifestEntryFromFile,
+  throwIfStrictFailed,
+} from './_shared.js';
+
+interface ArtifactPublishOpts {
+  strict?: boolean;
+  artifactType?: string;
+  buildPassed?: boolean;
+}
+
+/** Validate artifact-publish protocol for a task. */
+export async function validateArtifactPublishTask(
+  taskId: string,
+  opts: ArtifactPublishOpts,
+): Promise<ProtocolValidationResult> {
+  const entry = loadManifestEntryByTaskId(taskId);
+  const result = validateArtifactPublishProtocol(entry, opts);
+  throwIfStrictFailed(result, opts, 'artifact-publish', taskId);
+  return result;
+}
+
+/** Validate artifact-publish protocol from a manifest file. */
+export async function checkArtifactPublishManifest(
+  manifestFile: string,
+  opts: ArtifactPublishOpts,
+): Promise<ProtocolValidationResult> {
+  const entry = loadManifestEntryFromFile(manifestFile);
+  const taskId = entry.linked_tasks?.[0] ?? 'UNKNOWN';
+  const result = validateArtifactPublishProtocol(entry, opts);
+  throwIfStrictFailed(result, opts, 'artifact-publish', taskId);
+  return result;
+}