@deftai/directive-core 0.67.0 → 0.68.0

package/dist/init-deposit/hygiene.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Scoped staging + installer-managed allowlist for TS-native init/update (#1453).
+ *
+ * Mirrors cmd/deft-install/hygiene.go + deposit.go installerManagedMatchers.
+ * Refs #1576, #1453, #1430.
+ */
+import { type InitDepositIo } from "./constants.js";
+export declare const CODEQL_CONFIG_REL = ".github/codeql/codeql-config.yml";
+export declare const CORE_GUARD_WORKFLOW_REL = ".github/workflows/deft-core-guard.yml";
+export interface InstallerManagedMatcher {
+    readonly exact?: string;
+    readonly prefix?: string;
+}
+/** Single source of truth for installer-managed paths (#1440 / #1576). */
+export declare function installerManagedMatchers(): InstallerManagedMatcher[];
+/** POSIX ERE alternation embedded in the deposited deft-core-guard workflow. */
+export declare function installerManagedGuardEre(): string;
+export declare function isInstallerManagedPath(path: string): boolean;
+export interface FrameworkStagePathsOptions {
+    /**
+     * Include the project-root ``Taskfile.yml`` in the stage set. Defaults to
+     * ``false``: unlike the other allowlisted paths, ``Taskfile.yml`` is a
+     * consumer-owned file that merely *contains* an installer-managed include
+     * block, so it must only be staged when the installer actually wired that
+     * block this run -- otherwise an unrelated user edit would be silently
+     * ``git add``ed (#1576 review).
+     */
+    readonly includeTaskfile?: boolean;
+}
+export declare function frameworkStagePaths(projectDir: string, deftDir: string, options?: FrameworkStagePathsOptions): string[];
+export interface StageFrameworkPathsSeams {
+    gitPorcelain?: (projectRoot: string) => string | null;
+    runGitAdd?: (projectDir: string, paths: readonly string[]) => void;
+}
+/** Best-effort scoped `git add` — never fails the install/update (#1453 Layer 2b). */
+export declare function stageFrameworkPaths(projectDir: string, paths: readonly string[], seams?: StageFrameworkPathsSeams): {
+    staged: boolean;
+    error: Error | null;
+};
+export declare const COMMIT_HYGIENE_BRANCH_NAME = "chore/deft-framework-upgrade";
+export declare function printCommitGuidance(io: InitDepositIo, paths: readonly string[], staged: boolean): void;
+export interface DepositStagePathsOptions extends StageFrameworkPathsSeams, FrameworkStagePathsOptions {
+    readCachedNames?: (projectDir: string) => string[];
+}
+export declare function depositStagePaths(projectDir: string, options?: DepositStagePathsOptions): {
+    stagePaths: string[];
+    staged: boolean;
+    stagedPaths: string[];
+};
+//# sourceMappingURL=hygiene.d.ts.map

package/dist/init-deposit/hygiene.js

@@ -0,0 +1,176 @@
+/**
+ * Scoped staging + installer-managed allowlist for TS-native init/update (#1453).
+ *
+ * Mirrors cmd/deft-install/hygiene.go + deposit.go installerManagedMatchers.
+ * Refs #1576, #1453, #1430.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { gitPorcelain } from "../story-ready/git.js";
+import { CANONICAL_INSTALL_ROOT } from "./constants.js";
+export const CODEQL_CONFIG_REL = ".github/codeql/codeql-config.yml";
+export const CORE_GUARD_WORKFLOW_REL = ".github/workflows/deft-core-guard.yml";
+const VBRIEF_LIFECYCLE_DIRS = ["proposed", "pending", "active", "completed", "cancelled"];
+/** Single source of truth for installer-managed paths (#1440 / #1576). */
+export function installerManagedMatchers() {
+    return [
+        { exact: "AGENTS.md" },
+        { prefix: ".agents/" },
+        { prefix: ".githooks/" },
+        { exact: ".gitattributes" },
+        { exact: ".gitignore" },
+        { exact: "greptile.json" },
+        { exact: CODEQL_CONFIG_REL },
+        { exact: CORE_GUARD_WORKFLOW_REL },
+        { exact: "Taskfile.yml" },
+        { exact: "vbrief/.deft-version" },
+        { exact: "vbrief/vbrief.md" },
+        { prefix: "vbrief/schemas/" },
+        { prefix: "vbrief/migration/" },
+        ...VBRIEF_LIFECYCLE_DIRS.map((sub) => ({ exact: `vbrief/${sub}/.gitkeep` })),
+    ];
+}
+function escapeEre(value) {
+    return value.replace(/[.^$*+?()[\]{}|\\]/g, "\\$&");
+}
+function matcherToEre(matcher) {
+    if (matcher.exact)
+        return `^${escapeEre(matcher.exact)}$`;
+    return `^${escapeEre(matcher.prefix ?? "")}`;
+}
+/** POSIX ERE alternation embedded in the deposited deft-core-guard workflow. */
+export function installerManagedGuardEre() {
+    return installerManagedMatchers()
+        .map((matcher) => matcherToEre(matcher))
+        .join("|");
+}
+function matchesInstallerManaged(path, matchers) {
+    for (const matcher of matchers) {
+        if (matcher.exact && path === matcher.exact)
+            return true;
+        if (matcher.prefix && path.startsWith(matcher.prefix))
+            return true;
+    }
+    return false;
+}
+export function isInstallerManagedPath(path) {
+    return matchesInstallerManaged(path, installerManagedMatchers());
+}
+export function frameworkStagePaths(projectDir, deftDir, options = {}) {
+    const paths = [];
+    const seen = new Set();
+    const add = (rel) => {
+        const normalized = rel.replace(/\\/g, "/");
+        if (!normalized || normalized === "." || seen.has(normalized))
+            return;
+        if (!existsSync(join(projectDir, normalized)))
+            return;
+        seen.add(normalized);
+        paths.push(normalized);
+    };
+    const relDeft = relative(projectDir, deftDir);
+    if (relDeft && !relDeft.startsWith("..") && !relDeft.startsWith("/")) {
+        add(relDeft);
+    }
+    for (const matcher of installerManagedMatchers()) {
+        if (matcher.exact === "Taskfile.yml" && !options.includeTaskfile)
+            continue;
+        if (matcher.exact) {
+            add(matcher.exact);
+        }
+        else if (matcher.prefix) {
+            add(matcher.prefix.replace(/\/$/, ""));
+        }
+    }
+    return paths;
+}
+/** Best-effort scoped `git add` — never fails the install/update (#1453 Layer 2b). */
+export function stageFrameworkPaths(projectDir, paths, seams = {}) {
+    if (paths.length === 0)
+        return { staged: false, error: null };
+    const readPorcelain = seams.gitPorcelain ?? gitPorcelain;
+    if (readPorcelain(projectDir) === null)
+        return { staged: false, error: null };
+    const runGitAdd = seams.runGitAdd ??
+        ((root, stagePaths) => {
+            execFileSync("git", ["add", ...stagePaths], {
+                cwd: root,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        });
+    try {
+        runGitAdd(projectDir, paths);
+        return { staged: true, error: null };
+    }
+    catch (cause) {
+        const error = cause instanceof Error ? cause : new Error(String(cause));
+        return { staged: false, error };
+    }
+}
+export const COMMIT_HYGIENE_BRANCH_NAME = "chore/deft-framework-upgrade";
+export function printCommitGuidance(io, paths, staged) {
+    if (paths.length === 0)
+        return;
+    const addCmd = `git add ${paths.join(" ")}`;
+    io.printf("\nCommit hygiene (#1453, #1671): keep the framework deposit in its OWN branch/PR.\n");
+    io.printf("Do NOT use `git add -A` -- mixing the payload with your own files trips the\n");
+    io.printf("deft-core-guard CI check.\n");
+    if (staged) {
+        io.printf("The installer already staged ONLY these framework + installer-managed paths:\n");
+        io.printf(`  ${addCmd}\n`);
+    }
+    else {
+        io.printf("Stage ONLY these framework + installer-managed paths:\n");
+        io.printf(`  ${addCmd}\n`);
+    }
+    io.printf("Then take the framework deposit through the full PR lifecycle so deft-core-guard\n");
+    io.printf("evaluates a clean, standalone PR:\n");
+    io.printf(`  1. Branch: git switch -c ${COMMIT_HYGIENE_BRANCH_NAME}\n`);
+    io.printf('  2. Commit: git commit -m "chore(deft): update framework payload"\n');
+    io.printf(`  3. Push:   git push -u origin ${COMMIT_HYGIENE_BRANCH_NAME}\n`);
+    io.printf('  4. PR:     gh pr create --fill --title "chore(deft): update framework payload"\n');
+    io.printf("  5. Merge:  gh pr merge --squash --delete-branch   # after deft-core-guard passes\n");
+}
+function defaultCachedNames(projectDir) {
+    try {
+        const out = execFileSync("git", ["diff", "--cached", "--name-only", "-z"], {
+            cwd: projectDir,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return out
+            .split("\0")
+            .map((entry) => entry.trim().replace(/\\/g, "/"))
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Narrow the candidate stage paths to those that actually have staged index
+ * changes. A candidate file matches when the cached name is identical; a
+ * candidate directory (e.g. ``.deft/core``) matches when any cached name lives
+ * beneath it. This keeps ``staged_paths`` honest for downstream automation --
+ * it reports what git actually staged, not every path passed to ``git add``.
+ */
+function actuallyStagedPaths(stagePaths, cachedNames) {
+    return stagePaths.filter((candidate) => cachedNames.some((name) => name === candidate || name.startsWith(`${candidate}/`)));
+}
+export function depositStagePaths(projectDir, options = {}) {
+    const deftDir = join(projectDir, CANONICAL_INSTALL_ROOT);
+    const stagePaths = frameworkStagePaths(projectDir, deftDir, {
+        includeTaskfile: options.includeTaskfile ?? false,
+    });
+    const { staged } = stageFrameworkPaths(projectDir, stagePaths, options);
+    const readCachedNames = options.readCachedNames ?? defaultCachedNames;
+    const cachedNames = staged ? readCachedNames(projectDir) : [];
+    return {
+        stagePaths,
+        staged,
+        stagedPaths: staged ? actuallyStagedPaths(stagePaths, cachedNames) : [],
+    };
+}
+//# sourceMappingURL=hygiene.js.map

package/dist/init-deposit/init-deposit.d.ts

@@ -19,6 +19,7 @@ export interface InitDepositResult {
     readonly taskfileWired: boolean;
     readonly configDir: string;
     readonly legacyLayout: boolean;
+    readonly stagedPaths: string[];
 }
 export interface InitDepositSeams {
     resolveContentRoot?: () => Promise<string>;

package/dist/init-deposit/init-deposit.js

@@ -13,6 +13,7 @@ import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { readCorePackageVersion } from "../engine-version.js";
 import { ensureInitGitignoreLines, reconstituteDepositFromContent } from "./gitignore.js";
+import { depositStagePaths, printCommitGuidance } from "./hygiene.js";
 import { buildLegacyRefusalJson, buildLegacyRefusalMessage, detectLegacyLayout, LEGACY_LAYOUT_REFUSED_EXIT_CODE, LegacyLayoutRefusedError, } from "./legacy-detect.js";
 import { printMigrateNudgeIfNeeded } from "./migrate.js";
 import { CANONICAL_INSTALL_ROOT, depositNeutralization, ensureTaskfile, writeAgentsMd, writeAgentsSkills, writeConsumerGitHooks, writeConsumerVbrief, writeInstallManifest, } from "./scaffold.js";
@@ -93,7 +94,7 @@ export function buildInstallSummaryJson(result, options) {
         strategy: "vendor",
         dirty_tree: false,
         dirty_files: [],
-        staged_paths: [],
+        staged_paths: result.stagedPaths,
         backup_path: "",
         previous_version: "",
     };
@@ -150,6 +151,10 @@ export async function runInitDeposit(args, io, seams = {}) {
         taskfileWired = ensureTaskfile(projectDir, io);
     }
     const configDir = createUserConfigDir(io);
+    const { stagePaths, staged, stagedPaths } = depositStagePaths(projectDir, {
+        includeTaskfile: taskfileWired,
+    });
+    printCommitGuidance(io, stagePaths, staged);
     return {
         projectDir,
         deftDir,
@@ -157,6 +162,7 @@ export async function runInitDeposit(args, io, seams = {}) {
         taskfileWired,
         configDir,
         legacyLayout: false,
+        stagedPaths,
     };
 }
 /** CLI-facing wrapper: runs deposit, emits JSON or wizard UX, returns exit code. */

package/dist/init-deposit/refresh.d.ts

@@ -22,6 +22,8 @@ export interface RefreshDepositResult {
     readonly agentsMdUpdated: boolean;
     readonly versionSkewNotice: string | null;
     readonly legacyLayout: boolean;
+    readonly taskfileWired: boolean;
+    readonly stagedPaths: string[];
 }
 export interface RefreshDepositSeams {
     resolveContentRoot?: () => Promise<string>;

package/dist/init-deposit/refresh.js

@@ -7,7 +7,7 @@
  *
  * Refs #1942, #1430, #1671.
  */
-import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { copyTree } from "../deposit/copy-tree.js";
 import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
@@ -17,31 +17,11 @@ import { readCorePackageVersion } from "../engine-version.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { DEV_FALLBACK } from "../platform/constants.js";
 import { gitPorcelain } from "../story-ready/git.js";
+import { depositStagePaths, isInstallerManagedPath, printCommitGuidance } from "./hygiene.js";
 import { parseInitArgv } from "./init-deposit.js";
 import { buildLegacyRefusalJson, buildLegacyRefusalMessage, detectLegacyLayout, LEGACY_LAYOUT_REFUSED_EXIT_CODE, LegacyLayoutRefusedError, } from "./legacy-detect.js";
 import { printMigrateNudgeIfNeeded } from "./migrate.js";
-import { CANONICAL_INSTALL_ROOT, depositNeutralization, writeAgentsMd, writeInstallManifest, } from "./scaffold.js";
-const INSTALLER_MANAGED_EXACT = new Set([
-    "AGENTS.md",
-    ".gitattributes",
-    ".gitignore",
-    "greptile.json",
-    ".github/codeql/codeql-config.yml",
-    ".github/workflows/deft-core-guard.yml",
-    "vbrief/.deft-version",
-    "vbrief/vbrief.md",
-    "vbrief/proposed/.gitkeep",
-    "vbrief/pending/.gitkeep",
-    "vbrief/active/.gitkeep",
-    "vbrief/completed/.gitkeep",
-    "vbrief/cancelled/.gitkeep",
-]);
-const INSTALLER_MANAGED_PREFIXES = [
-    ".agents/",
-    ".githooks/",
-    "vbrief/schemas/",
-    "vbrief/migration/",
-];
+import { CANONICAL_INSTALL_ROOT, depositNeutralization, ensureTaskfile, writeAgentsMd, writeInstallManifest, } from "./scaffold.js";
 function normalizeVersion(version) {
     return version.trim().replace(/^v/, "");
 }
@@ -110,10 +90,34 @@ function syncBareVersionMarker(projectDir, version) {
         // best-effort, mirrors install-upgrade marker write
     }
 }
-function isInstallerManagedPath(path) {
-    if (INSTALLER_MANAGED_EXACT.has(path))
-        return true;
-    return INSTALLER_MANAGED_PREFIXES.some((prefix) => path.startsWith(prefix));
+/**
+ * Retire a stale legacy `.deft/VERSION` after the canonical `.deft/core/VERSION`
+ * has been (re)written (#2064). Folded in from the former `install-upgrade`
+ * path so the shared refresh transaction covers the v0.27.x -> v0.28 manifest
+ * transition (#1046 PR-B) that the doctor's `install-manifest-disagreement`
+ * check still cites `task upgrade` to repair. Only acts when the canonical
+ * manifest lives at `<project>/.deft/core/VERSION` and a legacy
+ * `<project>/.deft/VERSION` disagrees; renames the legacy file to
+ * `.deft/VERSION.premigrate` (best-effort, never fatal).
+ */
+function migrateLegacyInstallManifest(projectDir, canonicalManifestPath) {
+    const canonical = resolve(canonicalManifestPath);
+    const expectedParent = resolve(projectDir, ".deft", "core");
+    if (resolve(canonical, "..") !== expectedParent)
+        return;
+    const legacy = join(projectDir, ".deft", "VERSION");
+    if (!existsSync(legacy) || !statSync(legacy).isFile())
+        return;
+    try {
+        const legacyVersion = manifestTagToVersion(parseInstallManifest(readFileSync(legacy, "utf8")));
+        const canonicalVersion = manifestTagToVersion(parseInstallManifest(readFileSync(canonical, "utf8")));
+        if (legacyVersion !== null && legacyVersion === canonicalVersion)
+            return;
+        renameSync(legacy, join(projectDir, ".deft", "VERSION.premigrate"));
+    }
+    catch {
+        // best-effort
+    }
 }
 function unquoteGitPath(path) {
     if (path.length >= 2 && path.startsWith('"') && path.endsWith('"')) {
@@ -206,7 +210,7 @@ export function buildUpdateSummaryJson(result, options) {
         update: true,
         non_interactive: options.nonInteractive,
         upgrade: options.upgrade,
-        taskfile_wired: false,
+        taskfile_wired: result.taskfileWired,
         missing_tools: [],
         maintainer_mode: false,
         maintainer_tools: [],
@@ -217,7 +221,7 @@ export function buildUpdateSummaryJson(result, options) {
         strategy: "file-swap",
         dirty_tree: false,
         dirty_files: [],
-        staged_paths: [],
+        staged_paths: result.stagedPaths,
         backup_path: "",
         previous_version: result.previousDepositVersion ?? "",
         content_version: result.contentVersion,
@@ -268,13 +272,25 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         fetchedBy: "directive-update",
         ...(previousManagedBy ? { managedBy: previousManagedBy } : {}),
     };
-    writeInstallManifest(projectDir, deftDir, manifestFields);
+    const writtenManifestPath = writeInstallManifest(projectDir, deftDir, manifestFields);
+    // #2064: retire a stale legacy .deft/VERSION now that the canonical
+    // .deft/core/VERSION has been rewritten (folded in from install-upgrade so no
+    // manifest behavior is lost by the redirect). Best-effort; never fatal.
+    migrateLegacyInstallManifest(projectDir, writtenManifestPath);
     // #2055: regenerate the bare .deft-version derivative so it agrees with the
     // freshly written manifest tag (otherwise doctor's manifest-agreement check
     // fails and the operator must hand-edit the marker).
     syncBareVersionMarker(projectDir, contentVersion);
     const agentsMdUpdated = writeAgentsMd(projectDir, deftDir, io);
     await depositNeutralization(projectDir, io);
+    let taskfileWired = false;
+    if (args.nonInteractive) {
+        taskfileWired = ensureTaskfile(projectDir, io);
+    }
+    const { stagePaths, staged, stagedPaths } = depositStagePaths(projectDir, {
+        includeTaskfile: taskfileWired,
+    });
+    printCommitGuidance(io, stagePaths, staged);
     const readPorcelain = seams.gitPorcelain ?? gitPorcelain;
     printRefreshSideEffects(io, frameworkRefreshSideEffects(projectDir, readPorcelain));
     if (versionSkewNotice) {
@@ -289,6 +305,8 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         agentsMdUpdated,
         versionSkewNotice,
         legacyLayout: false,
+        taskfileWired,
+        stagedPaths,
     };
 }
 /** CLI-facing wrapper: runs refresh, emits JSON or wizard UX, returns exit code. */

package/dist/init-deposit/scaffold.d.ts

@@ -4,10 +4,9 @@
  *
  * Refs #1942, #1430, #1463, #1179.
  */
-export interface InitDepositIo {
-    printf: (text: string) => void;
-}
-export declare const CANONICAL_INSTALL_ROOT = ".deft/core";
+import { CANONICAL_INSTALL_ROOT, type InitDepositIo } from "./constants.js";
+export type { InitDepositIo };
+export { CANONICAL_INSTALL_ROOT };
 export declare const CORE_GLOB = ".deft/core/**";
 export declare const MINIMAL_TASKFILE = "version: '3'\n\n# Taskfile for this project.\n# Installed by deft-install --yes (Epic-4). Add your own tasks below or in\n# additional included files. The deft include makes all framework tasks\n# (task check, task vbrief:*, task doctor, etc.) available from the project root.\n\nincludes:\n  deft:\n    taskfile: ./.deft/core/Taskfile.yml\n    optional: true\n";
 export declare const CANONICAL_TASKFILE_INCLUDE = "taskfile: ./.deft/core/Taskfile.yml";

package/dist/init-deposit/scaffold.js

@@ -12,7 +12,9 @@ import { dirname, join, relative } from "node:path";
 import { copyTree } from "../deposit/copy-tree.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { agentsRefreshPlan } from "../platform/agents-md.js";
-export const CANONICAL_INSTALL_ROOT = ".deft/core";
+import { CANONICAL_INSTALL_ROOT } from "./constants.js";
+import { installerManagedGuardEre } from "./hygiene.js";
+export { CANONICAL_INSTALL_ROOT };
 export const CORE_GLOB = ".deft/core/**";
 const CODEQL_CONFIG_REL = ".github/codeql/codeql-config.yml";
 const CORE_GUARD_WORKFLOW_REL = ".github/workflows/deft-core-guard.yml";
@@ -475,29 +477,6 @@ export function writeConsumerGitHooks(projectDir, deftDir, io, seams = {}) {
     }
     return filesDeposited || configWired;
 }
-function escapeEre(value) {
-    return value.replace(/[.^$*+?()[\]{}|\\]/g, "\\$&");
-}
-function installerManagedGuardEre() {
-    const matchers = [
-        { exact: "AGENTS.md" },
-        { prefix: ".agents/" },
-        { prefix: ".githooks/" },
-        { exact: ".gitattributes" },
-        { exact: ".gitignore" },
-        { exact: "greptile.json" },
-        { exact: CODEQL_CONFIG_REL },
-        { exact: CORE_GUARD_WORKFLOW_REL },
-        { exact: "vbrief/.deft-version" },
-        { exact: "vbrief/vbrief.md" },
-        { prefix: "vbrief/schemas/" },
-        { prefix: "vbrief/migration/" },
-        ...VBRIEF_LIFECYCLE_DIRS.map((sub) => ({ exact: `vbrief/${sub}/.gitkeep` })),
-    ];
-    return matchers
-        .map((m) => (m.exact ? `^${escapeEre(m.exact)}$` : `^${escapeEre(m.prefix ?? "")}`))
-        .join("|");
-}
 function githubActionsExpr(expression) {
     return ["$", "{{ ", expression, " }}"].join("");
 }

package/dist/integration-e2e/helpers.d.ts

@@ -11,7 +11,6 @@ export interface DispatchCall {
     projectRoot: string;
     frameworkRoot: string;
 }
-export declare function isFrameworkSourceContext(frameworkRoot: string, projectRoot: string): boolean;
 /** Mirror ``scripts/_project_context.dispatch_task_check`` for consumer-task e2e. */
 export declare function dispatchTaskCheck(frameworkRoot: string, projectRoot: string, runner: (command: string, projectRoot: string, frameworkRoot: string) => {
     code: number;

package/dist/integration-e2e/helpers.js

@@ -1,6 +1,6 @@
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { join } from "node:path";
 import { afterEach } from "vitest";
 import { restIssueListPaginated, setPaginatedLister, setSingleIssueFetcher, setSleepFn, } from "../cache/fetch.js";
 import { auditPath } from "../cache/paths.js";
@@ -108,14 +108,10 @@ export function writeScopeVbrief(projectRoot, folder, filename, status = "propos
     }, null, 2)}\n`, "utf8");
     return target;
 }
-export function isFrameworkSourceContext(frameworkRoot, projectRoot) {
-    return resolve(frameworkRoot) === resolve(projectRoot);
-}
+import { resolveCheckTarget } from "../check/orchestrator.js";
 /** Mirror ``scripts/_project_context.dispatch_task_check`` for consumer-task e2e. */
 export function dispatchTaskCheck(frameworkRoot, projectRoot, runner) {
-    const target = isFrameworkSourceContext(frameworkRoot, projectRoot)
-        ? "check:framework-source"
-        : "check:consumer";
+    const target = resolveCheckTarget(frameworkRoot, projectRoot);
     return runner(target, projectRoot, frameworkRoot).code;
 }
 /** Hermetic mirror of ``tests/integration/test_scm_smoke._probe_rate_limit``. */

package/dist/layout/lifecycle-ref.d.ts

@@ -0,0 +1,15 @@
+/** Lifecycle folders searched when a folder-qualified ref dangles (#1926). */
+export declare const LIFECYCLE_SCOPE_FOLDERS: readonly ["proposed", "pending", "active", "completed", "cancelled"];
+export interface ResolveLifecycleArtifactRefOptions {
+    /** When false, only resolve the literal path (for rewrite matching). Default true (#1926). */
+    readonly allowCrossFolderSearch?: boolean;
+}
+/**
+ * Resolve a lifecycle-relative artifact reference to an absolute path.
+ *
+ * When the direct path is missing but the ref names a lifecycle artifact
+ * (folder-qualified or bare basename), search all lifecycle folders for the
+ * same filename (#1926).
+ */
+export declare function resolveLifecycleArtifactRef(rel: string, lifecycleRoot: string, options?: ResolveLifecycleArtifactRefOptions): string;
+//# sourceMappingURL=lifecycle-ref.d.ts.map

package/dist/layout/lifecycle-ref.js

@@ -0,0 +1,55 @@
+import { existsSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { hasArtifactSuffix } from "./resolve.js";
+/** Lifecycle folders searched when a folder-qualified ref dangles (#1926). */
+export const LIFECYCLE_SCOPE_FOLDERS = [
+    "proposed",
+    "pending",
+    "active",
+    "completed",
+    "cancelled",
+];
+function isLifecycleFolder(name) {
+    return LIFECYCLE_SCOPE_FOLDERS.includes(name);
+}
+function searchLifecycleFolders(lifecycleRoot, artifactBasename) {
+    for (const folder of LIFECYCLE_SCOPE_FOLDERS) {
+        const candidate = resolve(lifecycleRoot, folder, artifactBasename);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve a lifecycle-relative artifact reference to an absolute path.
+ *
+ * When the direct path is missing but the ref names a lifecycle artifact
+ * (folder-qualified or bare basename), search all lifecycle folders for the
+ * same filename (#1926).
+ */
+export function resolveLifecycleArtifactRef(rel, lifecycleRoot, options = {}) {
+    const allowCrossFolderSearch = options.allowCrossFolderSearch ?? true;
+    const direct = resolve(lifecycleRoot, rel);
+    if (existsSync(direct)) {
+        return direct;
+    }
+    if (!allowCrossFolderSearch) {
+        return direct;
+    }
+    const parts = rel.split("/").filter(Boolean);
+    if (parts.length >= 2 && isLifecycleFolder(parts[0] ?? "")) {
+        const found = searchLifecycleFolders(lifecycleRoot, basename(rel));
+        if (found !== null) {
+            return found;
+        }
+    }
+    if (!rel.includes("/") && hasArtifactSuffix(rel)) {
+        const found = searchLifecycleFolders(lifecycleRoot, rel);
+        if (found !== null) {
+            return found;
+        }
+    }
+    return direct;
+}
+//# sourceMappingURL=lifecycle-ref.js.map

package/dist/platform/agents-md.d.ts

@@ -1,3 +1,4 @@
+import { type LockDeps } from "../slice/lock.js";
 export interface ManagedSectionAttrs {
     readonly version: number;
     readonly sha: string | null;
@@ -27,5 +28,32 @@ export declare function attributeRenderManagedSection(rendered: string, attrs: {
 }): string;
 /** Compute AGENTS.md managed-section freshness plan (mirrors scripts/_agents_md.py). */
 export declare function agentsRefreshPlan(projectRoot: string, seams?: AgentsMdSeams): Record<string, unknown>;
+export interface ApplyAgentsRefreshOptions {
+    /** Compute state only, never write — mirrors `agents:refresh --check`. */
+    readonly check?: boolean;
+    /** Compute the plan but skip the write — mirrors `agents:refresh --dry-run`. */
+    readonly dryRun?: boolean;
+}
+export interface AgentsRefreshApplyResult {
+    readonly state: string;
+    readonly path: string;
+    /** True only when the managed section was written to disk on this call. */
+    readonly wrote: boolean;
+    /** True when the plan produced writable `new_content` for a writable state. */
+    readonly writable: boolean;
+}
+/**
+ * Serialize the AGENTS.md managed-section read->compute->write behind an advisory
+ * file lock and write atomically (temp file + rename), so concurrent
+ * install/upgrade/migrate/refresh writers cannot clobber one another's `session=`
+ * write or leave a partially-written file (#1329).
+ *
+ * Reuses the existing cross-process append lock (`withAppendLock`, keyed here on
+ * the AGENTS.md path -> `AGENTS.md.lock`) and atomic writer (`atomicWriteText`)
+ * rather than introducing a competing lock utility. The parallel
+ * `projectDefinitionMutationLock` remains owned by #1260; a general lock helper is
+ * deliberately not added here to avoid two competing mutation-lock utilities.
+ */
+export declare function applyAgentsRefresh(projectRoot: string, options?: ApplyAgentsRefreshOptions, seams?: AgentsMdSeams, lockDeps?: LockDeps): AgentsRefreshApplyResult;
 export declare function hasV3ManagedMarker(projectRoot: string, readText?: (path: string) => string | null): boolean;
 //# sourceMappingURL=agents-md.d.ts.map