@deftai/directive-core 0.93.0 → 0.95.0

package/dist/hooks/readonly.d.ts

@@ -1,7 +1,21 @@
+/** Session posture env for assist/research low-ceremony writes (#1802). */
+export declare const ASSIST_SESSION_POSTURE_ENV = "DEFT_SESSION_POSTURE";
 /** Best-effort read-only explore signal from host payload (#1185). */
 export declare function hookReadOnlyFromPayload(payload: unknown): boolean;
 /** Read-only hook context: env override or host payload marker (#1185). */
 export declare function isReadOnlyHookContext(payload: unknown, environ?: NodeJS.ProcessEnv): boolean;
 /** Explore sub-agent spawns are exempt from the implementation gate stack (#1185). */
 export declare function isExploreSpawn(payload: unknown): boolean;
+/**
+ * Assist / research / ephemeral session posture for low-ceremony scratch writes (#1802).
+ * Structural markers only (env, payload posture fields, worker_role/subagent_type).
+ * Absent marker → false (fail closed). Compose with allowlisted scratch path fence.
+ */
+export declare function isAssistPosture(payload: unknown, environ?: NodeJS.ProcessEnv): boolean;
+/**
+ * Ephemeral / assist / docs spawns skip active-xBRIEF implementation gates (#3080).
+ * True only with an explicit allowlisted marker. Absent marker → false (fail closed).
+ * When an ephemeral marker conflicts with implement envelope signals, implement wins.
+ */
+export declare function isEphemeralSpawn(payload: unknown): boolean;
 //# sourceMappingURL=readonly.d.ts.map

package/dist/hooks/readonly.js

@@ -1,5 +1,19 @@
 import { READ_ONLY_HOOK_ENV } from "./tools.js";
 const TRUTHY = new Set(["1", "true", "yes", "on"]);
+/** Session posture env for assist/research low-ceremony writes (#1802). */
+export const ASSIST_SESSION_POSTURE_ENV = "DEFT_SESSION_POSTURE";
+/** Explicit non-lifecycle assist markers (#3080 / #1802). Primary: ephemeral; aliases: docs, assist. */
+const EPHEMERAL_ROLE_MARKERS = new Set(["ephemeral", "docs", "assist"]);
+/** Assist/research session posture tokens (structural; not free-text NLP) (#1802). */
+const ASSIST_POSTURE_MARKERS = new Set([
+    "assist",
+    "ephemeral",
+    "docs",
+    "research",
+    "research-notes",
+    "research_notes",
+    "scratch",
+]);
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -28,6 +42,9 @@ function isReadOnlyCapability(value) {
     const normalized = value.toLowerCase().replace(/[_\s-]/g, "");
     return normalized === "readonly";
 }
+function normalizePostureToken(value) {
+    return value.toLowerCase().replace(/[_\s]/g, "-");
+}
 /** Best-effort read-only explore signal from host payload (#1185). */
 export function hookReadOnlyFromPayload(payload) {
     const input = record(payload);
@@ -80,4 +97,113 @@ export function isExploreSpawn(payload) {
         fieldString(input, "workerRole");
     return workerRole?.toLowerCase() === "explore";
 }
+/**
+ * Assist / research / ephemeral session posture for low-ceremony scratch writes (#1802).
+ * Structural markers only (env, payload posture fields, worker_role/subagent_type).
+ * Absent marker → false (fail closed). Compose with allowlisted scratch path fence.
+ */
+export function isAssistPosture(payload, environ = process.env) {
+    const envPosture = (environ[ASSIST_SESSION_POSTURE_ENV] ?? "").trim();
+    if (envPosture.length > 0 && ASSIST_POSTURE_MARKERS.has(normalizePostureToken(envPosture))) {
+        return true;
+    }
+    // Explicit assist env override (truthy), separate from posture token names.
+    if (envTruthy(environ, "DEFT_HOOK_ASSIST"))
+        return true;
+    const input = record(payload);
+    if (input === null)
+        return false;
+    const toolInput = toolInputRecord(input) ?? input;
+    const posture = fieldString(toolInput, "posture") ??
+        fieldString(toolInput, "session_posture") ??
+        fieldString(toolInput, "sessionPosture") ??
+        fieldString(input, "posture") ??
+        fieldString(input, "session_posture") ??
+        fieldString(input, "sessionPosture");
+    if (posture !== null && ASSIST_POSTURE_MARKERS.has(normalizePostureToken(posture))) {
+        return true;
+    }
+    // Shared taxonomy with #3080 ephemeral spawn markers.
+    if (isEphemeralSpawn(payload))
+        return true;
+    return false;
+}
+/**
+ * Structural implement signals that win over an ephemeral marker (fail closed, #3080).
+ * Detected from envelope fields only — never free-text prompt heuristics.
+ */
+function hasImplementConflictSignal(toolInput, input) {
+    const driveTo = fieldString(toolInput, "drive_to") ??
+        fieldString(toolInput, "driveTo") ??
+        fieldString(toolInput, "drive-to") ??
+        fieldString(input, "drive_to") ??
+        fieldString(input, "driveTo") ??
+        fieldString(input, "drive-to");
+    if (driveTo !== null) {
+        const normalized = driveTo.toLowerCase().replace(/[_\s]/g, "-");
+        if (normalized === "merge-ready" ||
+            normalized === "merge" ||
+            normalized.startsWith("merge-") ||
+            normalized.includes("implement")) {
+            return true;
+        }
+    }
+    // Non-ephemeral worker roles that imply product implementation / swarm leaf.
+    // Skip when this field is itself the ephemeral marker (conflict is via other fields).
+    const workerRole = fieldString(toolInput, "worker_role") ??
+        fieldString(toolInput, "workerRole") ??
+        fieldString(input, "worker_role") ??
+        fieldString(input, "workerRole");
+    if (workerRole !== null && !EPHEMERAL_ROLE_MARKERS.has(workerRole.toLowerCase())) {
+        const role = workerRole.toLowerCase().replace(/[_\s]/g, "-");
+        if (role === "leaf-implementation" ||
+            role === "implementation" ||
+            role === "implement" ||
+            role.includes("implement")) {
+            return true;
+        }
+    }
+    const dispatchKind = fieldString(toolInput, "dispatch_kind") ??
+        fieldString(toolInput, "dispatchKind") ??
+        fieldString(input, "dispatch_kind") ??
+        fieldString(input, "dispatchKind");
+    if (dispatchKind !== null) {
+        const kind = dispatchKind.toLowerCase().replace(/[_\s]/g, "-");
+        if (kind === "swarm-cohort" || kind === "swarm-leaf" || kind.includes("implement")) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Ephemeral / assist / docs spawns skip active-xBRIEF implementation gates (#3080).
+ * True only with an explicit allowlisted marker. Absent marker → false (fail closed).
+ * When an ephemeral marker conflicts with implement envelope signals, implement wins.
+ */
+export function isEphemeralSpawn(payload) {
+    const input = record(payload);
+    if (input === null)
+        return false;
+    const toolInput = toolInputRecord(input) ?? input;
+    const subagentType = fieldString(toolInput, "subagent_type") ??
+        fieldString(toolInput, "subagentType") ??
+        fieldString(input, "subagent_type") ??
+        fieldString(input, "subagentType");
+    const workerRole = fieldString(toolInput, "worker_role") ??
+        fieldString(toolInput, "workerRole") ??
+        fieldString(input, "worker_role") ??
+        fieldString(input, "workerRole");
+    const marker = (workerRole !== null && EPHEMERAL_ROLE_MARKERS.has(workerRole.toLowerCase())
+        ? workerRole.toLowerCase()
+        : null) ??
+        (subagentType !== null && EPHEMERAL_ROLE_MARKERS.has(subagentType.toLowerCase())
+            ? subagentType.toLowerCase()
+            : null);
+    if (marker === null)
+        return false;
+    // Implement signals win over ephemeral markers (fail closed).
+    if (hasImplementConflictSignal(toolInput, input))
+        return false;
+    return true;
+}
 //# sourceMappingURL=readonly.js.map

package/dist/index.d.ts

@@ -24,8 +24,10 @@ export * as evalReport from "./eval/report.js";
 export * as evalRun from "./eval/run.js";
 export * as events from "./events/attribution-ledger.js";
 export * from "./forward-coverage/evaluate.js";
+export * as freshness from "./freshness/index.js";
 export { ContainedWriteError, ContainedWriteErrorCode, type ContainedWriteInput, type ContainedWriteMode, type ContainedWriteResult, containedWrite, resolveContainedTarget, } from "./fs/contained-write.js";
 export { assertDestinationNotSymlink, assertDirectoryNotSymlink, assertProjectionContained, assertWriteTargetSafe, PROJECTION_CONTAINMENT_REFUSED_EXIT_CODE, ProjectionContainmentError, walkDirectoryRejectSymlinks, } from "./fs/projection-containment.js";
+export * as handoffEvidence from "./handoff-evidence/index.js";
 export * as intake from "./intake/index.js";
 export * as layout from "./layout/index.js";
 export * as legacyBridge from "./legacy-bridge/index.js";

package/dist/index.js

@@ -24,9 +24,11 @@ export * as evalReport from "./eval/report.js";
 export * as evalRun from "./eval/run.js";
 export * as events from "./events/attribution-ledger.js";
 export * from "./forward-coverage/evaluate.js";
+export * as freshness from "./freshness/index.js";
 // #2951 Phase 1: contained-write API for product sinks.
 export { ContainedWriteError, ContainedWriteErrorCode, containedWrite, resolveContainedTarget, } from "./fs/contained-write.js";
 export { assertDestinationNotSymlink, assertDirectoryNotSymlink, assertProjectionContained, assertWriteTargetSafe, PROJECTION_CONTAINMENT_REFUSED_EXIT_CODE, ProjectionContainmentError, walkDirectoryRejectSymlinks, } from "./fs/projection-containment.js";
+export * as handoffEvidence from "./handoff-evidence/index.js";
 export * as intake from "./intake/index.js";
 export * as layout from "./layout/index.js";
 export * as legacyBridge from "./legacy-bridge/index.js";

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

@@ -6,7 +6,7 @@ export declare const DEFT_HOOK_COMMAND_MARKER = "deft-hook";
 export declare const LEGACY_DEFT_HOOK_COMMAND_MARKER = "deft hook:dispatch";
 export declare const AGENT_HOOK_PATHS: readonly [".claude/settings.json", ".grok/hooks/deft.json", ".cursor/hooks.json", ".codex/hooks.json"];
 export type AgentHookPath = (typeof AGENT_HOOK_PATHS)[number];
-export type AgentHookRegistrationStatus = "healthy" | "missing" | "drifted";
+export type AgentHookRegistrationStatus = "healthy" | "disabled" | "missing" | "drifted";
 /** Whether the host receives a compact/resume hook deposit (#2113). */
 export type AgentHookCompactSupport = "deposited" | "unsupported";
 export interface AgentHookInspection {

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

@@ -312,7 +312,10 @@ function hasNestedRegistration(config, host, options = {}) {
     const sessionCommand = command(host, "session.start");
     const toolCommand = command(host, "tool.before");
     const compactCommand = command(host, "session.compact");
-    const base = session.some((entry) => nestedCommands(entry).includes(sessionCommand)) &&
+    const base = session.some((entry) => {
+        const group = object(entry);
+        return group?.matcher === undefined && nestedCommands(entry).includes(sessionCommand);
+    }) &&
         preTool.some((entry) => {
             const group = object(entry);
             return (group?.matcher === DIRECT_WRITE_HOOK_MATCHER && nestedCommands(entry).includes(toolCommand));
@@ -409,7 +412,7 @@ export function inspectAgentHookDeposit(projectRoot, hostHooksPolicy = loadHostH
             return {
                 host: definition.host,
                 path: definition.path,
-                status: "healthy",
+                status: "disabled",
                 compactSupport: definition.compactSupport,
                 detail: `plan.policy.hostHooks.${definition.host} is false — Directive hook deposit is skipped for this host.`,
             };

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

@@ -5,6 +5,7 @@
  * scaffold, skills/githooks/#1430 neutralization, and Taskfile wiring.
  * Refs #1942, #11, #1430.
  */
+import { type AgentHookReadinessResult } from "../verify-env/agent-hook-readiness.js";
 import { type LegacyLayoutDetection } from "./legacy-detect.js";
 import { type InitDepositIo, writeConsumerGitHooks } from "./scaffold.js";
 export interface InitDepositArgs {
@@ -28,11 +29,16 @@ export interface InitDepositSeams {
     nowIso?: () => string;
     gitHooks?: Parameters<typeof writeConsumerGitHooks>[3];
     detectLegacy?: (projectDir: string) => LegacyLayoutDetection;
+    evaluateAgentHookReadiness?: (projectRoot: string) => AgentHookReadinessResult;
 }
 export declare function parseInitArgv(canonicalArgv: readonly string[], userArgv?: readonly string[]): InitDepositArgs;
 export declare function userConfigDir(): string;
 export declare function createUserConfigDir(io: InitDepositIo): string;
-export declare function buildInstallSummaryJson(result: InitDepositResult, options: InitDepositArgs): Record<string, unknown>;
+export declare function buildInstallSummaryJson(input: {
+    result: InitDepositResult;
+    options: InitDepositArgs;
+    readiness: AgentHookReadinessResult | undefined;
+}): Record<string, unknown>;
 export declare function printNextSteps(result: InitDepositResult, io: InitDepositIo): void;
 /**
  * Ensure a minimal render-ready PROJECT-DEFINITION exists after lifecycle dirs

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

@@ -13,8 +13,10 @@ import { copyTree } from "../deposit/copy-tree.js";
 import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { readCorePackageVersion } from "../engine-version.js";
+import { stampLiveGeneration } from "../freshness/generation.js";
 import { renderProjectDefinition } from "../render/project-render.js";
 import { depositOpenClawL2ProductCommands } from "../slash/openclaw-deposit.js";
+import { agentHookReadinessJson, evaluateAgentHookReadiness, evaluateAgentHookReadinessSafely, } from "../verify-env/agent-hook-readiness.js";
 import { removeStaleMigratedFrameworkNarrative } from "../xbrief-migrate/migrate-project.js";
 import { writeAgentHookDeposit } from "./agent-hooks.js";
 import { ensureInitGitignoreLines, reconstituteDepositFromContent } from "./gitignore.js";
@@ -81,9 +83,12 @@ function readContentVersion(contentRoot, readVersion = readCorePackageVersion) {
     }
     return readVersion();
 }
-export function buildInstallSummaryJson(result, options) {
+export function buildInstallSummaryJson(input) {
+    const { result, options, readiness } = input;
     return {
-        success: true,
+        success: readiness ? readiness.code === 0 : true,
+        deposit_completed: true,
+        ...(readiness ? { agent_hook_readiness: agentHookReadinessJson(readiness) } : {}),
         action: "install",
         version: readCorePackageVersion(),
         project_dir: result.projectDir,
@@ -210,6 +215,14 @@ export async function runInitDeposit(args, io, seams = {}) {
         includeTaskfile: taskfileWired,
     });
     printCommitGuidance(io, stagePaths, staged);
+    // #3117: stamp live generation only after required init projections succeed.
+    // Stamping earlier would advance authority for a failed/partial init (Greptile).
+    stampLiveGeneration(projectDir, {
+        contentVersion: version,
+        stampedBy: "directive-init",
+        increment: true,
+        nowIso: nowIso(),
+    });
     return {
         projectDir,
         deftDir,
@@ -234,14 +247,21 @@ export async function runInitDepositCli(options) {
     };
     try {
         const result = await runInitDeposit(options, io, options.seams);
+        const readiness = evaluateAgentHookReadinessSafely(result.projectDir, options.seams?.evaluateAgentHookReadiness ?? evaluateAgentHookReadiness);
         if (options.jsonOut) {
-            options.writeOut(`${JSON.stringify(buildInstallSummaryJson(result, options), null, 2)}\n`);
+            options.writeOut(`${JSON.stringify(buildInstallSummaryJson({ result, options, readiness }), null, 2)}\n`);
             printNextSteps(result, { printf: options.writeErr });
         }
         else {
             printNextSteps(result, io);
         }
-        return 0;
+        const readinessOut = options.jsonOut
+            ? options.writeErr
+            : readiness.stream === "stderr"
+                ? options.writeErr
+                : options.writeOut;
+        readinessOut(`\n${readiness.message}\n`);
+        return readiness.code;
     }
     catch (cause) {
         if (cause instanceof LegacyLayoutRefusedError) {

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

@@ -9,6 +9,7 @@
  */
 import type { ResolutionFacts, ResolutionPlan } from "@deftai/directive-types";
 import { type ClassifySeams, type EngineInstallRunner, type EngineResolution, type LadderFacts, type ReprojectRunner } from "../resolution/index.js";
+import { type AgentHookReadinessResult } from "../verify-env/agent-hook-readiness.js";
 import { type GitLsFiles } from "./gitignore.js";
 import { type InitDepositArgs } from "./init-deposit.js";
 import { type LegacyLayoutDetection } from "./legacy-detect.js";
@@ -49,6 +50,8 @@ export interface RefreshDepositSeams {
     gitHooks?: GitHooksSeams;
     /** #2822: optional seam for trusted-org policy force-on migration. */
     runOrgForceOn?: (projectRoot: string) => void;
+    /** Post-deposit functional readiness gate (#3100). */
+    evaluateAgentHookReadiness?: (projectRoot: string) => AgentHookReadinessResult;
 }
 /**
  * The four states `directive update` classifies an EXISTING install into BEFORE
@@ -123,7 +126,12 @@ export interface RefreshSideEffects {
 export declare function frameworkRefreshSideEffects(projectDir: string, options?: FrameworkRefreshSideEffectsOptions): RefreshSideEffects;
 export declare function printRefreshSideEffects(io: InitDepositIo, effects: RefreshSideEffects): void;
 export declare function buildVersionSkewNotice(engineVersion: string, contentVersion: string, previousDepositVersion: string | null): string | null;
-export declare function buildUpdateSummaryJson(result: RefreshDepositResult, options: RefreshDepositArgs, updateState?: UpdateState): Record<string, unknown>;
+export declare function buildUpdateSummaryJson(input: {
+    result: RefreshDepositResult;
+    options: RefreshDepositArgs;
+    updateState: UpdateState | undefined;
+    readiness: AgentHookReadinessResult | undefined;
+}): Record<string, unknown>;
 export declare function printUpdateComplete(result: RefreshDepositResult, io: InitDepositIo, updateState?: UpdateState): void;
 export declare function runRefreshDeposit(args: RefreshDepositArgs, io: InitDepositIo, seams?: RefreshDepositSeams): Promise<RefreshDepositResult>;
 export interface RunRefreshDepositCliOptions extends RefreshDepositArgs {

package/dist/init-deposit/refresh.js

@@ -17,12 +17,14 @@ import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
 import { readCorePackageVersion } from "../engine-version.js";
+import { readLiveGeneration, stampLiveGeneration } from "../freshness/generation.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_FLAG_NAME, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY, } from "../policy/no-deft-directive.js";
 import { runOrgForceOnMigration } from "../policy/org-force-on-migration.js";
 import { checkLocalEngineIntegrity, classify, ENGINE_PACKAGE, plan, renderGlobalInstall, resolveEngine, } from "../resolution/index.js";
 import { depositOpenClawL2ProductCommands } from "../slash/openclaw-deposit.js";
 import { gitPorcelain } from "../story-ready/git.js";
+import { agentHookReadinessJson, evaluateAgentHookReadiness, evaluateAgentHookReadinessSafely, } from "../verify-env/agent-hook-readiness.js";
 import { removeStaleMigratedFrameworkNarrative } from "../xbrief-migrate/migrate-project.js";
 import { writeAgentHookDeposit } from "./agent-hooks.js";
 import { ensureInitGitignoreLines, isDepositTrackedInGit } from "./gitignore.js";
@@ -332,9 +334,12 @@ export function buildVersionSkewNotice(engineVersion, contentVersion, previousDe
     }
     return null;
 }
-export function buildUpdateSummaryJson(result, options, updateState) {
+export function buildUpdateSummaryJson(input) {
+    const { result, options, updateState, readiness } = input;
     return {
-        success: true,
+        success: readiness ? readiness.code === 0 : true,
+        deposit_completed: true,
+        ...(readiness ? { agent_hook_readiness: agentHookReadinessJson(readiness) } : {}),
         action: "upgrade",
         ...(updateState ? { update_state: updateState } : {}),
         version: result.engineVersion,
@@ -416,6 +421,27 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         // VERSION already matches (e.g. pre-#2804 additive deposits). Does not re-stamp.
         await reconcileDepositToContentPackage(deftDir, contentRoot, io);
         migrateLegacyInstallManifest(projectDir, join(deftDir, "VERSION"));
+        // #3117: ensure a readable live generation token exists without advancing
+        // when the payload did not swap (already-current). stampLiveGeneration is a
+        // no-op write when the token already matches (keeps git clean under #2118).
+        // If generation is missing or behind VERSION (e.g. prior stamp failed after
+        // VERSION rewrite), fail closed — do not report success with a stale token.
+        const priorGen = readLiveGeneration(projectDir);
+        const generationMatches = priorGen !== null &&
+            normalizeVersion(priorGen.contentVersion) === normalizeVersion(contentVersion);
+        try {
+            stampLiveGeneration(projectDir, {
+                contentVersion,
+                stampedBy: "directive-update",
+                increment: false,
+            });
+        }
+        catch (err) {
+            if (!generationMatches) {
+                throw err;
+            }
+            // Token already matches content; ensure write failure is non-fatal noise.
+        }
     }
     else {
         // Full-tree replace (or injected seam). Additive copy is no longer the default.
@@ -426,12 +452,13 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         // additive seams. Throws => no VERSION rewrite (refuse stamp until clean).
         await reconcileDepositToContentPackage(deftDir, contentRoot, io);
         const nowIso = seams.nowIso ?? (() => new Date().toISOString().replace(/\.\d{3}Z$/, "Z"));
+        const stampedAt = nowIso();
         const manifestFields = {
             ref: contentVersion.startsWith("v") ? contentVersion : `v${contentVersion}`,
             sha: "content-package",
             tag: contentVersion.startsWith("v") ? contentVersion : `v${contentVersion}`,
             installRoot: CANONICAL_INSTALL_ROOT,
-            fetchedAt: nowIso(),
+            fetchedAt: stampedAt,
             fetchedBy: "directive-update",
             ...(previousManagedBy ? { managedBy: previousManagedBy } : {}),
         };
@@ -440,6 +467,15 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         // .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);
+        // #3117: monotonic live generation MUST advance after a successful payload
+        // swap. Suppressing stamp failure would leave a prior bound/live match
+        // reporting `current` while the on-disk payload already changed (Greptile P1).
+        stampLiveGeneration(projectDir, {
+            contentVersion,
+            stampedBy: "directive-update",
+            increment: true,
+            nowIso: stampedAt,
+        });
     }
     // #2595: payload freshness and consumer derivative freshness are independent.
     // Always repair these cheap projections, including on the #2118 no-op path.
@@ -653,17 +689,24 @@ export async function runRefreshDepositCli(options) {
     }
     try {
         const result = await runRefreshDeposit(options, io, options.seams);
+        const readiness = evaluateAgentHookReadinessSafely(result.projectDir, options.seams?.evaluateAgentHookReadiness ?? evaluateAgentHookReadiness);
         const state = result.alreadyCurrent
             ? "current"
             : classification?.state;
         if (options.jsonOut) {
-            options.writeOut(`${JSON.stringify(buildUpdateSummaryJson(result, options, state), null, 2)}\n`);
+            options.writeOut(`${JSON.stringify(buildUpdateSummaryJson({ result, options, updateState: state, readiness }), null, 2)}\n`);
             printUpdateComplete(result, { printf: options.writeErr }, state);
         }
         else {
             printUpdateComplete(result, io, state);
         }
-        return 0;
+        const readinessOut = options.jsonOut
+            ? options.writeErr
+            : readiness.stream === "stderr"
+                ? options.writeErr
+                : options.writeOut;
+        readinessOut(`\n${readiness.message}\n`);
+        return readiness.code;
     }
     catch (cause) {
         if (cause instanceof LegacyLayoutRefusedError) {

package/dist/intake/issue-ingest.d.ts

@@ -1,6 +1,9 @@
 import { type ScanFlag } from "../cache/scanner.js";
+import { type IssueComment as ShapeIssueComment } from "../umbrella-current-shape/index.js";
 import { LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY } from "../xbrief-migrate/constants.js";
 import { type ScmCallFn } from "./reconcile-issues.js";
+/** Reference type pointing at the canonical current-shape comment permalink (#1870). */
+export declare const CURRENT_SHAPE_REF_TYPE: "x-xbrief/current-shape";
 export declare const INGEST_STATUSES: readonly ["proposed", "pending", "active"];
 export type IngestStatus = (typeof INGEST_STATUSES)[number];
 /**
@@ -21,9 +24,26 @@ export interface IssueComment {
         readonly login?: string;
     };
     readonly created_at?: string;
+    readonly updated_at?: string;
+    readonly html_url?: string;
+    readonly author_association?: string;
 }
 /** Enriched on issues after `fetchIssue` when the comment thread is non-empty (#2143). */
 export declare const ISSUE_COMMENT_THREAD_KEY: "issueCommentThread";
+/**
+ * Map ingest/REST comment rows onto the umbrella-current-shape selector input
+ * so #1152 pass-N + #2307 maintainer provenance rules apply (#1870).
+ */
+export declare function mapIngestCommentsToShapeComments(comments: readonly IssueComment[]): ShapeIssueComment[];
+/**
+ * Select the canonical current-shape comment from an ingest comment thread.
+ * Returns null when none is maintainer-authored / header-matched.
+ */
+export declare function selectIngestCurrentShape(comments: readonly IssueComment[]): (ShapeIssueComment & {
+    pass: number;
+}) | null;
+/** Count maintainer current-shape comments (lint surface for !=1). */
+export declare function countIngestCurrentShapeComments(comments: readonly IssueComment[]): number;
 export declare function bodyControlCharacterLabels(body: string): string[];
 export declare function warnBodyControlCharacters(number: number, body: string): void;
 export declare function extractPlanItems(body: string): Record<string, string>[];

package/dist/intake/issue-ingest.js

@@ -7,11 +7,14 @@ import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { call } from "../scm/call.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
 import { resolveProjectRepo } from "../slice/project-context.js";
+import { countMaintainerCurrentShapeComments, mapIssueCommentEntry, RAW_ISSUE_COMMENTS_KEY, selectCurrentShapeComment, } from "../umbrella-current-shape/index.js";
 import { slugify, TODAY } from "../vbrief-build/build.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
 import { LEGACY_ARTIFACT_SUFFIX, LEGACY_INFO_ROOT_KEY, MIGRATED_ARTIFACT_DIR, MIGRATED_ARTIFACT_SUFFIX, MIGRATED_INFO_ROOT_KEY, VBRIEF_VERSION, } from "../xbrief-migrate/constants.js";
 import { findAcHeading, parseCheckboxItems, parseListItems, sliceAcSection, stripCodeBlocks, stripFencedCodeBlocks, } from "./markdown-scanners.js";
 import { detectRepo, extractReferencesFromVbrief, fetchOpenIssues, GITHUB_ISSUE_REF_TYPES, LIFECYCLE_FOLDERS, parseIssueNumber, } from "./reconcile-issues.js";
+/** Reference type pointing at the canonical current-shape comment permalink (#1870). */
+export const CURRENT_SHAPE_REF_TYPE = "x-xbrief/current-shape";
 export const INGEST_STATUSES = ["proposed", "pending", "active"];
 /**
  * Thrown when the quarantine scanner hard-fails (credential-shaped content) on
@@ -36,6 +39,31 @@ export class ScannerHardFailError extends Error {
 }
 /** Enriched on issues after `fetchIssue` when the comment thread is non-empty (#2143). */
 export const ISSUE_COMMENT_THREAD_KEY = "issueCommentThread";
+/**
+ * Map ingest/REST comment rows onto the umbrella-current-shape selector input
+ * so #1152 pass-N + #2307 maintainer provenance rules apply (#1870).
+ */
+export function mapIngestCommentsToShapeComments(comments) {
+    const out = [];
+    for (const comment of comments) {
+        const mapped = mapIssueCommentEntry(comment);
+        if (mapped !== null) {
+            out.push(mapped);
+        }
+    }
+    return out;
+}
+/**
+ * Select the canonical current-shape comment from an ingest comment thread.
+ * Returns null when none is maintainer-authored / header-matched.
+ */
+export function selectIngestCurrentShape(comments) {
+    return selectCurrentShapeComment(mapIngestCommentsToShapeComments(comments));
+}
+/** Count maintainer current-shape comments (lint surface for !=1). */
+export function countIngestCurrentShapeComments(comments) {
+    return countMaintainerCurrentShapeComments(mapIngestCommentsToShapeComments(comments));
+}
 const STATUS_MAP = {
     proposed: ["proposed", "proposed"],
     pending: ["pending", "pending"],
@@ -326,6 +354,11 @@ export function buildIssueVbrief(issue, status, repoUrl, options = {}) {
     const bodyStr = typeof bodyRaw === "string" && bodyRaw.length > 0 ? bodyRaw : "";
     const commentThread = issueCommentThread(issue);
     const overviewSource = commentThread.length > 0 ? composeOverviewWithComments(bodyStr, commentThread) : bodyStr;
+    // #1870 / #1152: materialize the canonical Current shape comment as its own
+    // narrative so agents cannot plan umbrellas from the stale body alone. Prefer
+    // the same selector as `task umbrella:current-shape` (highest pass-N,
+    // maintainer-authored only — #2307).
+    const currentShape = selectIngestCurrentShape(commentThread);
     const labelsRaw = issue.labels;
     const labelNames = [];
     if (Array.isArray(labelsRaw)) {
@@ -366,6 +399,10 @@ export function buildIssueVbrief(issue, status, repoUrl, options = {}) {
         }
         narratives.Overview = scanResult.transformed_content;
     }
+    if (currentShape !== null) {
+        // Scan shape body under the same fail-closed contract as Overview (#2306).
+        narratives.CurrentShape = scanUntrustedIngestText(number, currentShape.body);
+    }
     if (labelNames.length > 0) {
         narratives.Labels = labelNames.join(", ");
     }
@@ -392,6 +429,16 @@ export function buildIssueVbrief(issue, status, repoUrl, options = {}) {
                 title: `Issue #${number}: ${title}`,
             },
         ];
+        if (currentShape !== null) {
+            const shapeUri = currentShape.htmlUrl.length > 0
+                ? currentShape.htmlUrl
+                : `${url}#issuecomment-${currentShape.id}`;
+            references.push({
+                uri: shapeUri,
+                type: CURRENT_SHAPE_REF_TYPE,
+                title: `Current shape (pass-${currentShape.pass}) for #${number}`,
+            });
+        }
         if (overviewSource.length > 0 && repoUrl.length > 0) {
             references.push(...extractCrossRefs(overviewSource, repoUrl, new Set([number])));
         }
@@ -446,6 +493,12 @@ export function fetchFromCache(repo, number, options = {}) {
         // the quarantine transform. When content.md is absent (e.g. a credential
         // hard-fail deleted it), the raw body falls through and is re-scanned in
         // buildIssueVbrief.
+        //
+        // #1870 note: content.md may also include the appended Canonical current
+        // shape section. That is intentional for agent-facing cache reads. When
+        // raw.comments is present we also restore the comment thread so
+        // narratives.CurrentShape + the current-shape reference can be materialised
+        // offline (without a live comments fetch).
         if (result.contentPath !== null) {
             try {
                 // #2314: content.md is `renderContent`-prefixed with a `# #<n>: <title>`
@@ -458,6 +511,11 @@ export function fetchFromCache(repo, number, options = {}) {
                 // fall back to the raw body (re-scanned downstream)
             }
         }
+        // #1870: restore comment thread from cache raw so CurrentShape survives
+        // offline / no-live-gh paths (fetchIssue still prefers live comments).
+        if (!issueCommentsAlreadyFetched(issue) && Array.isArray(issue[RAW_ISSUE_COMMENTS_KEY])) {
+            return attachIssueCommentThread(issue, issue[RAW_ISSUE_COMMENTS_KEY]);
+        }
         return issue;
     }
     catch {

package/dist/policy/index.d.ts

@@ -9,6 +9,7 @@ export * from "./host-hooks.js";
 export * from "./host-slash-commands.js";
 export * from "./hotfix-criteria.js";
 export * from "./intent-ceiling.js";
+export * from "./min-greptile-confidence.js";
 export * from "./no-deft-directive.js";
 export * from "./org-force-on-migration.js";
 export * from "./plan-extensions.js";
@@ -30,12 +31,15 @@ export declare const FIELD_TRIAGE_SCOPE_IGNORES = "plan.policy.triageScopeIgnore
 export declare const FIELD_TRIAGE_RANKING_LABELS = "plan.policy.triageRankingLabels";
 export declare const FIELD_TRIAGE_AUTO_CLASSIFY = "plan.policy.triageAutoClassify";
 export declare const FIELD_TRIAGE_HOLD_MARKERS = "plan.policy.triageHoldMarkers";
+export declare const FIELD_TRIAGE_LABEL_MIRROR = "plan.policy.triageLabelMirror";
 export declare const FIELD_SWARM_SUBAGENT_BACKEND = "plan.policy.swarmSubagentBackend";
 export declare const DEFAULT_SESSION_RITUAL_STALENESS_HOURS = 4;
 export declare const DEFAULT_TRIAGE_SCOPE_VALUE: readonly Record<string, unknown>[];
 export declare const DEFAULT_TRIAGE_SCOPE_IGNORES_VALUE: readonly unknown[];
 export declare const DEFAULT_TRIAGE_RANKING_LABELS_VALUE: readonly string[];
 export declare const DEFAULT_TRIAGE_AUTO_CLASSIFY_VALUE: readonly unknown[];
+/** Default for #1423 Tier-1 label mirror: enabled with `triaged` idempotency marker. */
+export declare const DEFAULT_TRIAGE_LABEL_MIRROR_VALUE: Readonly<Record<string, unknown>>;
 export declare const KNOWN_SUBAGENT_BACKEND_IDS: Set<string>;
 export interface PolicyField {
     readonly name: string;