@cleocode/core 2026.4.5 → 2026.4.7

package/dist/validation/protocols/specification.d.ts

@@ -1,28 +1,18 @@
 /**
- * Specification protocol validation.
+ * Specification protocol — thin wrapper delegating to the canonical pure validator.
+ *
  * @task T4537
- * @epic T4454
+ * @task T260
  */
-interface ValidationResult {
-    valid: boolean;
-    violations: Array<{
-        code: string;
-        severity: string;
-        message: string;
-    }>;
-    score: number;
-    protocol: string;
-    taskId: string;
-}
+import { type ProtocolValidationResult } from '../../orchestration/protocol-validators.js';
 /** Validate specification protocol for a task. */
 export declare function validateSpecificationTask(taskId: string, opts: {
     strict?: boolean;
     specFile?: string;
-}): Promise<ValidationResult>;
-/** Validate specification protocol from manifest file. */
+}): Promise<ProtocolValidationResult>;
+/** Validate specification protocol from a manifest file. */
 export declare function checkSpecificationManifest(manifestFile: string, opts: {
     strict?: boolean;
     specFile?: string;
-}): Promise<ValidationResult>;
-export {};
+}): Promise<ProtocolValidationResult>;
 //# sourceMappingURL=specification.d.ts.map

package/dist/validation/protocols/specification.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"specification.d.ts","sourceRoot":"","sources":["../../../src/validation/protocols/specification.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,UAAU,gBAAgB;IACxB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAWD,kDAAkD;AAClD,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,OAAO,CAAC,gBAAgB,CAAC,CA4D3B;AAED,0DAA0D;AAC1D,wBAAsB,0BAA0B,CAC9C,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,OAAO,CAAC,gBAAgB,CAAC,CAO3B"}
+{"version":3,"file":"specification.d.ts","sourceRoot":"","sources":["../../../src/validation/protocols/specification.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,KAAK,wBAAwB,EAE9B,MAAM,4CAA4C,CAAC;AAOpD,kDAAkD;AAClD,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,OAAO,CAAC,wBAAwB,CAAC,CAOnC;AAED,4DAA4D;AAC5D,wBAAsB,0BAA0B,CAC9C,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,OAAO,CAAC,wBAAwB,CAAC,CAQnC"}

package/dist/validation/protocols/testing.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Testing protocol — thin wrapper delegating to the canonical pure validator.
+ *
+ * Renamed from testing-protocol.ts in T260. The testing protocol is the
+ * project-agnostic IVT loop closure stage: it checks that a detected test
+ * framework ran, achieved 100% pass rate, and the Implement→Validate→Test
+ * loop converged on the specification. Framework detection and loop logic
+ * live in the `ct-ivt-looper` skill; this validator only certifies results.
+ *
+ * @task T4804
+ * @task T260 — drop -protocol suffix, delegate, project-agnostic IVT
+ */
+import { type ProtocolValidationResult, type TestingOptions } from '../../orchestration/protocol-validators.js';
+/** Validate testing protocol for a task. */
+export declare function validateTestingTask(taskId: string, opts: {
+    strict?: boolean;
+} & TestingOptions): Promise<ProtocolValidationResult>;
+/** Validate testing protocol from a manifest file. */
+export declare function checkTestingManifest(manifestFile: string, opts: {
+    strict?: boolean;
+} & TestingOptions): Promise<ProtocolValidationResult>;
+//# sourceMappingURL=testing.d.ts.map

package/dist/validation/protocols/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../../src/validation/protocols/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EAEpB,MAAM,4CAA4C,CAAC;AAOpD,4CAA4C;AAC5C,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,cAAc,GAC1C,OAAO,CAAC,wBAAwB,CAAC,CAKnC;AAED,sDAAsD;AACtD,wBAAsB,oBAAoB,CACxC,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,cAAc,GAC1C,OAAO,CAAC,wBAAwB,CAAC,CAMnC"}

package/dist/validation/protocols/validation.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Validation protocol — thin wrapper delegating to the canonical pure validator.
+ *
+ * Renamed from validation-protocol.ts in T260. The validation stage runs
+ * static analysis, type checking, and pre-test quality gates. It is the
+ * first half of the IVT loop (Implement → Validate → Test); the validator
+ * here only verifies that a validation run produced a proper manifest
+ * entry — runtime gate enforcement is in the lifecycle state machine.
+ *
+ * @task T4804
+ * @task T260 — drop -protocol suffix, delegate to orchestration validator
+ */
+import { type ProtocolValidationResult, type ValidationStageOptions } from '../../orchestration/protocol-validators.js';
+/** Validate validation-stage protocol for a task. */
+export declare function validateValidationTask(taskId: string, opts: {
+    strict?: boolean;
+} & ValidationStageOptions): Promise<ProtocolValidationResult>;
+/** Validate validation-stage protocol from a manifest file. */
+export declare function checkValidationManifest(manifestFile: string, opts: {
+    strict?: boolean;
+} & ValidationStageOptions): Promise<ProtocolValidationResult>;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation/protocols/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/validation/protocols/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAE5B,MAAM,4CAA4C,CAAC;AAOpD,qDAAqD;AACrD,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,sBAAsB,GAClD,OAAO,CAAC,wBAAwB,CAAC,CAKnC;AAED,+DAA+D;AAC/D,wBAAsB,uBAAuB,CAC3C,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,sBAAsB,GAClD,OAAO,CAAC,wBAAwB,CAAC,CAMnC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/core",
-  "version": "2026.4.5",
+  "version": "2026.4.7",
   "description": "CLEO core business logic kernel — tasks, sessions, memory, orchestration, lifecycle, with bundled SQLite store",
   "type": "module",
   "main": "./dist/index.js",
@@ -35,12 +35,12 @@
     "write-file-atomic": "^6.0.0",
     "yaml": "^2.8.2",
     "zod": "^3.25.76",
-    "@cleocode/adapters": "2026.4.5",
-    "@cleocode/caamp": "2026.4.5",
-    "@cleocode/contracts": "2026.4.5",
-    "@cleocode/agents": "2026.4.5",
-    "@cleocode/lafs": "2026.4.5",
-    "@cleocode/skills": "2026.4.5"
+    "@cleocode/adapters": "2026.4.7",
+    "@cleocode/agents": "2026.4.7",
+    "@cleocode/contracts": "2026.4.7",
+    "@cleocode/caamp": "2026.4.7",
+    "@cleocode/lafs": "2026.4.7",
+    "@cleocode/skills": "2026.4.7"
   },
   "optionalDependencies": {
     "tree-sitter-c": "^0.24.1",

package/src/discovery.ts

@@ -0,0 +1,235 @@
+/**
+ * Greenfield/Brownfield project discovery & classification (Phase 5).
+ *
+ * Classifies a project directory as either:
+ *   - **greenfield**: empty or nearly-empty, no code, no git history
+ *   - **brownfield**: existing codebase with files, possibly git history
+ *
+ * Used by `cleo init` (Phase 5 bootstrap) to choose the correct seed
+ * pipeline:
+ *   - Greenfield → seed a Vision/PRD "research" epic so the agent starts
+ *     from a blank-slate planning posture
+ *   - Brownfield → invoke codebase mapping and anchor findings in BRAIN as
+ *     baseline context (per ULTRAPLAN §1 "Context Anchoring")
+ *
+ * Classification is intentionally simple and transparent — no heuristics,
+ * no ML, just file/directory presence checks. A project qualifies as
+ * brownfield if ANY of these are true:
+ *   - `.git/` directory exists (under a size threshold we still treat as
+ *     brownfield since history matters)
+ *   - source files exist under common source dirs (src, lib, app, packages)
+ *   - any manifest file exists (package.json, Cargo.toml, go.mod, pyproject.toml)
+ *   - markdown docs already exist (README.md, docs/)
+ *
+ * @task Phase 5 — Greenfield/brownfield bootstrap + context anchoring
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+/**
+ * Classification result for a project directory.
+ */
+export interface ProjectClassification {
+  /** Project type: 'greenfield' (empty/new) or 'brownfield' (existing). */
+  kind: 'greenfield' | 'brownfield';
+  /** Absolute path that was classified. */
+  directory: string;
+  /** Signal list — which indicators led to the classification. */
+  signals: ClassificationSignal[];
+  /** Total non-hidden files found at the top level (for reporting). */
+  topLevelFileCount: number;
+  /** Whether a `.git/` directory is present. */
+  hasGit: boolean;
+}
+
+/** A single classification signal detected on the filesystem. */
+export interface ClassificationSignal {
+  /** Canonical signal id for programmatic handling. */
+  id:
+    | 'git-dir'
+    | 'source-dir'
+    | 'package-manifest'
+    | 'docs'
+    | 'rust-manifest'
+    | 'go-manifest'
+    | 'python-manifest'
+    | 'readme'
+    | 'empty';
+  /** Human-readable description of what was detected. */
+  description: string;
+  /** File or directory that triggered this signal. */
+  path: string;
+}
+
+// ============================================================================
+// Detection helpers
+// ============================================================================
+
+/** Common source directory names that indicate an existing codebase. */
+const SOURCE_DIRS = ['src', 'lib', 'app', 'packages', 'crates', 'cmd', 'internal'];
+
+/** Manifest files that indicate a managed project. */
+const MANIFESTS: Array<{
+  file: string;
+  signal: ClassificationSignal['id'];
+  description: string;
+}> = [
+  { file: 'package.json', signal: 'package-manifest', description: 'Node.js manifest' },
+  { file: 'Cargo.toml', signal: 'rust-manifest', description: 'Rust manifest' },
+  { file: 'go.mod', signal: 'go-manifest', description: 'Go manifest' },
+  { file: 'pyproject.toml', signal: 'python-manifest', description: 'Python manifest (PEP 621)' },
+  { file: 'requirements.txt', signal: 'python-manifest', description: 'Python requirements.txt' },
+  { file: 'setup.py', signal: 'python-manifest', description: 'Python setup.py' },
+];
+
+/** Docs files/directories that indicate prior work. */
+const DOCS_MARKERS: Array<{ path: string; signal: ClassificationSignal['id'] }> = [
+  { path: 'README.md', signal: 'readme' },
+  { path: 'README.rst', signal: 'readme' },
+  { path: 'docs', signal: 'docs' },
+];
+
+/**
+ * Check if a directory (at the top level only) contains any files that are
+ * NOT part of the CLEO scaffolding itself. Used to decide whether the caller
+ * is about to `cleo init` into an already-populated directory.
+ */
+function countMeaningfulTopLevelFiles(directory: string): number {
+  if (!existsSync(directory)) return 0;
+  try {
+    const entries = readdirSync(directory);
+    let count = 0;
+    for (const entry of entries) {
+      // Ignore hidden files, the CLEO dir itself, and common CI/git debris
+      if (
+        entry.startsWith('.') ||
+        entry === '.cleo' ||
+        entry === 'node_modules' ||
+        entry === 'target' ||
+        entry === 'dist' ||
+        entry === 'build'
+      ) {
+        continue;
+      }
+      count += 1;
+    }
+    return count;
+  } catch {
+    return 0;
+  }
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Classify a project directory as greenfield or brownfield.
+ *
+ * Read-only — never mutates the filesystem. Safe to call at any time.
+ *
+ * @param directory - Absolute or relative path; defaults to process.cwd()
+ * @returns Classification result with signals and metadata
+ *
+ * @example
+ * ```typescript
+ * const classification = classifyProject('/my/project');
+ * if (classification.kind === 'greenfield') {
+ *   // Seed initial Vision epic
+ * } else {
+ *   // Run codebase mapping
+ * }
+ * ```
+ */
+export function classifyProject(directory?: string): ProjectClassification {
+  const root = resolve(directory ?? process.cwd());
+  const signals: ClassificationSignal[] = [];
+
+  // Signal 1: .git directory
+  const gitPath = join(root, '.git');
+  const hasGit = existsSync(gitPath);
+  if (hasGit) {
+    signals.push({
+      id: 'git-dir',
+      description: '.git/ directory present — project has version history',
+      path: gitPath,
+    });
+  }
+
+  // Signal 2: manifest files
+  for (const manifest of MANIFESTS) {
+    const manifestPath = join(root, manifest.file);
+    if (existsSync(manifestPath)) {
+      signals.push({
+        id: manifest.signal,
+        description: manifest.description,
+        path: manifestPath,
+      });
+    }
+  }
+
+  // Signal 3: common source directories
+  for (const dir of SOURCE_DIRS) {
+    const srcPath = join(root, dir);
+    if (existsSync(srcPath) && isNonEmptyDir(srcPath)) {
+      signals.push({
+        id: 'source-dir',
+        description: `Source directory ${dir}/ contains files`,
+        path: srcPath,
+      });
+      break; // One source-dir signal is enough
+    }
+  }
+
+  // Signal 4: docs / README
+  for (const marker of DOCS_MARKERS) {
+    const markerPath = join(root, marker.path);
+    if (existsSync(markerPath)) {
+      signals.push({
+        id: marker.signal,
+        description: `${marker.path} present`,
+        path: markerPath,
+      });
+      break;
+    }
+  }
+
+  const topLevelFileCount = countMeaningfulTopLevelFiles(root);
+
+  // Empty signal if we have nothing
+  if (signals.length === 0 && topLevelFileCount === 0) {
+    signals.push({
+      id: 'empty',
+      description: 'No source files, manifests, git history, or docs detected',
+      path: root,
+    });
+  }
+
+  // Classification rule: brownfield if ANY non-'empty' signal present
+  const kind: ProjectClassification['kind'] = signals.some((s) => s.id !== 'empty')
+    ? 'brownfield'
+    : 'greenfield';
+
+  return {
+    kind,
+    directory: root,
+    signals,
+    topLevelFileCount,
+    hasGit,
+  };
+}
+
+/**
+ * True if a directory exists AND contains at least one non-hidden entry.
+ */
+function isNonEmptyDir(dirPath: string): boolean {
+  try {
+    const stat = statSync(dirPath);
+    if (!stat.isDirectory()) return false;
+    const entries = readdirSync(dirPath).filter((e) => !e.startsWith('.'));
+    return entries.length > 0;
+  } catch {
+    return false;
+  }
+}

package/src/index.ts

@@ -173,6 +173,12 @@ export {
 } from './config.js';
 // Constants
 export { CORE_PROTECTED_FILES } from './constants.js';
+// Discovery (Phase 5)
+export {
+  type ClassificationSignal,
+  classifyProject,
+  type ProjectClassification,
+} from './discovery.js';
 // Engine result type (used by dispatch layer)
 export type { EngineResult } from './engine-result.js';
 export type { ErrorDefinition } from './error-catalog.js';
@@ -208,9 +214,18 @@ export { formatError, formatOutput, formatSuccess, pushWarning } from './output.
 export { createPage, paginate } from './pagination.js';
 // Paths
 export {
+  getCleoCacheDir,
+  getCleoCantWorkflowsDir,
+  getCleoConfigDir,
   getCleoDir,
   getCleoDirAbsolute,
+  getCleoGlobalAgentsDir,
+  getCleoGlobalJustfilePath,
+  getCleoGlobalRecipesDir,
   getCleoHome,
+  getCleoLogDir,
+  getCleoPiExtensionsDir,
+  getCleoTempDir,
   getCleoTemplatesTildePath,
   getConfigPath,
   getGlobalConfigPath,
@@ -233,6 +248,7 @@ export type { ProjectInfo } from './project-info.js';
 export { getProjectInfo, getProjectInfoSync, updateProjectName } from './project-info.js';
 // Scaffold
 export {
+  ensureCleoOsHub,
   ensureCleoStructure,
   ensureGlobalHome,
   ensureGlobalScaffold,

package/src/init.ts

@@ -37,6 +37,7 @@ import { copyFile, lstat, mkdir, readFile, symlink, unlink, writeFile } from 'no
 import { platform } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 import { ExitCode } from '@cleocode/contracts';
+import { classifyProject, type ProjectClassification } from './discovery.js';
 import { CleoError } from './errors.js';
 import { ensureGitHooks } from './hooks.js';
 import { ensureInjection } from './injection.js';
@@ -47,6 +48,7 @@ import { getAgentsHome, getCleoDirAbsolute, getProjectRoot } from './paths.js';
 import {
   ensureBrainDb,
   ensureCleoGitRepo,
+  ensureCleoOsHub,
   ensureCleoStructure,
   ensureConfig,
   ensureGitignore,
@@ -70,6 +72,16 @@ export interface InitOptions {
   detect?: boolean;
   /** Run codebase analysis and store findings to brain.db. */
   mapCodebase?: boolean;
+  /**
+   * Install canonical CleoOS seed agents (cleo-prime, cleo-dev, cleo-historian,
+   * cleo-rust-lead, cleo-db-lead, cleoos-opus-orchestrator) into the project's
+   * `.cleo/agents/` directory. Default: false (operator opts in).
+   *
+   * The seeds ship with `@cleocode/agents` under `seed-agents/`. Existing
+   * project files are never overwritten — operators are free to delete or
+   * fork any seed.
+   */
+  installSeedAgents?: boolean;
 }
 
 /** Result of the init operation. */
@@ -80,6 +92,22 @@ export interface InitResult {
   skipped: string[];
   warnings: string[];
   updateDocsOnly?: boolean;
+  /**
+   * Phase 5 — Greenfield/brownfield classification of the directory.
+   * Populated by the discovery module during init.
+   */
+  classification?: {
+    kind: 'greenfield' | 'brownfield';
+    signalCount: number;
+    topLevelFileCount: number;
+    hasGit: boolean;
+  };
+  /**
+   * Phase 5 — Next-step guidance for the agent/operator, emitted as a
+   * LAFS-compatible suggestion list. Each entry has an action description
+   * and a copy-pasteable command.
+   */
+  nextSteps?: Array<{ action: string; command: string }>;
 }
 
 // ── Helpers ──────────────────────────────────────────────────────────
@@ -93,6 +121,62 @@ const DIR_SYMLINK_TYPE: 'junction' | 'dir' = platform() === 'win32' ? 'junction'
 
 // ── Init-specific operations ─────────────────────────────────────────
 
+/**
+ * Resolve the absolute path to the bundled `seed-agents/` directory inside
+ * the `@cleocode/agents` package.
+ *
+ * Mirrors the multi-candidate resolution pattern used by
+ * {@link initAgentDefinition} so the same code path works across all layouts:
+ *   1. **npm install** — `require.resolve('@cleocode/agents/package.json')`
+ *      finds the package under `node_modules/@cleocode/agents/`.
+ *   2. **Workspace dev (bundled CLI)** — walks up from `getPackageRoot()`
+ *      (which resolves to `packages/cleo/dist/` or `packages/core/`) to find
+ *      `packages/agents/seed-agents/`.
+ *   3. **Monorepo dev (source)** — falls back to `packages/agents/seed-agents/`
+ *      relative to `getPackageRoot()`.
+ *
+ * @returns Absolute path to an existing `seed-agents/` directory, or `null`
+ *          if no candidate exists. Returning `null` lets callers skip the
+ *          seed install gracefully without crashing.
+ *
+ * @task T283
+ * @epic T280
+ */
+export async function resolveSeedAgentsDir(): Promise<string | null> {
+  // Primary: resolve via Node module resolution (@cleocode/agents)
+  try {
+    const { createRequire } = await import('node:module');
+    const req = createRequire(import.meta.url);
+    const agentsPkgMain = req.resolve('@cleocode/agents/package.json');
+    const agentsPkgRoot = dirname(agentsPkgMain);
+    const candidate = join(agentsPkgRoot, 'seed-agents');
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  } catch {
+    // Not resolvable via require.resolve — fall through to bundled path
+  }
+
+  // Walk a series of candidate paths relative to getPackageRoot(), which
+  // can resolve to several different locations depending on whether we're
+  // running from packages/core/dist, packages/cleo/dist, or installed under
+  // node_modules/@cleocode/.
+  const packageRoot = getPackageRoot();
+  const candidates = [
+    // Workspace fallback: bundled alongside core under packages/agents/seed-agents
+    join(packageRoot, 'agents', 'seed-agents'),
+    // Sibling-package layout (e.g. node_modules/@cleocode/core -> ../agents)
+    join(packageRoot, '..', 'agents', 'seed-agents'),
+    // Bundled CLI: packages/cleo/dist -> ../../agents/seed-agents
+    join(packageRoot, '..', '..', 'agents', 'seed-agents'),
+    // Bundled CLI dist subdir: packages/cleo/dist/cli -> ../../../packages/agents
+    join(packageRoot, '..', '..', 'packages', 'agents', 'seed-agents'),
+    // Monorepo workspace from repo root
+    join(packageRoot, '..', '..', '..', 'packages', 'agents', 'seed-agents'),
+  ];
+  return candidates.find((p) => existsSync(p)) ?? null;
+}
+
 /**
  * Install cleo-subagent agent definition to ~/.agents/agents/.
  * @task T4685
@@ -458,6 +542,17 @@ export async function initProject(opts: InitOptions = {}): Promise<InitResult> {
   const skipped: string[] = [];
   const warnings: string[] = [];
 
+  // Phase 5 — classify the directory BEFORE creating any files so the
+  // classification reflects the real pre-init state of the directory.
+  let classification: ProjectClassification | undefined;
+  try {
+    classification = classifyProject(projRoot);
+  } catch (err) {
+    warnings.push(
+      `Project classification failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
   // T4681: Create .cleo/ directory structure
   const structureResult = await ensureCleoStructure(projRoot);
   if (structureResult.action === 'created') {
@@ -724,12 +819,113 @@ export async function initProject(opts: InitOptions = {}): Promise<InitResult> {
     );
   }
 
+  // T283: Optional install of canonical CleoOS seed agent personas
+  if (opts.installSeedAgents) {
+    try {
+      const seedDir = await resolveSeedAgentsDir();
+      if (seedDir && existsSync(seedDir)) {
+        const targetDir = join(projRoot, '.cleo', 'agents');
+        await mkdir(targetDir, { recursive: true });
+        const seeds = readdirSync(seedDir).filter((f) => f.endsWith('.cant'));
+        let installed = 0;
+        for (const seed of seeds) {
+          const dst = join(targetDir, seed);
+          if (!existsSync(dst)) {
+            await copyFile(join(seedDir, seed), dst);
+            installed++;
+          }
+        }
+        if (installed > 0) {
+          created.push(`seed-agents: ${installed} canonical .cant personas installed`);
+        }
+      } else {
+        warnings.push('seed-agents install: bundled seed-agents/ directory not found');
+      }
+    } catch (err) {
+      warnings.push(
+        `seed-agents install failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  // ────────────────────────────────────────────────────────────────────
+  // Phase 5 — Finalize classification report + CleoOS hub bootstrap
+  // (Classification already ran at the TOP of init, before file creation)
+  // ────────────────────────────────────────────────────────────────────
+  if (classification) {
+    created.push(
+      `classification: ${classification.kind} (${classification.signals.length} signals)`,
+    );
+  }
+
+  // Ensure the CleoOS Hub exists globally (idempotent — only writes once)
+  try {
+    const hubResult = await ensureCleoOsHub();
+    if (hubResult.action === 'created') {
+      created.push(`cleoos-hub: ${hubResult.details ?? 'scaffolded'}`);
+    }
+  } catch (err) {
+    warnings.push(
+      `CleoOS hub scaffold failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  // Context anchoring: when brownfield and --map-codebase was NOT already run,
+  // surface a hint so the operator knows they can anchor the baseline in BRAIN.
+  // (We do NOT auto-run mapCodebase here — it's opt-in to avoid blocking init.)
+  if (classification?.kind === 'brownfield' && !opts.mapCodebase) {
+    warnings.push(
+      'Brownfield detected — run `cleo init --map-codebase` to anchor the existing codebase in BRAIN (Phase 5 context anchoring).',
+    );
+  }
+
+  // LAFS next-step guidance for autonomous agents
+  const nextSteps: Array<{ action: string; command: string }> =
+    classification?.kind === 'greenfield'
+      ? [
+          {
+            action: 'Start the session and record your first research findings',
+            command: 'cleo session start --scope global',
+          },
+          {
+            action: 'Create the seed epic for Vision/PRD research',
+            command: 'cleo add "Project vision and initial scope" --type epic',
+          },
+          {
+            action: 'Invoke the Conductor Loop once the seed epic is present',
+            command: 'pi /cleo:auto <seedEpicId>',
+          },
+        ]
+      : [
+          {
+            action: 'Anchor the existing codebase in BRAIN as baseline context',
+            command: 'cleo init --map-codebase',
+          },
+          {
+            action: 'Review the detected project context',
+            command: 'cleo admin paths',
+          },
+          {
+            action: 'Start a session scoped to the work you want to continue',
+            command: 'cleo session start --scope global',
+          },
+        ];
+
   return {
     initialized: true,
     directory: cleoDir,
     created,
     skipped,
     warnings,
+    classification: classification
+      ? {
+          kind: classification.kind,
+          signalCount: classification.signals.length,
+          topLevelFileCount: classification.topLevelFileCount,
+          hasGit: classification.hasGit,
+        }
+      : undefined,
+    nextSteps,
   };
 }