@deftai/directive-core 0.92.0 → 0.94.0

package/dist/init-deposit/skill-discovery-hosts.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Multi-host skill discovery layouts + per-host opt-out (#75 residual).
+ *
+ * Deposits **skill** discovery dirs (thin SKILL.md pointers). Distinct from
+ * epic #55 slash/command paths (`.claude/commands/`, `.codex/prompts/`, …).
+ *
+ * | Host id | Relative skills directory |
+ * |---------|---------------------------|
+ * | claude  | `.claude/skills`          |
+ * | cursor  | `.cursor/skills`          |
+ * | codex   | `.codex/skills`           |
+ * | github  | `.github/skills`          |
+ *
+ * Policy: `plan.policy.hostSkillDiscovery` — per-host boolean, default all true.
+ * Opt-out skips deposit for that host only.
+ */
+/** Hosts with a known residual skill-discovery path matrix (#75). */
+export declare const SKILL_DISCOVERY_HOSTS: readonly ["claude", "cursor", "codex", "github"];
+export type SkillDiscoveryHostId = (typeof SKILL_DISCOVERY_HOSTS)[number];
+/** Repo-relative layout for one host’s skill discovery tree. */
+export interface HostSkillDiscoveryLayout {
+    readonly hostId: SkillDiscoveryHostId;
+    /**
+     * Repo-relative directory (posix, no trailing slash).
+     * Example: `.claude/skills`
+     */
+    readonly relativeDir: string;
+    /** Typical agent product that scans this path. */
+    readonly typicalHost: string;
+    /**
+     * Filename under `{relativeDir}/{skillDir}/` (always `SKILL.md` for v1 —
+     * same thin-pointer format as `.agents/skills/`).
+     */
+    readonly skillFilename: string;
+}
+/**
+ * Documented host id → skills directory mapping (#75 residual matrix).
+ * Frozen; additive registration only.
+ */
+export declare const HOST_SKILL_DISCOVERY_LAYOUTS: Readonly<Record<SkillDiscoveryHostId, HostSkillDiscoveryLayout>>;
+export declare const FIELD_HOST_SKILL_DISCOVERY = "plan.policy.hostSkillDiscovery";
+export declare const FIELD_HOST_SKILL_DISCOVERY_CLI_ALIAS = "hostSkillDiscovery";
+/** Per-host skill discovery deposit toggles (#75). Default: all enabled. */
+export type HostSkillDiscoveryPolicy = Record<SkillDiscoveryHostId, boolean>;
+export declare const DEFAULT_HOST_SKILL_DISCOVERY_POLICY: HostSkillDiscoveryPolicy;
+export interface HostSkillDiscoveryPolicyField {
+    readonly name: string;
+    readonly current: HostSkillDiscoveryPolicy;
+    readonly default: HostSkillDiscoveryPolicy;
+    readonly source: string;
+}
+/** Type guard for {@link SkillDiscoveryHostId}. */
+export declare function isSkillDiscoveryHostId(value: string): value is SkillDiscoveryHostId;
+/** Stable list of residual skill-discovery hosts. */
+export declare function listSkillDiscoveryHosts(): readonly SkillDiscoveryHostId[];
+/** Look up the documented layout for a host, or throw. */
+export declare function getHostSkillDiscoveryLayout(hostId: SkillDiscoveryHostId): HostSkillDiscoveryLayout;
+export interface ResolvedHostSkillDiscoveryPolicy {
+    readonly policy: HostSkillDiscoveryPolicy;
+    /** Non-empty when raw policy was malformed; callers SHOULD surface these. */
+    readonly warnings: readonly string[];
+    /**
+     * True when the entire raw value is unusable (not an object). Deposit SHOULD
+     * skip all hosts rather than silently apply defaults after a bad opt-out.
+     */
+    readonly refuseAll: boolean;
+}
+/**
+ * Resolve typed host skill discovery policy from raw PROJECT-DEFINITION value.
+ * Fail-closed on malformed opt-outs (#75 Greptile P1): bad host values disable
+ * that host; wholly non-object values refuse all multi-host deposit.
+ */
+export declare function resolveHostSkillDiscoveryPolicyDetailed(raw: unknown): ResolvedHostSkillDiscoveryPolicy;
+/** Resolve typed host skill discovery policy from raw PROJECT-DEFINITION value. */
+export declare function resolveHostSkillDiscoveryPolicy(raw: unknown): HostSkillDiscoveryPolicy;
+export declare function validateHostSkillDiscovery(value: unknown): string[];
+export declare function isHostSkillDiscoveryEnabled(host: SkillDiscoveryHostId, policy?: HostSkillDiscoveryPolicy): boolean;
+/** Inspector row for `policy:show --field=hostSkillDiscovery`. */
+export declare function inspectHostSkillDiscovery(data: Record<string, unknown> | null): HostSkillDiscoveryPolicyField;
+/** Load raw hostSkillDiscovery value from PROJECT-DEFINITION, if present. */
+export declare function loadHostSkillDiscoveryRawFromProject(projectRoot: string): unknown;
+/** Resolve host skill discovery policy from PROJECT-DEFINITION on disk. */
+export declare function loadHostSkillDiscoveryPolicyFromProject(projectRoot: string): HostSkillDiscoveryPolicy;
+/**
+ * Resolve policy + validation warnings from PROJECT-DEFINITION for deposit.
+ * Surfaces malformed opt-outs so init/update can report them (#75 Greptile P1).
+ */
+export declare function loadHostSkillDiscoveryPolicyDetailedFromProject(projectRoot: string): ResolvedHostSkillDiscoveryPolicy;
+/**
+ * Repo-relative posix path for one skill under a host layout.
+ * Example: `.claude/skills/deft-directive-build/SKILL.md`
+ */
+export declare function hostSkillRelativePath(hostId: SkillDiscoveryHostId, skillDir: string): string;
+//# sourceMappingURL=skill-discovery-hosts.d.ts.map

package/dist/init-deposit/skill-discovery-hosts.js

@@ -0,0 +1,217 @@
+/**
+ * Multi-host skill discovery layouts + per-host opt-out (#75 residual).
+ *
+ * Deposits **skill** discovery dirs (thin SKILL.md pointers). Distinct from
+ * epic #55 slash/command paths (`.claude/commands/`, `.codex/prompts/`, …).
+ *
+ * | Host id | Relative skills directory |
+ * |---------|---------------------------|
+ * | claude  | `.claude/skills`          |
+ * | cursor  | `.cursor/skills`          |
+ * | codex   | `.codex/skills`           |
+ * | github  | `.github/skills`          |
+ *
+ * Policy: `plan.policy.hostSkillDiscovery` — per-host boolean, default all true.
+ * Opt-out skips deposit for that host only.
+ */
+import { readPlanPolicy } from "../policy/plan-extensions.js";
+import { loadProjectDefinition } from "../policy/resolve.js";
+/** Hosts with a known residual skill-discovery path matrix (#75). */
+export const SKILL_DISCOVERY_HOSTS = ["claude", "cursor", "codex", "github"];
+/**
+ * Documented host id → skills directory mapping (#75 residual matrix).
+ * Frozen; additive registration only.
+ */
+export const HOST_SKILL_DISCOVERY_LAYOUTS = Object.freeze({
+    claude: Object.freeze({
+        hostId: "claude",
+        relativeDir: ".claude/skills",
+        typicalHost: "Claude Code",
+        skillFilename: "SKILL.md",
+    }),
+    cursor: Object.freeze({
+        hostId: "cursor",
+        relativeDir: ".cursor/skills",
+        typicalHost: "Cursor",
+        skillFilename: "SKILL.md",
+    }),
+    codex: Object.freeze({
+        hostId: "codex",
+        relativeDir: ".codex/skills",
+        typicalHost: "OpenAI Codex",
+        skillFilename: "SKILL.md",
+    }),
+    github: Object.freeze({
+        hostId: "github",
+        relativeDir: ".github/skills",
+        typicalHost: "GitHub Copilot",
+        skillFilename: "SKILL.md",
+    }),
+});
+export const FIELD_HOST_SKILL_DISCOVERY = "plan.policy.hostSkillDiscovery";
+export const FIELD_HOST_SKILL_DISCOVERY_CLI_ALIAS = "hostSkillDiscovery";
+export const DEFAULT_HOST_SKILL_DISCOVERY_POLICY = {
+    claude: true,
+    cursor: true,
+    codex: true,
+    github: true,
+};
+/** Type guard for {@link SkillDiscoveryHostId}. */
+export function isSkillDiscoveryHostId(value) {
+    return SKILL_DISCOVERY_HOSTS.includes(value);
+}
+/** Stable list of residual skill-discovery hosts. */
+export function listSkillDiscoveryHosts() {
+    return SKILL_DISCOVERY_HOSTS;
+}
+/** Look up the documented layout for a host, or throw. */
+export function getHostSkillDiscoveryLayout(hostId) {
+    const layout = HOST_SKILL_DISCOVERY_LAYOUTS[hostId];
+    if (layout === undefined) {
+        throw new Error(`No skill discovery layout for host: ${hostId}`);
+    }
+    return layout;
+}
+/**
+ * Resolve one host toggle. Malformed present values fail closed to **disabled**
+ * (do not silently enable deposit when the operator attempted an opt-out shape).
+ */
+function readHostBoolean(rec, host, fallback, warnings) {
+    if (!(host in rec)) {
+        return fallback;
+    }
+    const value = rec[host];
+    if (typeof value === "boolean") {
+        return value;
+    }
+    warnings.push(`${FIELD_HOST_SKILL_DISCOVERY}.${host} must be a boolean (got ${typeof value}); treating as disabled`);
+    return false;
+}
+/**
+ * Resolve typed host skill discovery policy from raw PROJECT-DEFINITION value.
+ * Fail-closed on malformed opt-outs (#75 Greptile P1): bad host values disable
+ * that host; wholly non-object values refuse all multi-host deposit.
+ */
+export function resolveHostSkillDiscoveryPolicyDetailed(raw) {
+    if (raw === null || raw === undefined) {
+        return {
+            policy: { ...DEFAULT_HOST_SKILL_DISCOVERY_POLICY },
+            warnings: [],
+            refuseAll: false,
+        };
+    }
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        return {
+            policy: {
+                claude: false,
+                cursor: false,
+                codex: false,
+                github: false,
+            },
+            warnings: [
+                `${FIELD_HOST_SKILL_DISCOVERY} must be an object; got ${typeof raw} — multi-host skill discovery deposit skipped`,
+            ],
+            refuseAll: true,
+        };
+    }
+    const rec = raw;
+    const warnings = [];
+    for (const key of Object.keys(rec)) {
+        if (!isSkillDiscoveryHostId(key)) {
+            warnings.push(`${FIELD_HOST_SKILL_DISCOVERY}.${key} is not a skill-discovery host (${SKILL_DISCOVERY_HOSTS.join(", ")})`);
+        }
+    }
+    const policy = {
+        claude: readHostBoolean(rec, "claude", DEFAULT_HOST_SKILL_DISCOVERY_POLICY.claude, warnings),
+        cursor: readHostBoolean(rec, "cursor", DEFAULT_HOST_SKILL_DISCOVERY_POLICY.cursor, warnings),
+        codex: readHostBoolean(rec, "codex", DEFAULT_HOST_SKILL_DISCOVERY_POLICY.codex, warnings),
+        github: readHostBoolean(rec, "github", DEFAULT_HOST_SKILL_DISCOVERY_POLICY.github, warnings),
+    };
+    return { policy, warnings, refuseAll: false };
+}
+/** Resolve typed host skill discovery policy from raw PROJECT-DEFINITION value. */
+export function resolveHostSkillDiscoveryPolicy(raw) {
+    return resolveHostSkillDiscoveryPolicyDetailed(raw).policy;
+}
+export function validateHostSkillDiscovery(value) {
+    if (value === null || value === undefined) {
+        return [];
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return [`${FIELD_HOST_SKILL_DISCOVERY} must be an object; got ${typeof value}`];
+    }
+    const rec = value;
+    const errors = [];
+    for (const host of SKILL_DISCOVERY_HOSTS) {
+        if (host in rec && typeof rec[host] !== "boolean") {
+            errors.push(`${FIELD_HOST_SKILL_DISCOVERY}.${host} must be a boolean`);
+        }
+    }
+    for (const key of Object.keys(rec)) {
+        if (!isSkillDiscoveryHostId(key)) {
+            errors.push(`${FIELD_HOST_SKILL_DISCOVERY}.${key} is not a skill-discovery host (${SKILL_DISCOVERY_HOSTS.join(", ")})`);
+        }
+    }
+    return errors;
+}
+export function isHostSkillDiscoveryEnabled(host, policy = DEFAULT_HOST_SKILL_DISCOVERY_POLICY) {
+    return policy[host];
+}
+function fieldFromResolved(resolved, source) {
+    return {
+        name: FIELD_HOST_SKILL_DISCOVERY,
+        current: resolved,
+        default: DEFAULT_HOST_SKILL_DISCOVERY_POLICY,
+        source,
+    };
+}
+/** Inspector row for `policy:show --field=hostSkillDiscovery`. */
+export function inspectHostSkillDiscovery(data) {
+    if (data === null) {
+        return fieldFromResolved(DEFAULT_HOST_SKILL_DISCOVERY_POLICY, "default");
+    }
+    const policyBlock = readPlanPolicy(data.plan);
+    if (typeof policyBlock !== "object" ||
+        policyBlock === null ||
+        Array.isArray(policyBlock) ||
+        !("hostSkillDiscovery" in policyBlock)) {
+        return fieldFromResolved(DEFAULT_HOST_SKILL_DISCOVERY_POLICY, "default");
+    }
+    const resolved = resolveHostSkillDiscoveryPolicy(policyBlock.hostSkillDiscovery);
+    return fieldFromResolved(resolved, "typed");
+}
+/** Load raw hostSkillDiscovery value from PROJECT-DEFINITION, if present. */
+export function loadHostSkillDiscoveryRawFromProject(projectRoot) {
+    const [data] = loadProjectDefinition(projectRoot);
+    if (data === null) {
+        return undefined;
+    }
+    const policyBlock = readPlanPolicy(data.plan);
+    if (typeof policyBlock !== "object" ||
+        policyBlock === null ||
+        Array.isArray(policyBlock) ||
+        !("hostSkillDiscovery" in policyBlock)) {
+        return undefined;
+    }
+    return policyBlock.hostSkillDiscovery;
+}
+/** Resolve host skill discovery policy from PROJECT-DEFINITION on disk. */
+export function loadHostSkillDiscoveryPolicyFromProject(projectRoot) {
+    return resolveHostSkillDiscoveryPolicy(loadHostSkillDiscoveryRawFromProject(projectRoot));
+}
+/**
+ * Resolve policy + validation warnings from PROJECT-DEFINITION for deposit.
+ * Surfaces malformed opt-outs so init/update can report them (#75 Greptile P1).
+ */
+export function loadHostSkillDiscoveryPolicyDetailedFromProject(projectRoot) {
+    return resolveHostSkillDiscoveryPolicyDetailed(loadHostSkillDiscoveryRawFromProject(projectRoot));
+}
+/**
+ * Repo-relative posix path for one skill under a host layout.
+ * Example: `.claude/skills/deft-directive-build/SKILL.md`
+ */
+export function hostSkillRelativePath(hostId, skillDir) {
+    const layout = getHostSkillDiscoveryLayout(hostId);
+    return `${layout.relativeDir}/${skillDir}/${layout.skillFilename}`;
+}
+//# sourceMappingURL=skill-discovery-hosts.js.map

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

@@ -0,0 +1,46 @@
+/**
+ * Multi-host init/update deposit for native slash command files (#3054 / epic #55).
+ *
+ * Wires #3053 emitters into the init/update deposit path:
+ * - Default enabled set = hosts with real emitters (L6)
+ * - Per-host opt-out via `plan.policy.hostSlashCommands`
+ * - Idempotent managed rewrite (no duplicate pile-up)
+ * - Prefer commit of **managed product paths only** (L8) — exact allowlist, not whole dirs
+ *
+ * Parallel to agent-hooks deposit; does not touch hook JSON configs.
+ *
+ * Ownership: only create/update/remove files that are missing or still look like
+ * Directive thin wrappers (`isThinWrapperMarkdown`). Consumer-customized content
+ * at a product filename is left untouched.
+ */
+import { type HostSlashCommandsPolicy } from "../policy/host-slash-commands.js";
+import { type SlashEmitterHostId } from "../slash/index.js";
+import type { InitDepositIo } from "./constants.js";
+export interface SlashCommandDepositResult {
+    readonly changed: boolean;
+    /** Repo-relative paths written or updated. */
+    readonly writtenPaths: string[];
+    /** Repo-relative paths removed on opt-out (managed product files only). */
+    readonly removedPaths: string[];
+    /** Repo-relative paths skipped because consumer content is not managed. */
+    readonly preservedCustomPaths: string[];
+    /** Hosts that received a deposit pass (policy enabled). */
+    readonly depositedHosts: SlashEmitterHostId[];
+    /** Hosts skipped by policy opt-out. */
+    readonly skippedHosts: SlashEmitterHostId[];
+}
+/**
+ * Write thin-wrapper command/prompt files for every policy-enabled host.
+ *
+ * Idempotent: skips files whose on-disk bytes already match emission.
+ * Ownership-safe: never overwrites non-thin consumer customizations at product paths.
+ * Opt-out: removes managed thin wrappers only (leaves user customizations alone).
+ */
+export declare function writeSlashCommandDeposit(projectRoot: string, io?: InitDepositIo, policy?: HostSlashCommandsPolicy): SlashCommandDepositResult;
+/**
+ * Exact repo-relative product command paths (all emitter hosts).
+ * Used by installerManagedMatchers for L8 prefer-commit staging without
+ * claiming whole host command directories (consumer custom files stay app-owned).
+ */
+export declare function slashCommandManagedExactPaths(): readonly string[];
+//# sourceMappingURL=slash-deposit.d.ts.map

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

@@ -0,0 +1,174 @@
+/**
+ * Multi-host init/update deposit for native slash command files (#3054 / epic #55).
+ *
+ * Wires #3053 emitters into the init/update deposit path:
+ * - Default enabled set = hosts with real emitters (L6)
+ * - Per-host opt-out via `plan.policy.hostSlashCommands`
+ * - Idempotent managed rewrite (no duplicate pile-up)
+ * - Prefer commit of **managed product paths only** (L8) — exact allowlist, not whole dirs
+ *
+ * Parallel to agent-hooks deposit; does not touch hook JSON configs.
+ *
+ * Ownership: only create/update/remove files that are missing or still look like
+ * Directive thin wrappers (`isThinWrapperMarkdown`). Consumer-customized content
+ * at a product filename is left untouched.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { assertDepositContained } from "../deposit/contain.js";
+import { containedWrite } from "../fs/contained-write.js";
+import { isHostSlashCommandDepositEnabled, loadHostSlashCommandsPolicyFromProject, } from "../policy/host-slash-commands.js";
+import { emitHostCommandFiles, getHostCommandLayout, isThinWrapperMarkdown, listSlashEmitterHosts, } from "../slash/index.js";
+import { listProductCommands, logicalIdToFilename } from "../slash/product-set.js";
+/**
+ * Write thin-wrapper command/prompt files for every policy-enabled host.
+ *
+ * Idempotent: skips files whose on-disk bytes already match emission.
+ * Ownership-safe: never overwrites non-thin consumer customizations at product paths.
+ * Opt-out: removes managed thin wrappers only (leaves user customizations alone).
+ */
+export function writeSlashCommandDeposit(projectRoot, io = { printf: () => undefined }, policy = loadHostSlashCommandsPolicyFromProject(projectRoot)) {
+    const rootAbs = resolve(projectRoot);
+    const writtenPaths = [];
+    const removedPaths = [];
+    const preservedCustomPaths = [];
+    const depositedHosts = [];
+    const skippedHosts = [];
+    for (const hostId of listSlashEmitterHosts()) {
+        if (!isHostSlashCommandDepositEnabled(hostId, policy)) {
+            skippedHosts.push(hostId);
+            removedPaths.push(...stripManagedHostCommandFiles(rootAbs, hostId));
+            continue;
+        }
+        depositedHosts.push(hostId);
+        const files = emitHostCommandFiles(hostId);
+        for (const file of files) {
+            const outcome = writeHostCommandFileIfChanged(rootAbs, file);
+            if (outcome === "written")
+                writtenPaths.push(file.relativePath);
+            if (outcome === "preserved")
+                preservedCustomPaths.push(file.relativePath);
+        }
+    }
+    if (writtenPaths.length > 0) {
+        const hostSummary = depositedHosts.join(", ");
+        io.printf(`Installed Directive slash commands for hosts [${hostSummary}]: ${writtenPaths.length} file(s)\n`);
+    }
+    if (preservedCustomPaths.length > 0) {
+        io.printf(`Preserved non-managed slash command customizations: ${preservedCustomPaths.join(", ")}\n`);
+    }
+    if (removedPaths.length > 0) {
+        io.printf(`Removed Directive-managed slash commands (plan.policy.hostSlashCommands opt-out): ${removedPaths.join(", ")}\n`);
+    }
+    if (writtenPaths.length === 0 && removedPaths.length === 0) {
+        if (depositedHosts.length === 0) {
+            io.printf("Directive slash commands: all hosts opted out via plan.policy.hostSlashCommands.\n");
+        }
+        else {
+            io.printf("Directive slash commands already current.\n");
+        }
+    }
+    return {
+        changed: writtenPaths.length + removedPaths.length > 0,
+        writtenPaths,
+        removedPaths,
+        preservedCustomPaths,
+        depositedHosts,
+        skippedHosts,
+    };
+}
+/**
+ * Exact repo-relative product command paths (all emitter hosts).
+ * Used by installerManagedMatchers for L8 prefer-commit staging without
+ * claiming whole host command directories (consumer custom files stay app-owned).
+ */
+export function slashCommandManagedExactPaths() {
+    const paths = [];
+    for (const hostId of listSlashEmitterHosts()) {
+        const dir = getHostCommandLayout(hostId).relativeDir;
+        for (const cmd of listProductCommands()) {
+            paths.push(`${dir}/${logicalIdToFilename(cmd.logicalId)}`);
+        }
+    }
+    return paths;
+}
+function isManagedThinContent(raw, file) {
+    return raw === file.contents || isThinWrapperMarkdown(raw, file.dispatchPath);
+}
+function writeHostCommandFileIfChanged(projectRoot, file) {
+    const absolute = join(projectRoot, file.relativePath);
+    assertDepositContained(projectRoot, absolute);
+    if (existsSync(absolute)) {
+        let raw;
+        try {
+            raw = readFileSync(absolute, "utf8");
+        }
+        catch {
+            // Unreadable existing file: do not clobber consumer content.
+            return "preserved";
+        }
+        if (raw === file.contents)
+            return "unchanged";
+        // Ownership gate: only rewrite managed thin wrappers.
+        if (!isManagedThinContent(raw, file)) {
+            return "preserved";
+        }
+    }
+    const parent = dirname(absolute);
+    mkdirSync(parent, { recursive: true });
+    // Atomic replace via temp under project root (#2951).
+    const tmpName = `${basename(absolute)}.deft-${process.pid}.tmp`;
+    const temporary = join(parent, tmpName);
+    try {
+        containedWrite({
+            root: projectRoot,
+            target: temporary,
+            data: file.contents,
+            mode: "replace",
+        });
+        renameSync(temporary, absolute);
+    }
+    catch (err) {
+        try {
+            rmSync(temporary, { force: true });
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw err;
+    }
+    return "written";
+}
+/**
+ * On opt-out, remove only product-set managed thin wrappers for that host.
+ * User-authored or non-thin files under the host command dir are left untouched.
+ */
+function stripManagedHostCommandFiles(projectRoot, hostId) {
+    const removed = [];
+    const files = emitHostCommandFiles(hostId);
+    for (const file of files) {
+        const absolute = join(projectRoot, file.relativePath);
+        assertDepositContained(projectRoot, absolute);
+        if (!existsSync(absolute))
+            continue;
+        let raw;
+        try {
+            raw = readFileSync(absolute, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (!isManagedThinContent(raw, file)) {
+            continue;
+        }
+        try {
+            rmSync(absolute, { force: true });
+            removed.push(file.relativePath);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    return removed;
+}
+//# sourceMappingURL=slash-deposit.js.map

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 {