@powerhousedao/ph-clint-cli 0.1.0-dev.34 → 0.1.0-dev.36

package/dist/codegen/actions.d.ts

@@ -38,5 +38,5 @@ export interface PostGenActionResult {
     reason?: string;
     durationMs: number;
 }
-export declare function collectPostGenActions(result: GenerateProjectResult, spec: ClintProjectSpec): PostGenAction[];
+export declare function collectPostGenActions(result: GenerateProjectResult, spec: ClintProjectSpec): Promise<PostGenAction[]>;
 export declare function runPostGenActions(actions: PostGenAction[], ctx: PostGenActionContext): Promise<PostGenActionResult[]>;

package/dist/codegen/actions.js

@@ -7,6 +7,7 @@
  * `runPostGenActions()` executes them sequentially with proper ordering,
  * failure cascading, and log output.
  */
+import fs from 'node:fs/promises';
 import path from 'node:path';
 // ---------------------------------------------------------------------------
 // Fixed execution order — index defines precedence
@@ -45,9 +46,21 @@ function dependsOn(downstream, upstream) {
     return di > ui;
 }
 // ---------------------------------------------------------------------------
-// collectPostGenActions — pure function
+// Helpers
 // ---------------------------------------------------------------------------
-export function collectPostGenActions(result, spec) {
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// collectPostGenActions
+// ---------------------------------------------------------------------------
+export async function collectPostGenActions(result, spec) {
     const split = result.appDir !== null;
     const relPaths = new Set(result.files.map((f) => f.relativePath));
     // Determine the earliest triggered action in the chain
@@ -55,13 +68,21 @@ export function collectPostGenActions(result, spec) {
     if (split) {
         const appFolder = result.appDir ? path.basename(result.appDir) : '';
         const cliFolder = path.basename(result.cliDir);
-        // ph-init needed: app dir exists but no package.json (new scaffold)
+        // ph-init needed: app dir placeholder written but app not yet initialized.
+        // Check the actual filesystem — if package.json already exists on disk,
+        // ph init has already run and must not run again.
         const appPkgJsonChanged = relPaths.has(path.join(appFolder, 'package.json'));
-        // Check for the .gitkeep — signals a new app dir that needs ph-init
         const appGitkeepWritten = relPaths.has(path.join(appFolder, '.gitkeep'));
+        // ph-init needed: app dir placeholder written but app not yet initialized.
+        // Check the actual filesystem — if package.json already exists on disk,
+        // ph init has already run and must not run again.
         if (appGitkeepWritten && !appPkgJsonChanged) {
-            // .gitkeep written but no package.json — app needs ph init
-            earliest = 'ph-init';
+            const appAlreadyInitialized = result.appDir
+                ? await fileExists(path.join(result.appDir, 'package.json'))
+                : false;
+            if (!appAlreadyInitialized) {
+                earliest = 'ph-init';
+            }
         }
         // Migration always triggers full rebuild
         if (result.migrated) {
@@ -87,11 +108,11 @@ export function collectPostGenActions(result, spec) {
                 earliest = 'cli-install';
             }
         }
-        // CLI source regenerated (.ts files)
+        // CLI source or prompts regenerated (.ts files, agent profile .md files)
         if (!earliest) {
             for (const rel of relPaths) {
                 if (rel.startsWith(cliFolder + '/') &&
-                    rel.endsWith('.ts')) {
+                    (rel.endsWith('.ts') || rel.endsWith('.md'))) {
                     earliest = 'cli-build';
                     break;
                 }
@@ -285,6 +306,15 @@ async function executeAction(action, ctx) {
                 ctx.log(`      ${result.reason ?? 'ph init did not run'}`);
                 return false;
             }
+            if (result.exitCode === 0) {
+                // Mark app as initialized in generated state
+                const { readGeneratedState, writeGeneratedState } = await import('./generated.js');
+                const gen = await readGeneratedState(action.targetDir);
+                if (gen) {
+                    gen.appInitialized = true;
+                    await writeGeneratedState(action.targetDir, gen);
+                }
+            }
             return result.exitCode === 0;
         }
         case 'app-install':

package/dist/codegen/generated.d.ts

@@ -0,0 +1,17 @@
+import { type ClintProjectSpec } from '../spec/types.js';
+export interface GeneratedState {
+    name: string;
+    scope: string | undefined;
+    cliFolderName: string;
+    appFolderName: string;
+    /** True once `ph init` has run successfully in the app dir. */
+    appInitialized: boolean;
+}
+export declare function getGeneratedPath(targetDir: string): string;
+export declare function readGeneratedState(targetDir: string): Promise<GeneratedState | null>;
+export declare function writeGeneratedState(targetDir: string, state: GeneratedState): Promise<void>;
+/**
+ * Derive a `GeneratedState` from a spec. The `appInitialized` flag must be
+ * supplied by the caller (it depends on filesystem state, not the spec).
+ */
+export declare function generatedStateFromSpec(spec: ClintProjectSpec, appInitialized: boolean): GeneratedState;

package/dist/codegen/generated.js

@@ -0,0 +1,49 @@
+/**
+ * Tracks the derived state from the last successful code generation.
+ *
+ * Stored at `{targetDir}/.ph/ph-clint-cli/generated.json`. Used to detect
+ * folder renames (name/scope changes) and re-apply patches that depend on
+ * the project identity.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { getAppFolderName, getCliFolderName, } from '../spec/types.js';
+const GEN_DIR = path.join('.ph', 'ph-clint-cli');
+const GEN_FILE = 'generated.json';
+export function getGeneratedPath(targetDir) {
+    return path.join(targetDir, GEN_DIR, GEN_FILE);
+}
+export async function readGeneratedState(targetDir) {
+    try {
+        const raw = await fs.readFile(getGeneratedPath(targetDir), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (err &&
+            typeof err === 'object' &&
+            'code' in err &&
+            err.code === 'ENOENT') {
+            return null;
+        }
+        throw err;
+    }
+}
+export async function writeGeneratedState(targetDir, state) {
+    const file = getGeneratedPath(targetDir);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, JSON.stringify(state, null, 2) + '\n', 'utf8');
+}
+/**
+ * Derive a `GeneratedState` from a spec. The `appInitialized` flag must be
+ * supplied by the caller (it depends on filesystem state, not the spec).
+ */
+export function generatedStateFromSpec(spec, appInitialized) {
+    const split = spec.features.powerhouse !== 'Disabled';
+    return {
+        name: spec.name,
+        scope: spec.scope,
+        cliFolderName: split ? getCliFolderName(spec) : '',
+        appFolderName: split ? getAppFolderName(spec) : '',
+        appInitialized,
+    };
+}

package/dist/codegen/index.js

@@ -37,6 +37,8 @@ import { writeFileEnsuringDir, isDirEmptyEnough } from './write.js';
 import { migrateFlatToSplit } from './migrate/flat-to-split.js';
 import { CLI_FILE_BUILDERS, getProfileFileBuilders, buildReadme, buildRootPackageJson, buildPublishConfigJs, buildAppIndexTs, } from './builders/index.js';
 import { collectPostGenActions, } from './actions.js';
+import { readGeneratedState, writeGeneratedState, generatedStateFromSpec, } from './generated.js';
+import { patchAppPackageName } from './scaffold.js';
 /**
  * Generate / reconcile a project at `targetDir` from the given spec.
  */
@@ -156,6 +158,82 @@ function buildAppReadmeContent(spec) {
         '',
     ].join('\n');
 }
+// ---------------------------------------------------------------------------
+// Folder rename handling
+// ---------------------------------------------------------------------------
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Detect and execute folder renames when the project name changes.
+ *
+ * Reads the previous `GeneratedState` to find the old folder names, compares
+ * with the new spec's folder names. If they differ:
+ *   1. Renames the directories on disk.
+ *   2. Rewrites hash-record keys from old → new prefixes.
+ *
+ * Must run BEFORE `planFiles()` so the reconciliation loop sees the files
+ * in their new locations.
+ */
+async function handleFolderRename(targetDir, spec, prev, warn) {
+    const split = spec.features.powerhouse !== 'Disabled';
+    if (!split || !prev || !prev.cliFolderName) {
+        return { renamed: false, appInitialized: prev?.appInitialized ?? false };
+    }
+    const newCliFolder = getCliFolderName(spec);
+    const newAppFolder = getAppFolderName(spec);
+    const oldCliFolder = prev.cliFolderName;
+    const oldAppFolder = prev.appFolderName;
+    if (oldCliFolder === newCliFolder && oldAppFolder === newAppFolder) {
+        return { renamed: false, appInitialized: prev.appInitialized };
+    }
+    // Rename CLI folder
+    if (oldCliFolder !== newCliFolder) {
+        const oldPath = path.join(targetDir, oldCliFolder);
+        const newPath = path.join(targetDir, newCliFolder);
+        if (await fileExists(oldPath)) {
+            if (await fileExists(newPath)) {
+                warn(`cannot rename ${oldCliFolder} → ${newCliFolder}: target already exists`);
+                return { renamed: false, appInitialized: prev.appInitialized };
+            }
+            await fs.rename(oldPath, newPath);
+        }
+    }
+    // Rename app folder
+    if (oldAppFolder !== newAppFolder) {
+        const oldPath = path.join(targetDir, oldAppFolder);
+        const newPath = path.join(targetDir, newAppFolder);
+        if (await fileExists(oldPath)) {
+            if (await fileExists(newPath)) {
+                warn(`cannot rename ${oldAppFolder} → ${newAppFolder}: target already exists`);
+                return { renamed: false, appInitialized: prev.appInitialized };
+            }
+            await fs.rename(oldPath, newPath);
+        }
+    }
+    // Rewrite hash keys from old folder prefixes to new ones
+    const hashes = await readHashes(targetDir);
+    const remapped = {};
+    for (const [key, value] of Object.entries(hashes)) {
+        let newKey = key;
+        if (oldCliFolder !== newCliFolder && key.startsWith(oldCliFolder + '/')) {
+            newKey = newCliFolder + key.slice(oldCliFolder.length);
+        }
+        else if (oldAppFolder !== newAppFolder &&
+            key.startsWith(oldAppFolder + '/')) {
+            newKey = newAppFolder + key.slice(oldAppFolder.length);
+        }
+        remapped[newKey] = value;
+    }
+    await writeHashes(targetDir, remapped);
+    return { renamed: true, appInitialized: prev.appInitialized };
+}
 /** Create mode — empty target dir, write everything fresh. */
 async function runCreate(options, _warn) {
     const { targetDir, spec } = options;
@@ -179,6 +257,8 @@ async function runCreate(options, _warn) {
         relativePath: path.relative(targetDir, getSpecPath(targetDir)),
     });
     await writeHashes(targetDir, hashes);
+    // App is not yet initialized on create — ph-init runs as a post-gen action.
+    await writeGeneratedState(targetDir, generatedStateFromSpec(spec, false));
     const result = {
         mode: 'create',
         files,
@@ -189,13 +269,16 @@ async function runCreate(options, _warn) {
         appDir,
         pendingActions: [],
     };
-    result.pendingActions = collectPostGenActions(result, spec);
+    result.pendingActions = await collectPostGenActions(result, spec);
     return result;
 }
 /** Update mode — reconcile against an existing project. */
 async function runUpdate(options, warn, migrated) {
     const { targetDir, spec } = options;
     const force = !!options.force;
+    // --- Folder rename detection ---
+    const prev = await readGeneratedState(targetDir);
+    const { renamed, appInitialized: appWasInitialized } = await handleFolderRename(targetDir, spec, prev, warn);
     const { planned, cliDir, appDir } = planFiles(spec, targetDir);
     const plannedByKey = new Map(planned.map((p) => [p.relativePath, p]));
     const previous = await readHashes(targetDir);
@@ -299,6 +382,26 @@ async function runUpdate(options, warn, migrated) {
     }
     await writeProjectSpec(targetDir, spec);
     await writeHashes(targetDir, next);
+    // Re-patch app package.json if name or scope changed and app is initialized.
+    // Add to `files` so collectPostGenActions sees the change and triggers
+    // app-install → app-build → cli-install → cli-build.
+    const appIsInitialized = appDir
+        ? await fileExists(path.join(appDir, 'package.json'))
+        : false;
+    const nameOrScopeChanged = prev
+        ? prev.name !== spec.name || prev.scope !== spec.scope
+        : false;
+    if (appDir && appIsInitialized && nameOrScopeChanged) {
+        const patched = await patchAppPackageName(appDir, spec, warn);
+        if (patched) {
+            const appFolder = path.basename(appDir);
+            files.push({
+                absolutePath: path.join(appDir, 'package.json'),
+                relativePath: path.join(appFolder, 'package.json'),
+            });
+        }
+    }
+    await writeGeneratedState(targetDir, generatedStateFromSpec(spec, appIsInitialized));
     const result = {
         mode: 'update',
         files,
@@ -309,6 +412,6 @@ async function runUpdate(options, warn, migrated) {
         appDir,
         pendingActions: [],
     };
-    result.pendingActions = collectPostGenActions(result, spec);
+    result.pendingActions = await collectPostGenActions(result, spec);
     return result;
 }

package/dist/codegen/scaffold.d.ts

@@ -34,6 +34,16 @@ export interface PhInitResult {
  */
 export declare function getPhVersion(binName: string): string | undefined;
 export declare function runPhInit(options: PhInitOptions): Promise<PhInitResult>;
+/**
+ * Patch the app `package.json` name to the scoped form (`@scope/name-app`).
+ * Called after `ph init` and after name/scope renames.
+ *
+ * Returns `true` if the file was actually changed.
+ */
+export declare function patchAppPackageName(appDir: string, spec: {
+    name: string;
+    scope?: string;
+}, log?: (msg: string) => void): Promise<boolean>;
 export interface PnpmInstallOptions {
     /** Directories to run `pnpm install` in, in order. */
     dirs: string[];

package/dist/codegen/scaffold.js

@@ -31,6 +31,15 @@ export async function runPhInit(options) {
     const log = options.log ?? (() => { });
     const binName = options.binName ?? 'ph';
     const appFolder = path.basename(options.appDir);
+    // Guard: never re-init an already-initialized app directory.
+    try {
+        await fs.access(path.join(options.appDir, 'package.json'));
+        log(`App directory ${appFolder} already initialized — skipping ph init.`);
+        return { ran: false, reason: 'already-initialized' };
+    }
+    catch {
+        // No package.json — proceed with init.
+    }
     if (!(await hasCommandOnPath(binName))) {
         log(`Skipping \`${binName} init\` — \`${binName}\` is not on PATH. ` +
             `Install @powerhousedao/ph-cli and re-run manually inside ${appFolder}/.`);
@@ -76,25 +85,40 @@ export async function runPhInit(options) {
     await patchScopedName(options, appFolder, log);
     return { ran: true, exitCode: result.exitCode };
 }
-async function patchScopedName(options, appFolder, log) {
-    if (!options.spec.scope)
-        return;
-    const appPkgJsonPath = path.join(options.appDir, 'package.json');
+/**
+ * Patch the app `package.json` name to the scoped form (`@scope/name-app`).
+ * Called after `ph init` and after name/scope renames.
+ *
+ * Returns `true` if the file was actually changed.
+ */
+export async function patchAppPackageName(appDir, spec, log) {
+    const appFolder = path.basename(appDir);
+    const scopedName = spec.scope
+        ? `@${spec.scope}/${appFolder}`
+        : appFolder;
+    const appPkgJsonPath = path.join(appDir, 'package.json');
     try {
         const raw = await fs.readFile(appPkgJsonPath, 'utf8');
         const pkg = JSON.parse(raw);
-        const scopedName = `@${options.spec.scope}/${appFolder}`;
         if (pkg.name !== scopedName) {
             pkg.name = scopedName;
-            pkg.publishConfig = { access: 'public' };
+            if (spec.scope) {
+                pkg.publishConfig = { access: 'public' };
+            }
             await fs.writeFile(appPkgJsonPath, JSON.stringify(pkg, null, 2) + '\n');
-            log(`Patched app package name to ${scopedName}`);
+            log?.(`Patched app package name to ${scopedName}`);
+            return true;
         }
+        return false;
     }
     catch (err) {
-        log(`Warning: could not patch app package name: ${err instanceof Error ? err.message : String(err)}`);
+        log?.(`Warning: could not patch app package name: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
     }
 }
+async function patchScopedName(options, _appFolder, log) {
+    await patchAppPackageName(options.appDir, options.spec, log);
+}
 export async function runPnpmInstall(options) {
     const log = options.log ?? (() => { });
     const binName = options.binName ?? 'pnpm';

package/dist/commands/clint-project-init.js

@@ -13,14 +13,12 @@
  */
 import path from 'node:path';
 import { defineCommand } from '@powerhousedao/ph-clint';
-import { importSpec } from '@powerhousedao/ph-clint-app/document-models/ph-clint-project';
 import { z } from 'zod';
 import { clintProjectSpecSchema, } from '../spec/types.js';
 import { generateProject } from '../codegen/index.js';
 import { isDirEmptyEnough } from '../codegen/write.js';
 import { runPostGenActions } from '../codegen/actions.js';
-import { writeProjectSpec } from '../spec/file.js';
-import { specToImportInput } from '../triggers/spec-change.js';
+import { ensureSpecDocument } from '../spec/ensure-document.js';
 const inputSchema = z.object({
     dir: z
         .string()
@@ -127,14 +125,9 @@ export const init = defineCommand({
             try {
                 const reactor = await getReactor();
                 if (reactor) {
-                    const newDoc = await reactor.client.createEmpty('powerhouse/ph-clint-project');
-                    const docId = newDoc.header.id;
-                    await folders.addDocument(docId, `specs/${spec.name}`, spec.name);
-                    const importInput = specToImportInput(spec);
-                    await reactor.client.execute(docId, 'main', [importSpec(importInput)]);
-                    spec.documentId = docId;
-                    spec.documentType = 'powerhouse/ph-clint-project';
-                    await writeProjectSpec(targetDir, spec);
+                    const { docId } = await ensureSpecDocument({
+                        spec, targetDir, reactor, folders,
+                    });
                     stdout(`Created spec document ${docId} in Clint Folders/specs/${spec.name}\n`);
                 }
             }

package/dist/commands/clint-project-regen.js

@@ -12,6 +12,7 @@ import { z } from 'zod';
 import { readProjectSpec } from '../spec/file.js';
 import { generateProject } from '../codegen/index.js';
 import { runPostGenActions } from '../codegen/actions.js';
+import { ensureSpecDocument } from '../spec/ensure-document.js';
 const inputSchema = z.object({
     dir: z
         .string()
@@ -26,7 +27,7 @@ export const regen = defineCommand({
     id: 'clint-project-regen',
     description: 'Regenerate project files from the persisted spec',
     inputSchema,
-    execute: async (input, { workdir, stdout, log, runProcess }) => {
+    execute: async (input, { workdir, stdout, log, runProcess, reactor: getReactor, folders }) => {
         const targetDir = path.resolve(workdir, input.dir ?? '.');
         const spec = await readProjectSpec(targetDir);
         if (!spec) {
@@ -53,6 +54,23 @@ export const regen = defineCommand({
             else
                 stdout('warning: ' + w + '\n');
         }
+        // Ensure spec document exists in drive (recover if deleted)
+        if (getReactor && folders) {
+            try {
+                const reactor = await getReactor();
+                if (reactor) {
+                    const { docId, created } = await ensureSpecDocument({
+                        spec, targetDir, reactor, folders,
+                    });
+                    if (created) {
+                        lines.push(`Created spec document ${docId} in Clint Folders/specs/${spec.name}`);
+                    }
+                }
+            }
+            catch (err) {
+                log?.warn(`Could not ensure spec document: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
         stdout(lines.join('\n') + '\n');
         // Run post-generation actions (install, build, skills-sync).
         await runPostGenActions(result.pendingActions, {

package/dist/spec/ensure-document.d.ts

@@ -0,0 +1,17 @@
+import type { FolderOperations } from '@powerhousedao/ph-clint';
+import type { ReactorContext, DocumentRegistry } from '@powerhousedao/ph-clint';
+import type { ClintProjectSpec } from './types.js';
+export interface EnsureSpecDocumentResult {
+    docId: string;
+    created: boolean;
+}
+/**
+ * Ensure the spec document exists in the personal drive. Creates one if
+ * missing or if the existing `documentId` no longer resolves to a drive node.
+ */
+export declare function ensureSpecDocument<R extends DocumentRegistry = DocumentRegistry>(opts: {
+    spec: ClintProjectSpec;
+    targetDir: string;
+    reactor: ReactorContext<R>;
+    folders: FolderOperations;
+}): Promise<EnsureSpecDocumentResult>;

package/dist/spec/ensure-document.js

@@ -0,0 +1,62 @@
+/**
+ * Ensure a ph-clint-project spec document exists in the personal drive.
+ *
+ * Single code path used by:
+ *   - `clint-project-init` (after scaffolding)
+ *   - `clint-project-regen` (recover deleted docs)
+ *   - `spec-change` trigger (auto-link unlinked projects)
+ *
+ * If the spec already has a `documentId` that exists in the drive, this is
+ * a no-op. If the document was deleted (or never created), a new one is
+ * created, added to the drive at `specs/{name}`, and the spec JSON on disk
+ * is updated with the new `documentId`.
+ */
+import { importSpec } from '@powerhousedao/ph-clint-app/document-models/ph-clint-project';
+import { writeProjectSpec } from './file.js';
+import { specToImportInput } from '../triggers/spec-change.js';
+const DOCUMENT_TYPE = 'powerhouse/ph-clint-project';
+/**
+ * Ensure the spec document exists in the personal drive. Creates one if
+ * missing or if the existing `documentId` no longer resolves to a drive node.
+ */
+export async function ensureSpecDocument(opts) {
+    const { spec, targetDir, reactor, folders } = opts;
+    // Check if the document already exists in the drive's folder tree
+    if (spec.documentId) {
+        const entries = await folders.findByType(DOCUMENT_TYPE);
+        const inDrive = entries.some((e) => e.id === spec.documentId);
+        if (inDrive)
+            return { docId: spec.documentId, created: false };
+    }
+    // Reuse existing document if it's still in the reactor, otherwise create new
+    let docId;
+    if (spec.documentId) {
+        try {
+            const existing = await reactor.client.get(spec.documentId);
+            if (existing) {
+                docId = spec.documentId;
+            }
+            else {
+                const newDoc = await reactor.client.createEmpty(DOCUMENT_TYPE);
+                docId = newDoc.header.id;
+            }
+        }
+        catch {
+            const newDoc = await reactor.client.createEmpty(DOCUMENT_TYPE);
+            docId = newDoc.header.id;
+        }
+    }
+    else {
+        const newDoc = await reactor.client.createEmpty(DOCUMENT_TYPE);
+        docId = newDoc.header.id;
+    }
+    // Add to the drive's folder tree
+    await folders.addDocument(docId, `specs/${spec.name}`, spec.name);
+    const importInput = specToImportInput(spec);
+    await reactor.client.execute(docId, 'main', [importSpec(importInput)]);
+    // Persist the link back to disk
+    spec.documentId = docId;
+    spec.documentType = DOCUMENT_TYPE;
+    await writeProjectSpec(targetDir, spec);
+    return { docId, created: true };
+}

package/dist/triggers/spec-change.js

@@ -17,12 +17,12 @@ import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { scanProjects, getProjectMapping } from '@powerhousedao/ph-clint';
-import { importSpec } from '@powerhousedao/ph-clint-app/document-models/ph-clint-project';
 import { createDocumentChangeTrigger } from '../framework.js';
 import { generateProject } from '../codegen/index.js';
 import { runPostGenActions } from '../codegen/actions.js';
 import { specFromDocumentState } from '../spec/from-document.js';
 import { readProjectSpec, writeProjectSpec } from '../spec/file.js';
+import { ensureSpecDocument } from '../spec/ensure-document.js';
 import { clintProject } from '../services/clint-project.js';
 const DOCUMENT_TYPE = 'powerhouse/ph-clint-project';
 const HASH_DIR = path.join('.ph', 'ph-clint-cli');
@@ -121,24 +121,28 @@ export const specChangeTrigger = createDocumentChangeTrigger({
             ? scanProjects(ctx.context.workdir, scanner)
             : [];
         const mapping = await getProjectMapping(scanResults, folders);
-        // Auto-create spec documents for unlinked projects
+        // Auto-create spec documents for unlinked or orphaned projects
         const reactor = await ctx.reactor();
         if (reactor && folders) {
             for (const entry of mapping) {
-                if (entry.path && !entry.documentId) {
-                    const existingSpec = await readProjectSpec(entry.path);
-                    if (!existingSpec)
-                        continue;
-                    log?.info(`${TAG} creating spec document for unlinked project ${entry.name}`);
-                    const newDoc = await reactor.client.createEmpty('powerhouse/ph-clint-project');
-                    const docId = newDoc.header.id;
-                    await folders.addDocument(docId, `specs/${entry.name}`, entry.name);
-                    const importInput = specToImportInput(existingSpec);
-                    await reactor.client.execute(docId, 'main', [importSpec(importInput)]);
-                    existingSpec.documentId = docId;
-                    existingSpec.documentType = 'powerhouse/ph-clint-project';
-                    await writeProjectSpec(entry.path, existingSpec);
-                    log?.info(`${TAG} linked project ${entry.name} to document ${docId}`);
+                if (!entry.path)
+                    continue;
+                const existingSpec = await readProjectSpec(entry.path);
+                if (!existingSpec)
+                    continue;
+                try {
+                    const { docId, created } = await ensureSpecDocument({
+                        spec: existingSpec,
+                        targetDir: entry.path,
+                        reactor,
+                        folders,
+                    });
+                    if (created) {
+                        log?.info(`${TAG} linked project ${entry.name} to document ${docId}`);
+                    }
+                }
+                catch (err) {
+                    log?.warn(`${TAG} could not ensure spec document for ${entry.name}: ${err instanceof Error ? err.message : String(err)}`);
                 }
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@powerhousedao/ph-clint-cli",
-  "version": "0.1.0-dev.34",
+  "version": "0.1.0-dev.36",
   "publishConfig": {
     "access": "public"
   },
@@ -29,9 +29,9 @@
     "@mastra/core": "^1.22.0",
     "@mastra/libsql": "^1.7.4",
     "@mastra/memory": "^1.13.1",
-    "@powerhousedao/ph-clint": "^0.1.0-dev.34",
-    "@powerhousedao/ph-clint-app": "^0.1.0-dev.34",
-    "@powerhousedao/ph-clint-dev": "^0.1.0-dev.34",
+    "@powerhousedao/ph-clint": "^0.1.0-dev.36",
+    "@powerhousedao/ph-clint-app": "^0.1.0-dev.36",
+    "@powerhousedao/ph-clint-dev": "^0.1.0-dev.36",
     "@powerhousedao/reactor": "6.0.0-dev.170",
     "@powerhousedao/reactor-api": "6.0.0-dev.170",
     "@powerhousedao/shared": "6.0.0-dev.170",