@codyswann/lisa 2.217.8 → 2.219.0

package/dist/core/learnings-lock.js

@@ -0,0 +1,227 @@
+/** Cross-process serialization for project learnings writes. */
+import { link, lstat, readFile, unlink, writeFile } from "node:fs/promises";
+const MAX_LOCK_ATTEMPTS = 200;
+const LOCK_RETRY_DELAY_MS = 10;
+const STALE_LOCK_MS = 30_000;
+/**
+ * Serialize same-target writers across processes with an exclusive hard link.
+ * @param target - Absolute learnings target
+ * @param operation - Complete read, validate, and atomic-write transaction
+ * @returns Operation result
+ */
+export async function withLearningTargetLock(target, operation) {
+    const lockPath = `${target}.lock`;
+    const owner = {
+        token: crypto.randomUUID(),
+        pid: process.pid,
+        createdAt: Date.now(),
+    };
+    const lease = await acquireLock(lockPath, owner, 0);
+    try {
+        return await operation();
+    }
+    finally {
+        await releaseLock(lockPath, lease);
+    }
+}
+/**
+ * Publish complete owner metadata atomically via a hard link.
+ * @param lockPath - Shared lock path
+ * @param owner - Unique owner metadata
+ * @param attempt - Current retry count
+ * @returns Acquired lock lease
+ */
+async function acquireLock(lockPath, owner, attempt) {
+    const ownerPath = `${lockPath}.${owner.token}.owner`;
+    await writeFile(ownerPath, JSON.stringify(owner), {
+        encoding: "utf8",
+        flag: "wx",
+    });
+    const acquired = await publishOwnerLink(ownerPath, lockPath);
+    if (acquired) {
+        return { owner, ownerPath };
+    }
+    await removeFileIfPresent(ownerPath);
+    if (attempt >= MAX_LOCK_ATTEMPTS) {
+        throw new Error(`Timed out waiting for learnings lock: ${lockPath}`);
+    }
+    await reclaimStaleLock(lockPath);
+    await delay(LOCK_RETRY_DELAY_MS);
+    return acquireLock(lockPath, owner, attempt + 1);
+}
+/**
+ * Try to hard-link fully written owner metadata into the lock path.
+ * @param ownerPath - Fully written owner metadata file
+ * @param lockPath - Destination lock path
+ * @returns Whether publication acquired the lock
+ */
+async function publishOwnerLink(ownerPath, lockPath) {
+    try {
+        await link(ownerPath, lockPath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EEXIST" ||
+            error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+/**
+ * Remove only the lock inode still linked to this lease's owner file.
+ * @param lockPath - Shared lock path
+ * @param lease - Owner lease retaining the same inode
+ */
+async function releaseLock(lockPath, lease) {
+    try {
+        if (await sameFile(lockPath, lease.ownerPath)) {
+            await unlink(lockPath);
+        }
+    }
+    finally {
+        await removeFileIfPresent(lease.ownerPath);
+    }
+}
+/**
+ * Reclaim an expired lock only when its declared process is no longer live.
+ * @param lockPath - Shared lock path
+ */
+async function reclaimStaleLock(lockPath) {
+    const before = await statFile(lockPath);
+    if (before === undefined || !before.isFile()) {
+        return;
+    }
+    const owner = await readLockOwner(lockPath);
+    const timestamp = owner?.createdAt ?? Number(before.mtimeMs);
+    if (Date.now() - timestamp <= STALE_LOCK_MS ||
+        (owner !== undefined && isProcessLive(owner.pid))) {
+        return;
+    }
+    const retainedOwnerPath = owner === undefined ? undefined : `${lockPath}.${owner.token}.owner`;
+    const quarantine = retainedOwnerPath !== undefined &&
+        (await sameFile(lockPath, retainedOwnerPath))
+        ? retainedOwnerPath
+        : `${lockPath}.${crypto.randomUUID()}.stale`;
+    const linked = quarantine === retainedOwnerPath
+        ? true
+        : await publishOwnerLink(lockPath, quarantine);
+    if (!linked) {
+        return;
+    }
+    try {
+        if (await sameFile(lockPath, quarantine)) {
+            await removeFileIfPresent(lockPath);
+        }
+    }
+    finally {
+        await removeFileIfPresent(quarantine);
+    }
+}
+/**
+ * Read bounded owner metadata; partial or special lock files are unowned.
+ * @param lockPath - Shared lock path
+ * @returns Parsed owner or undefined
+ */
+async function readLockOwner(lockPath) {
+    const metadata = await statFile(lockPath);
+    if (metadata === undefined || !metadata.isFile() || metadata.size > 512) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(await readFile(lockPath, "utf8"));
+        return isLockOwner(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Compare two regular-file paths by device and inode.
+ * @param left - First file path
+ * @param right - Second file path
+ * @returns Whether both paths retain the same regular-file inode
+ */
+async function sameFile(left, right) {
+    const [leftStat, rightStat] = await Promise.all([
+        statFile(left),
+        statFile(right),
+    ]);
+    return (leftStat !== undefined &&
+        rightStat !== undefined &&
+        leftStat.isFile() &&
+        rightStat.isFile() &&
+        leftStat.dev === rightStat.dev &&
+        leftStat.ino === rightStat.ino);
+}
+/**
+ * Read file metadata without treating an absent path as an error.
+ * @param filePath - Filesystem path
+ * @returns File metadata or undefined
+ */
+async function statFile(filePath) {
+    try {
+        return await lstat(filePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/**
+ * Remove one path without recursive deletion.
+ * @param filePath - Regular file or hard-link path
+ */
+async function removeFileIfPresent(filePath) {
+    try {
+        await unlink(filePath);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+}
+/**
+ * Narrow parsed lock metadata to the exact ownership shape.
+ * @param value - Parsed metadata
+ * @returns Whether the metadata is a lock owner
+ */
+function isLockOwner(value) {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    const owner = value;
+    return (typeof owner.token === "string" &&
+        typeof owner.pid === "number" &&
+        Number.isSafeInteger(owner.pid) &&
+        owner.pid > 0 &&
+        typeof owner.createdAt === "number" &&
+        Number.isSafeInteger(owner.createdAt));
+}
+/**
+ * Treat permission-denied PID probes as live and missing PIDs as dead.
+ * @param pid - Declared owner process id
+ * @returns Whether the process may still be alive
+ */
+function isProcessLive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+/**
+ * Await a short retry delay without blocking the event loop.
+ * @param milliseconds - Delay duration
+ */
+async function delay(milliseconds) {
+    await new Promise(resolve => {
+        setTimeout(resolve, milliseconds);
+    });
+}
+//# sourceMappingURL=learnings-lock.js.map

package/dist/core/learnings-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learnings-lock.js","sourceRoot":"","sources":["../../src/core/learnings-lock.ts"],"names":[],"mappings":"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"}

package/dist/core/learnings-writer.d.ts

@@ -0,0 +1,22 @@
+import { type LearningEntry } from "./learnings-contract.js";
+/**
+ * Persist one already-selected learning without generating or truncating it.
+ * @param projectRoot - Absolute path to the host project root
+ * @param candidate - Untrusted seven-field learning entry
+ * @returns Absolute path to the persisted learnings file
+ */
+export declare function persistLearningEntry(projectRoot: string, candidate: unknown): Promise<string>;
+/**
+ * Render the complete file in one stable, machine-readable Markdown form.
+ * @param entries - Validated entries to serialize
+ * @returns Canonical Markdown plus JSONL document
+ */
+export declare function renderLearningsFile(entries: readonly LearningEntry[]): string;
+/**
+ * Parse and revalidate an existing file before it participates in a write.
+ * @param content - Existing learnings document
+ * @returns Revalidated entries from the document
+ */
+export declare function parseLearningsFile(content: string): LearningEntry[];
+export { validateLearningEntry } from "./learnings-entry.js";
+//# sourceMappingURL=learnings-writer.d.ts.map

package/dist/core/learnings-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learnings-writer.d.ts","sourceRoot":"","sources":["../../src/core/learnings-writer.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,yBAAyB,CAAC;AAqBjC;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,MAAM,CAAC,CA6BjB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,CAG7E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,EAAE,CAsBnE;AAED,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/core/learnings-writer.js

@@ -0,0 +1,128 @@
+/** Deterministic persistence for project-local learnings. */
+import * as fse from "fs-extra";
+import { rename, writeFile } from "node:fs/promises";
+import * as path from "node:path";
+import { LEARNINGS_CONTRACT, estimateLearningTokens, } from "./learnings-contract.js";
+import { validateLearningEntry } from "./learnings-entry.js";
+import { assertSafeLearningParents, readExistingLearnings, resolveSafeLearningTarget, } from "./learnings-file-safety.js";
+import { withLearningTargetLock } from "./learnings-lock.js";
+import { readProjectConfig, resolveProjectLearningsFile, } from "./project-config.js";
+const FILE_HEADER = `# Project Learnings
+
+<!-- lisa-learnings-contract:v${LEARNINGS_CONTRACT.version} -->
+
+`;
+const JSON_FENCE_START = "```jsonl\n";
+const JSON_FENCE_END = "\n```\n";
+/**
+ * Persist one already-selected learning without generating or truncating it.
+ * @param projectRoot - Absolute path to the host project root
+ * @param candidate - Untrusted seven-field learning entry
+ * @returns Absolute path to the persisted learnings file
+ */
+export async function persistLearningEntry(projectRoot, candidate) {
+    const entry = validateLearningEntry(candidate);
+    const initialDocument = buildNextDocument([], entry);
+    const config = await readProjectConfig(projectRoot);
+    const relativeFile = resolveProjectLearningsFile(config);
+    const { root, target } = resolveSafeLearningTarget(projectRoot, relativeFile);
+    await assertSafeLearningParents(root, path.dirname(target));
+    await fse.ensureDir(path.dirname(target));
+    return withLearningTargetLock(target, async () => {
+        await assertSafeLearningParents(root, path.dirname(target));
+        const existing = await readExistingLearnings(target);
+        const entries = existing === undefined ? [] : parseLearningsFile(existing);
+        const rendered = existing === undefined
+            ? initialDocument
+            : buildNextDocument(entries, entry);
+        const temporary = path.join(path.dirname(target), `.${path.basename(target)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+        try {
+            await writeFile(temporary, rendered, { encoding: "utf8", flag: "wx" });
+            await assertSafeLearningParents(root, path.dirname(target));
+            await rename(temporary, target);
+        }
+        finally {
+            await fse.remove(temporary);
+        }
+        return target;
+    });
+}
+/**
+ * Render the complete file in one stable, machine-readable Markdown form.
+ * @param entries - Validated entries to serialize
+ * @returns Canonical Markdown plus JSONL document
+ */
+export function renderLearningsFile(entries) {
+    const lines = entries.map(entry => JSON.stringify(entry)).join("\n");
+    return `${FILE_HEADER}${JSON_FENCE_START}${lines}${JSON_FENCE_END}`;
+}
+/**
+ * Parse and revalidate an existing file before it participates in a write.
+ * @param content - Existing learnings document
+ * @returns Revalidated entries from the document
+ */
+export function parseLearningsFile(content) {
+    if (estimateLearningTokens(content) > LEARNINGS_CONTRACT.maxTokens) {
+        throw new Error(`Project learnings payload exceeds maxTokens ${LEARNINGS_CONTRACT.maxTokens}`);
+    }
+    if (!content.startsWith(`${FILE_HEADER}${JSON_FENCE_START}`) ||
+        !content.endsWith(JSON_FENCE_END)) {
+        throw new Error("Invalid project learnings file format");
+    }
+    const jsonStart = FILE_HEADER.length + JSON_FENCE_START.length;
+    const jsonEnd = content.length - JSON_FENCE_END.length;
+    const entries = parseJsonLines(content.slice(jsonStart, jsonEnd)).map(validateLearningEntry);
+    if (new Set(entries.map(entry => entry.id)).size !== entries.length) {
+        throw new Error("Invalid project learnings payload: duplicate ids");
+    }
+    assertDocumentBudget(content, entries.length, "Project learnings payload");
+    return entries;
+}
+export { validateLearningEntry } from "./learnings-entry.js";
+/**
+ * Build and budget-check the next canonical document.
+ * @param entries - Existing validated entries
+ * @param entry - New validated entry
+ * @returns Next canonical document
+ */
+function buildNextDocument(entries, entry) {
+    if (entries.some(current => current.id === entry.id)) {
+        throw new Error(`Duplicate learning id: ${entry.id}`);
+    }
+    const nextEntries = [...entries, entry].sort((left, right) => left.id.localeCompare(right.id));
+    const rendered = renderLearningsFile(nextEntries);
+    assertDocumentBudget(rendered, nextEntries.length, "Learnings file");
+    return rendered;
+}
+/**
+ * Enforce the shared entry-count and model-agnostic token upper bounds.
+ * @param content - Canonical document
+ * @param entryCount - Number of entries in the document
+ * @param context - Error-message prefix
+ */
+function assertDocumentBudget(content, entryCount, context) {
+    if (entryCount > LEARNINGS_CONTRACT.maxEntries) {
+        throw new Error(`${context} exceeds maxEntries ${LEARNINGS_CONTRACT.maxEntries}`);
+    }
+    const estimatedTokens = estimateLearningTokens(content);
+    if (estimatedTokens > LEARNINGS_CONTRACT.maxTokens) {
+        throw new Error(`${context} exceeds maxTokens ${LEARNINGS_CONTRACT.maxTokens} (measured ${estimatedTokens})`);
+    }
+}
+/**
+ * Parse the strict JSONL payload with a stable, user-facing error.
+ * @param payload - JSONL payload
+ * @returns Parsed unknown entry values
+ */
+function parseJsonLines(payload) {
+    if (payload === "") {
+        return [];
+    }
+    try {
+        return payload.split("\n").map(line => JSON.parse(line));
+    }
+    catch {
+        throw new Error("Invalid project learnings JSONL payload");
+    }
+}
+//# sourceMappingURL=learnings-writer.js.map

package/dist/core/learnings-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learnings-writer.js","sourceRoot":"","sources":["../../src/core/learnings-writer.ts"],"names":[],"mappings":"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"}

package/dist/core/learnings.d.ts

@@ -0,0 +1,4 @@
+export * from "./learnings-contract.js";
+export * from "./learnings-writer.js";
+export { DEFAULT_PROJECT_RULES_FILE, PROJECT_LEARNINGS_FILENAME, resolveProjectLearningsFile, resolveProjectRulesFile, type ProjectConfig, } from "./project-config.js";
+//# sourceMappingURL=learnings.d.ts.map

package/dist/core/learnings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"learnings.d.ts","sourceRoot":"","sources":["../../src/core/learnings.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,EAC1B,2BAA2B,EAC3B,uBAAuB,EACvB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC"}

package/dist/core/learnings.js

@@ -0,0 +1,4 @@
+export * from "./learnings-contract.js";
+export * from "./learnings-writer.js";
+export { DEFAULT_PROJECT_RULES_FILE, PROJECT_LEARNINGS_FILENAME, resolveProjectLearningsFile, resolveProjectRulesFile, } from "./project-config.js";
+//# sourceMappingURL=learnings.js.map

package/dist/core/learnings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learnings.js","sourceRoot":"","sources":["../../src/core/learnings.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,EAC1B,2BAA2B,EAC3B,uBAAuB,GAExB,MAAM,qBAAqB,CAAC"}

package/dist/core/lisa.d.ts

@@ -76,6 +76,10 @@ export declare class Lisa {
      * skips existing files, so without help the parent would win).
      */
     private copyOverwriteOwnership;
+    /** Destination selected by the host project's projectRulesFile setting. */
+    private projectLearningsFile;
+    /** Whether the canonical all/create-only learnings source is registered. */
+    private projectLearningsTemplateRegistered;
     private readonly separator;
     private readonly lisaignoreSuffix;
     /**
@@ -137,6 +141,12 @@ export declare class Lisa {
      * @returns Promise that resolves once pending deletions have been collected
      */
     private loadPendingDeletions;
+    /**
+     * Resolve the host-owned learnings destination before template ownership is
+     * computed. The canonical source stays at its stable package path while its
+     * destination follows the configured project-rules directory.
+     */
+    private loadProjectLearningsFile;
     /**
      * Pre-compute, for every relative path shipped by any type's `create-only/`
      * directory, which single type "owns" it. The owner is the most-specific
@@ -398,6 +408,22 @@ export declare class Lisa {
      * @param currentType Project type (e.g. "all", "typescript", "cdk") supplying these files
      */
     private processDirectory;
+    /**
+     * Map the stable canonical learnings source to the project's configured
+     * sibling path. No other template source is redirected.
+     * @param sourceRelativePath - Path relative to the strategy source directory
+     * @param strategyName - Strategy delivering the source file
+     * @param currentType - Project type that owns the source directory
+     * @returns Destination path relative to the host project
+     */
+    private resolveTemplateDestination;
+    /**
+     * Identify the single machine-managed file that remains host-owned after
+     * creation, regardless of later stack templates or deletion manifests.
+     * @param relativePath - Candidate destination path
+     * @returns Whether the path is the registered project learnings destination
+     */
+    private isProjectLearningsPath;
     /**
      * Decide whether a candidate source file should be passed to its strategy.
      * Centralizes three independent skip rules that all need to short-circuit

package/dist/core/lisa.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lisa.d.ts","sourceRoot":"","sources":["../../src/core/lisa.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lisa.d.ts","sourceRoot":"","sources":["../../src/core/lisa.ts"],"names":[],"mappings":"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"}

package/dist/core/lisa.js

@@ -25,11 +25,15 @@ import { loadIgnorePatterns, } from "../utils/ignore-patterns.js";
 import { getLisaDistDir, hashFile, isRunningAsTrampoline, regenerateLockfilesInProcess, scheduleReconciliationChild, shouldSchedulePostinstallReconciliation, } from "../utils/postinstall-trampoline.js";
 import { COPY_STRATEGIES, createInitialCounters, harnessIncludesAgent, } from "./config.js";
 import { migrateInstructionFiles } from "./instruction-files-migration.js";
+import { assertSafeLearningParents, resolveSafeLearningTarget, } from "./learnings-file-safety.js";
+import { readProjectConfig, resolveProjectLearningsFile, } from "./project-config.js";
 /**
  * Log fragment used when a create-only instruction file already exists and is
  * therefore left untouched (the host owns it).
  */
 const HOST_OWNED_LABEL = "already present (host-owned)";
+const CREATE_ONLY_STRATEGY = "create-only";
+const PROJECT_LEARNINGS_TEMPLATE_PATH = path.join(".claude", "rules", "PROJECT_LEARNINGS.md");
 /**
  * Main Lisa orchestrator
  */
@@ -91,6 +95,10 @@ export class Lisa {
      * skips existing files, so without help the parent would win).
      */
     copyOverwriteOwnership = new Map();
+    /** Destination selected by the host project's projectRulesFile setting. */
+    projectLearningsFile = PROJECT_LEARNINGS_TEMPLATE_PATH;
+    /** Whether the canonical all/create-only learnings source is registered. */
+    projectLearningsTemplateRegistered = false;
     separator = "========================================";
     lisaignoreSuffix = "(.lisaignore)";
     /**
@@ -199,11 +207,22 @@ export class Lisa {
         for (const type of ["all", ...this.detectedTypes]) {
             const paths = await this.readPendingDeletionsForType(type);
             for (const p of paths) {
-                pending.add(p);
+                pending.add(path.normalize(p));
             }
         }
         this.pendingDeletions = pending;
     }
+    /**
+     * Resolve the host-owned learnings destination before template ownership is
+     * computed. The canonical source stays at its stable package path while its
+     * destination follows the configured project-rules directory.
+     */
+    async loadProjectLearningsFile() {
+        const relativeFile = resolveProjectLearningsFile(await readProjectConfig(this.config.destDir));
+        const { root, target } = resolveSafeLearningTarget(this.config.destDir, relativeFile);
+        await assertSafeLearningParents(root, path.dirname(target));
+        this.projectLearningsFile = path.normalize(relativeFile);
+    }
     /**
      * Pre-compute, for every relative path shipped by any type's `create-only/`
      * directory, which single type "owns" it. The owner is the most-specific
@@ -230,17 +249,25 @@ export class Lisa {
     async loadCreateOnlyOwnership() {
         const ownership = new Map();
         for (const type of ["all", ...this.detectedTypes]) {
-            const createOnlyDir = path.join(this.config.lisaDir, type, "create-only");
+            const createOnlyDir = path.join(this.config.lisaDir, type, CREATE_ONLY_STRATEGY);
             if (!(await fse.pathExists(createOnlyDir))) {
                 continue;
             }
             const files = await listFilesRecursive(createOnlyDir);
             for (const file of files) {
-                const relativePath = path.relative(createOnlyDir, file);
+                const sourceRelativePath = path.relative(createOnlyDir, file);
+                const relativePath = this.resolveTemplateDestination(sourceRelativePath, CREATE_ONLY_STRATEGY, type);
                 // Later types overwrite earlier ones, so child wins over parent.
                 ownership.set(relativePath, type);
             }
         }
+        const canonicalSource = path.join(this.config.lisaDir, "all", CREATE_ONLY_STRATEGY, PROJECT_LEARNINGS_TEMPLATE_PATH);
+        this.projectLearningsTemplateRegistered =
+            await fse.pathExists(canonicalSource);
+        if (this.projectLearningsTemplateRegistered) {
+            // Durable project memory is a single contract, not a stack override.
+            ownership.set(this.projectLearningsFile, "all");
+        }
         this.createOnlyOwnership = ownership;
     }
     /**
@@ -345,6 +372,13 @@ export class Lisa {
      */
     async processSingleDeletion(relativePath) {
         const { logger } = this.deps;
+        const normalizedRelativePath = path.normalize(relativePath);
+        if (this.projectLearningsTemplateRegistered &&
+            normalizedRelativePath === this.projectLearningsFile) {
+            logger.info(`Kept (host-owned project learnings): ${relativePath}`);
+            this.counters.skipped++;
+            return;
+        }
         const targetPath = path.join(this.config.destDir, relativePath);
         const resolvedTarget = path.resolve(targetPath);
         const resolvedDest = path.resolve(this.config.destDir);
@@ -564,6 +598,7 @@ export class Lisa {
             await this.initServices();
             await this.detectTypes();
             await this.detectSelfApply();
+            await this.loadProjectLearningsFile();
             await this.loadPendingDeletions();
             await this.loadCreateOnlyOwnership();
             await this.loadCopyOverwriteOwnership();
@@ -1003,7 +1038,15 @@ export class Lisa {
      */
     async processDirectory(srcDir, strategy, currentType) {
         const allFiles = await listFilesRecursive(srcDir);
-        const files = allFiles.filter(srcFile => this.shouldProcessFile(path.relative(srcDir, srcFile), strategy.name, currentType));
+        const files = allFiles
+            .map(srcFile => {
+            const sourceRelativePath = path.relative(srcDir, srcFile);
+            return {
+                srcFile,
+                relativePath: this.resolveTemplateDestination(sourceRelativePath, strategy.name, currentType),
+            };
+        })
+            .filter(({ relativePath }) => this.shouldProcessFile(relativePath, strategy.name, currentType));
         const context = {
             config: this.config,
             backupFile: async (absolutePath) => {
@@ -1014,14 +1057,39 @@ export class Lisa {
                 return this.handleOverwritePrompt(relativePath, sourcePath, destPath);
             },
         };
-        for (const srcFile of files) {
-            const relativePath = path.relative(srcDir, srcFile);
+        for (const { srcFile, relativePath } of files) {
             const destFile = path.join(this.config.destDir, relativePath);
             const result = await strategy.apply(srcFile, destFile, relativePath, context);
             this.updateCounters(result);
             this.logResult(result);
         }
     }
+    /**
+     * Map the stable canonical learnings source to the project's configured
+     * sibling path. No other template source is redirected.
+     * @param sourceRelativePath - Path relative to the strategy source directory
+     * @param strategyName - Strategy delivering the source file
+     * @param currentType - Project type that owns the source directory
+     * @returns Destination path relative to the host project
+     */
+    resolveTemplateDestination(sourceRelativePath, strategyName, currentType) {
+        if (currentType === "all" &&
+            strategyName === CREATE_ONLY_STRATEGY &&
+            sourceRelativePath === PROJECT_LEARNINGS_TEMPLATE_PATH) {
+            return this.projectLearningsFile;
+        }
+        return sourceRelativePath;
+    }
+    /**
+     * Identify the single machine-managed file that remains host-owned after
+     * creation, regardless of later stack templates or deletion manifests.
+     * @param relativePath - Candidate destination path
+     * @returns Whether the path is the registered project learnings destination
+     */
+    isProjectLearningsPath(relativePath) {
+        return (this.projectLearningsTemplateRegistered &&
+            relativePath === this.projectLearningsFile);
+    }
     /**
      * Decide whether a candidate source file should be passed to its strategy.
      * Centralizes three independent skip rules that all need to short-circuit
@@ -1049,12 +1117,18 @@ export class Lisa {
             this.logSkip(`ignored`, relativePath, "Ignored");
             return false;
         }
-        if (this.pendingDeletions.has(relativePath)) {
+        const isProjectLearnings = this.isProjectLearningsPath(relativePath);
+        if (this.pendingDeletions.has(relativePath) && !isProjectLearnings) {
             this.counters.skipped++;
             this.logSkip("pending deletion by detected type", relativePath, "Skipped (pending deletion)");
             return false;
         }
-        if (strategyName === "create-only") {
+        if (isProjectLearnings && strategyName !== CREATE_ONLY_STRATEGY) {
+            this.counters.skipped++;
+            this.logSkip("owned by all/create-only", relativePath, "Skipped (host-owned project learnings)");
+            return false;
+        }
+        if (strategyName === CREATE_ONLY_STRATEGY) {
             const owner = this.createOnlyOwnership.get(relativePath);
             if (owner !== undefined && owner !== currentType) {
                 this.counters.skipped++;