@deftai/directive-core 0.103.0 → 0.105.0

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

@@ -13,10 +13,10 @@
  * Directive thin wrappers (`isThinWrapperMarkdown`). Consumer-customized content
  * at a product filename is left untouched.
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { existsSync, readFileSync } 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 { containedMkdir, containedRemove, containedRename, 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";
@@ -115,7 +115,7 @@ function writeHostCommandFileIfChanged(projectRoot, file) {
         }
     }
     const parent = dirname(absolute);
-    mkdirSync(parent, { recursive: true });
+    containedMkdir({ root: projectRoot, target: parent });
     // Atomic replace via temp under project root (#2951).
     const tmpName = `${basename(absolute)}.deft-${process.pid}.tmp`;
     const temporary = join(parent, tmpName);
@@ -126,11 +126,16 @@ function writeHostCommandFileIfChanged(projectRoot, file) {
             data: file.contents,
             mode: "replace",
         });
-        renameSync(temporary, absolute);
+        containedRename({
+            root: projectRoot,
+            from: temporary,
+            to: absolute,
+            mutation: false,
+        });
     }
     catch (err) {
         try {
-            rmSync(temporary, { force: true });
+            containedRemove({ root: projectRoot, target: temporary, mutation: false });
         }
         catch {
             /* best-effort cleanup */
@@ -162,8 +167,9 @@ function stripManagedHostCommandFiles(projectRoot, hostId) {
             continue;
         }
         try {
-            rmSync(absolute, { force: true });
-            removed.push(file.relativePath);
+            if (containedRemove({ root: projectRoot, target: absolute }).removed) {
+                removed.push(file.relativePath);
+            }
         }
         catch {
             /* best-effort */

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

@@ -7,11 +7,18 @@
  */
 /** Rewrite legacy vbrief/.eval description paths for xbrief/schemas projection (#2670). */
 export declare function rewriteProjectedSchemaContent(content: string): string;
+/** Fail closed when planned (source-rewritten) schema bytes still cite vbrief/.eval/. */
+export declare function assertPlannedSchemaDescriptionRooted(rel: string, text: string): void;
 /**
  * Fail closed when a projected xbrief/schemas file still cites vbrief/.eval/.
  * Upstream vbrief/schemas/ may keep legacy paths; consumer copies must not (#2670).
+ *
+ * `skipRel` is dest files the collect record plans to replace (#3456 plan-note):
+ * never validate stale dest bytes a skipped write would have replaced.
  */
-export declare function assertProjectedSchemaDescriptionsRooted(projectDir: string, destinationDir: string): void;
+export declare function assertProjectedSchemaDescriptionsRooted(projectDir: string, destinationDir: string, options?: {
+    readonly skipRel?: ReadonlySet<string>;
+}): void;
 /**
  * Synchronize framework-owned xBRIEF schemas while preserving unknown consumer
  * files. The obsolete v0.6 root schema is the only destination-only file this

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

@@ -5,9 +5,9 @@
  * freshness. A current `.deft/core/VERSION` therefore cannot short-circuit
  * these repairs.
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
-import { containedWrite } from "../fs/contained-write.js";
+import { containedMkdir, containedRemove, containedWrite } from "../fs/contained-write.js";
 import { assertDestinationNotSymlink } from "../fs/projection-containment.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { DEV_FALLBACK } from "../platform/constants.js";
@@ -50,20 +50,30 @@ export function rewriteProjectedSchemaContent(content) {
         ? content.replaceAll(LEGACY_EVAL_PATH_PREFIX, XBRIEF_EVAL_PATH_PREFIX)
         : content;
 }
+/** Fail closed when planned (source-rewritten) schema bytes still cite vbrief/.eval/. */
+export function assertPlannedSchemaDescriptionRooted(rel, text) {
+    if (text.includes(LEGACY_EVAL_PATH_PREFIX)) {
+        throw new Error(`projected xbrief schema still cites ${LEGACY_EVAL_PATH_PREFIX}: ${join(MIGRATED_ARTIFACT_DIR, "schemas", rel)}`);
+    }
+}
 /**
  * Fail closed when a projected xbrief/schemas file still cites vbrief/.eval/.
  * Upstream vbrief/schemas/ may keep legacy paths; consumer copies must not (#2670).
+ *
+ * `skipRel` is dest files the collect record plans to replace (#3456 plan-note):
+ * never validate stale dest bytes a skipped write would have replaced.
  */
-export function assertProjectedSchemaDescriptionsRooted(projectDir, destinationDir) {
+export function assertProjectedSchemaDescriptionsRooted(projectDir, destinationDir, options = {}) {
     assertDestinationNotSymlink(projectDir, destinationDir);
     if (!isDirectory(destinationDir))
         return;
+    const skipRel = options.skipRel;
     for (const rel of collectSchemaFiles(destinationDir)) {
+        if (skipRel?.has(rel))
+            continue;
         const full = join(destinationDir, rel);
         const text = readFileSync(full, "utf8");
-        if (text.includes(LEGACY_EVAL_PATH_PREFIX)) {
-            throw new Error(`projected xbrief schema still cites ${LEGACY_EVAL_PATH_PREFIX}: ${join(MIGRATED_ARTIFACT_DIR, "schemas", rel)}`);
-        }
+        assertPlannedSchemaDescriptionRooted(rel, text);
     }
 }
 function writeFileIfChanged(projectDir, target, content) {
@@ -99,23 +109,26 @@ export function syncConsumerXbriefSchemas(projectDir, deftDir) {
     }
     const destinationDir = join(projectDir, MIGRATED_ARTIFACT_DIR, "schemas");
     assertDestinationNotSymlink(projectDir, destinationDir);
-    mkdirSync(destinationDir, { recursive: true });
+    containedMkdir({ root: resolve(projectDir), target: destinationDir });
     let changed = false;
+    const plannedRel = new Set();
     for (const rel of collectSchemaFiles(sourceDir)) {
         if (rel === OBSOLETE_CORE_SCHEMA)
             continue;
         const source = join(sourceDir, rel);
         const destination = join(destinationDir, rel);
         const projected = rewriteProjectedSchemaContent(readFileSync(source, "utf8"));
+        // Planned content is the oracle. Dest bytes a skipped write would replace
+        // are not validated (#3456 plan-note).
+        assertPlannedSchemaDescriptionRooted(rel, projected);
+        plannedRel.add(rel);
         changed = writeFileIfChanged(projectDir, destination, projected) || changed;
     }
     const obsoleteDestination = join(destinationDir, OBSOLETE_CORE_SCHEMA);
-    assertDestinationNotSymlink(projectDir, obsoleteDestination);
-    if (existsSync(obsoleteDestination)) {
-        rmSync(obsoleteDestination, { force: true });
+    if (containedRemove({ root: projectDir, target: obsoleteDestination }).removed) {
         changed = true;
     }
-    assertProjectedSchemaDescriptionsRooted(projectDir, destinationDir);
+    assertProjectedSchemaDescriptionsRooted(projectDir, destinationDir, { skipRel: plannedRel });
     return changed;
 }
 function syncBareVersionMarkerWithPolicy(projectDir, version, allowRootFallback) {

package/dist/intake/clause-derivation.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Hand-authored briefs run #3323 clause derivation on activate/promote (#3360).
+ *
+ * issue:ingest already stamps clauses. The dominant consumer path authors the
+ * brief by hand; #3334 only required plan.acceptance to exist. This module is
+ * the missing derive step.
+ */
+import { type AcceptanceClause } from "../verify-ac/clauses.js";
+/** One-line remediation when a stamp has no statement-traceable clause (#3398). */
+export declare const CLAUSE_STAMP_IMPLEMENTATION_ONLY_REMEDIATION = "derive clauses from the statement's testable constraints";
+export type ClauseProvenance = "statement" | "implementation";
+export interface ProvenanceCounts {
+    readonly statement: number;
+    readonly implementation: number;
+}
+export interface TracedAcceptanceClause extends AcceptanceClause {
+    readonly provenance: ClauseProvenance;
+}
+export interface ClauseStampPreparation {
+    readonly ok: boolean;
+    readonly clauses: readonly TracedAcceptanceClause[];
+    readonly provenance_counts: ProvenanceCounts;
+    readonly ambiguity_attestation?: "none_found";
+    readonly remediation?: string;
+}
+export interface AmbiguityAttestationCheck {
+    readonly ok: boolean;
+    readonly attested: boolean;
+    readonly kind: "ambiguous-clause" | "none_found" | "missing";
+    readonly message: string;
+}
+/** True when activate/promote must run #3323 (absent, empty none_stated, or command-only). */
+export declare function needsClauseDerivation(acceptance: unknown): boolean;
+/** Task-statement text from title, narratives, and item Acceptance fields. */
+export declare function collectTaskStatementFromPlan(plan: Record<string, unknown>): string;
+export interface ClauseDerivationResult {
+    readonly applied: boolean;
+    readonly clauses: readonly (AcceptanceClause | TracedAcceptanceClause)[];
+    readonly notice: string;
+}
+/** Statement-traceable when the clause text or its identifiers appear in the statement. */
+export declare function traceClauseProvenance(clause: AcceptanceClause, statement: string): ClauseProvenance;
+export declare function countClauseProvenance(clauses: readonly TracedAcceptanceClause[]): ProvenanceCounts;
+/** Fail closed when every clause is implementation-provenance; else attest ambiguity. */
+export declare function prepareClauseStamp(clauses: readonly AcceptanceClause[], statement: string): ClauseStampPreparation;
+/** Config-error surface for verify:ac: attestation or an ambiguous clause with readings. */
+export declare function evaluateAmbiguityAttestation(acceptance: unknown): AmbiguityAttestationCheck;
+/**
+ * Annotate stamped clauses with provenance and an ambiguity attestation.
+ * An all-implementation stamp is stripped (never sufficient alone).
+ */
+export declare function applyClauseQualityToPlan(plan: Record<string, unknown>): ClauseDerivationResult;
+/** Ingest path: strip an implementation-only stamp and record the remediation. */
+export declare function applyClauseQualityForIngest(plan: Record<string, unknown>): ClauseDerivationResult;
+/**
+ * Stamp derived clauses onto plan.acceptance in place. Headless: records
+ * chosen_reading, never blocks on a question.
+ */
+export declare function applyClauseDerivationToPlan(plan: Record<string, unknown>, options?: {
+    readonly projectRoot?: string;
+    readonly emitStamp?: boolean;
+}): ClauseDerivationResult;
+/** Stable fingerprint of plan.acceptance for first-write / material-change detection (#3355). */
+export declare function acceptanceFingerprint(acceptance: unknown): string | null;
+/** True when next is a first write or a material change versus previous (#3355). */
+export declare function isMaterialAcceptanceChange(previous: unknown, next: unknown): boolean;
+/** Fail-open acceptance_stamp emission (same contract as issue:ingest / #3355). */
+export declare function emitAcceptanceStampFromPlan(projectRoot: string, plan: unknown, env?: NodeJS.ProcessEnv): void;
+/**
+ * Emit acceptance_stamp when plan.acceptance is first written or materially changed.
+ * State-observed: callers pass the before/after blocks from any lifecycle verb (#3355).
+ */
+export declare function maybeEmitAcceptanceStampFromChange(projectRoot: string, previous: unknown, next: unknown, env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=clause-derivation.d.ts.map

package/dist/intake/clause-derivation.js

@@ -0,0 +1,409 @@
+/**
+ * Hand-authored briefs run #3323 clause derivation on activate/promote (#3360).
+ *
+ * issue:ingest already stamps clauses. The dominant consumer path authors the
+ * brief by hand; #3334 only required plan.acceptance to exist. This module is
+ * the missing derive step.
+ */
+import { ENV_RUN_SUMMARY_PATH, RunSummaryEmitter, } from "../run-summary/index.js";
+import { deriveAcceptanceClauses, readAcceptanceClauses, serializeAcceptanceClauses, } from "../verify-ac/clauses.js";
+/** One-line remediation when a stamp has no statement-traceable clause (#3398). */
+export const CLAUSE_STAMP_IMPLEMENTATION_ONLY_REMEDIATION = "derive clauses from the statement's testable constraints";
+const NARRATIVE_KEYS = [
+    "Overview",
+    "Description",
+    "Acceptance",
+    "AcceptanceCriteria",
+    "Acceptance sketch",
+    "AcceptanceSketch",
+    "Test",
+    "Verification",
+    "ImplementationPlan",
+];
+function asRecord(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/** True when activate/promote must run #3323 (absent, empty none_stated, or command-only). */
+export function needsClauseDerivation(acceptance) {
+    if (acceptance === undefined || acceptance === null) {
+        return true;
+    }
+    const rec = asRecord(acceptance);
+    if (rec === null) {
+        return true;
+    }
+    return !(Array.isArray(rec.clauses) && rec.clauses.length > 0);
+}
+/** Task-statement text from title, narratives, and item Acceptance fields. */
+export function collectTaskStatementFromPlan(plan) {
+    const parts = [];
+    if (isNonEmptyString(plan.title)) {
+        parts.push(plan.title.trim());
+    }
+    const narratives = asRecord(plan.narratives);
+    if (narratives !== null) {
+        const seen = new Set();
+        for (const key of NARRATIVE_KEYS) {
+            const value = narratives[key];
+            if (isNonEmptyString(value)) {
+                parts.push(value.trim());
+                seen.add(key.toLowerCase());
+            }
+        }
+        for (const [key, value] of Object.entries(narratives)) {
+            if (seen.has(key.toLowerCase()) || !isNonEmptyString(value)) {
+                continue;
+            }
+            parts.push(value.trim());
+        }
+    }
+    if (Array.isArray(plan.items)) {
+        for (const item of plan.items) {
+            const rec = asRecord(item);
+            if (rec === null) {
+                continue;
+            }
+            const narrative = asRecord(rec.narrative);
+            const text = narrative?.Acceptance;
+            if (isNonEmptyString(text)) {
+                parts.push(text.trim());
+            }
+        }
+    }
+    return parts.join("\n\n");
+}
+function hasAmbiguousReadings(clause) {
+    return clause.ambiguous === true && (clause.readings?.length ?? 0) > 0;
+}
+function extractClauseTokens(text) {
+    const found = [];
+    const seen = new Set();
+    const push = (raw) => {
+        const token = raw.trim();
+        if (token.length < 2 || seen.has(token)) {
+            return;
+        }
+        seen.add(token);
+        found.push(token);
+    };
+    const quoted = /["'`]([^"'`\n]{2,80})["'`]/g;
+    let match = quoted.exec(text);
+    while (match !== null) {
+        push(match[1] ?? "");
+        match = quoted.exec(text);
+    }
+    const pathRe = /(?<![A-Za-z0-9_])((?:[A-Za-z0-9_.-]+\/)+[A-Za-z0-9_.-]+\.[A-Za-z][A-Za-z0-9]+)(?![A-Za-z0-9_])/g;
+    match = pathRe.exec(text);
+    while (match !== null) {
+        push(match[1] ?? "");
+        match = pathRe.exec(text);
+    }
+    const ident = /(?<![A-Za-z0-9_])([A-Za-z_][A-Za-z0-9_]*)(?![A-Za-z0-9_])/g;
+    match = ident.exec(text);
+    while (match !== null) {
+        const token = match[1] ?? "";
+        const camelOrPascal = /[a-z][A-Z]/.test(token) || /[A-Z][a-z]+[A-Z]/.test(token);
+        const codeShaped = camelOrPascal || token.includes("_");
+        if (codeShaped) {
+            push(token);
+        }
+        match = ident.exec(text);
+    }
+    return found;
+}
+/** Statement-traceable when the clause text or its identifiers appear in the statement. */
+export function traceClauseProvenance(clause, statement) {
+    const normClause = clause.text.replace(/\s+/g, " ").trim();
+    const normStatement = statement.replace(/\s+/g, " ").trim();
+    if (normClause.length > 0 && normStatement.includes(normClause)) {
+        return "statement";
+    }
+    const tokens = extractClauseTokens(clause.text);
+    if (tokens.length === 0) {
+        return "implementation";
+    }
+    return tokens.every((token) => statement.includes(token)) ? "statement" : "implementation";
+}
+export function countClauseProvenance(clauses) {
+    let statement = 0;
+    let implementation = 0;
+    for (const clause of clauses) {
+        if (clause.provenance === "statement") {
+            statement += 1;
+        }
+        else {
+            implementation += 1;
+        }
+    }
+    return { statement, implementation };
+}
+/** Fail closed when every clause is implementation-provenance; else attest ambiguity. */
+export function prepareClauseStamp(clauses, statement) {
+    const traced = clauses.map((clause) => ({
+        ...clause,
+        provenance: traceClauseProvenance(clause, statement),
+    }));
+    const provenance_counts = countClauseProvenance(traced);
+    if (traced.length > 0 && provenance_counts.statement === 0) {
+        return {
+            ok: false,
+            clauses: traced,
+            provenance_counts,
+            remediation: CLAUSE_STAMP_IMPLEMENTATION_ONLY_REMEDIATION,
+        };
+    }
+    return {
+        ok: true,
+        clauses: traced,
+        provenance_counts,
+        ambiguity_attestation: traced.some(hasAmbiguousReadings) ? undefined : "none_found",
+    };
+}
+const AMBIGUITY_ATTESTATION_MISSING = "verify:ac config error: missing ambiguity attestation; record at least one ambiguous: true clause with readings, or set ambiguity_attestation: none_found";
+/** Config-error surface for verify:ac: attestation or an ambiguous clause with readings. */
+export function evaluateAmbiguityAttestation(acceptance) {
+    const rec = asRecord(acceptance);
+    if (rec === null) {
+        return { ok: false, attested: false, kind: "missing", message: AMBIGUITY_ATTESTATION_MISSING };
+    }
+    const clauses = readAcceptanceClauses(rec);
+    if (clauses.some(hasAmbiguousReadings)) {
+        return { ok: true, attested: true, kind: "ambiguous-clause", message: "" };
+    }
+    if (rec.ambiguity_attestation === "none_found") {
+        return { ok: true, attested: true, kind: "none_found", message: "" };
+    }
+    return { ok: false, attested: false, kind: "missing", message: AMBIGUITY_ATTESTATION_MISSING };
+}
+function serializeTracedClauses(clauses) {
+    return serializeAcceptanceClauses(clauses).map((row, index) => ({
+        ...row,
+        provenance: clauses[index]?.provenance ?? "implementation",
+    }));
+}
+/**
+ * Annotate stamped clauses with provenance and an ambiguity attestation.
+ * An all-implementation stamp is stripped (never sufficient alone).
+ */
+export function applyClauseQualityToPlan(plan) {
+    const existing = asRecord(plan.acceptance);
+    if (existing === null) {
+        return { applied: false, clauses: [], notice: "" };
+    }
+    const clauses = readAcceptanceClauses(existing);
+    if (clauses.length === 0) {
+        return { applied: false, clauses: [], notice: "" };
+    }
+    const prepared = prepareClauseStamp(clauses, collectTaskStatementFromPlan(plan));
+    if (!prepared.ok) {
+        const next = { ...existing };
+        delete next.clauses;
+        plan.acceptance = next;
+        return {
+            applied: false,
+            clauses: prepared.clauses,
+            notice: prepared.remediation ?? CLAUSE_STAMP_IMPLEMENTATION_ONLY_REMEDIATION,
+        };
+    }
+    const next = {
+        ...existing,
+        clauses: serializeTracedClauses(prepared.clauses),
+    };
+    if (prepared.ambiguity_attestation !== undefined &&
+        existing.ambiguity_attestation === undefined) {
+        next.ambiguity_attestation = prepared.ambiguity_attestation;
+    }
+    plan.acceptance = next;
+    return {
+        applied: true,
+        clauses: prepared.clauses,
+        notice: formatAmbiguousClauseNotice(prepared.clauses),
+    };
+}
+/** Ingest path: strip an implementation-only stamp and record the remediation. */
+export function applyClauseQualityForIngest(plan) {
+    const quality = applyClauseQualityToPlan(plan);
+    if (!quality.applied && quality.notice.length > 0) {
+        const existing = asRecord(plan.acceptance);
+        if (existing !== null) {
+            plan.acceptance = {
+                ...existing,
+                derived_reason: quality.notice,
+                quality_notice: quality.notice,
+            };
+        }
+    }
+    return quality;
+}
+function formatAmbiguousClauseNotice(clauses) {
+    const flagged = clauses.filter((clause) => clause.ambiguous);
+    const lines = [
+        `#3323 clause derivation stamped ${clauses.length} clause(s)` +
+            (flagged.length > 0 ? `; flagged-ambiguous: ${flagged.length}` : ""),
+    ];
+    for (const clause of flagged) {
+        const chosen = clause.chosen_reading ?? 0;
+        const chosenPath = clause.readings?.[chosen]?.artifact_path ?? clause.artifact_path ?? "(none)";
+        lines.push(`  clause ${clause.id}: two readings; chosen_reading=${chosen} (${chosenPath}) [headless #3323]`);
+        for (const [index, reading] of (clause.readings ?? []).entries()) {
+            lines.push(`    reading ${index}: ${reading.artifact_path ?? "(none)"}`);
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Stamp derived clauses onto plan.acceptance in place. Headless: records
+ * chosen_reading, never blocks on a question.
+ */
+export function applyClauseDerivationToPlan(plan, options = {}) {
+    if (!needsClauseDerivation(plan.acceptance)) {
+        return {
+            applied: false,
+            clauses: readAcceptanceClauses(plan.acceptance),
+            notice: "",
+        };
+    }
+    const clauses = deriveAcceptanceClauses(collectTaskStatementFromPlan(plan));
+    if (clauses.length === 0) {
+        return { applied: false, clauses: [], notice: "" };
+    }
+    const existing = asRecord(plan.acceptance);
+    const commands = existing !== null && Array.isArray(existing.commands) ? existing.commands : [];
+    const hasCommands = commands.length > 0;
+    const noneStated = hasCommands ? existing?.none_stated === true : true;
+    const sourceRung = hasCommands && existing?.none_stated !== true
+        ? isNonEmptyString(existing?.source_rung)
+            ? existing.source_rung
+            : "stated"
+        : "derived";
+    const previousAcceptance = plan.acceptance;
+    plan.acceptance = {
+        ...(existing ?? {}),
+        commands: hasCommands ? commands : [],
+        none_stated: noneStated,
+        source_rung: sourceRung,
+        derived_reason: `derived ${clauses.length} independently testable clauses from the task statement before product edit (#3323)`,
+        clauses: serializeAcceptanceClauses(clauses),
+    };
+    const quality = applyClauseQualityToPlan(plan);
+    if (!quality.applied) {
+        const existing = asRecord(previousAcceptance);
+        if (existing !== null && quality.notice.length > 0) {
+            plan.acceptance = {
+                ...existing,
+                quality_notice: quality.notice,
+                derived_reason: quality.notice,
+            };
+        }
+        else {
+            plan.acceptance = previousAcceptance;
+        }
+        return {
+            applied: false,
+            clauses: quality.clauses,
+            notice: quality.notice,
+        };
+    }
+    if (options.emitStamp !== false && options.projectRoot !== undefined) {
+        emitAcceptanceStampFromPlan(options.projectRoot, plan);
+    }
+    return {
+        applied: true,
+        clauses: quality.clauses,
+        notice: quality.notice,
+    };
+}
+/** Stable fingerprint of plan.acceptance for first-write / material-change detection (#3355). */
+export function acceptanceFingerprint(acceptance) {
+    const rec = asRecord(acceptance);
+    if (rec === null) {
+        return null;
+    }
+    const commands = Array.isArray(rec.commands) ? rec.commands.length : 0;
+    const clauses = Array.isArray(rec.clauses)
+        ? rec.clauses.map((entry, index) => {
+            const row = asRecord(entry);
+            if (row === null) {
+                return `${index}`;
+            }
+            return `${row.id ?? index}:${row.text ?? ""}:${row.artifact_path ?? ""}`;
+        })
+        : [];
+    const rung = typeof rec.source_rung === "string" ? rec.source_rung : "";
+    return `${rung}|${rec.none_stated === true}|${commands}|${clauses.join(";")}`;
+}
+/** True when next is a first write or a material change versus previous (#3355). */
+export function isMaterialAcceptanceChange(previous, next) {
+    const nextFp = acceptanceFingerprint(next);
+    if (nextFp === null) {
+        return false;
+    }
+    return acceptanceFingerprint(previous) !== nextFp;
+}
+/** Fail-open acceptance_stamp emission (same contract as issue:ingest / #3355). */
+export function emitAcceptanceStampFromPlan(projectRoot, plan, env = process.env) {
+    const rec = asRecord(plan);
+    if (rec === null) {
+        return;
+    }
+    const acceptance = asRecord(rec.acceptance);
+    if (acceptance === null) {
+        return;
+    }
+    const dest = env[ENV_RUN_SUMMARY_PATH];
+    if (dest === undefined || dest.trim().length === 0) {
+        return;
+    }
+    try {
+        const emitter = new RunSummaryEmitter({
+            projectRoot,
+            env,
+            component: "clause-derivation",
+        });
+        const commands = Array.isArray(acceptance.commands) ? acceptance.commands.length : 0;
+        const clauses = Array.isArray(acceptance.clauses) ? acceptance.clauses.length : 0;
+        const statement = collectTaskStatementFromPlan(rec);
+        const rawRows = Array.isArray(acceptance.clauses) ? acceptance.clauses : [];
+        const traced = readAcceptanceClauses(acceptance).map((clause, index) => {
+            const row = asRecord(rawRows[index]);
+            const stamped = row?.provenance === "statement" || row?.provenance === "implementation"
+                ? row.provenance
+                : undefined;
+            return {
+                ...clause,
+                provenance: stamped ??
+                    (statement.trim().length > 0 ? traceClauseProvenance(clause, statement) : "statement"),
+            };
+        });
+        const payload = {
+            rung: typeof acceptance.source_rung === "string" ? acceptance.source_rung : "project_floor",
+            none_stated: acceptance.none_stated === true,
+            command_count: commands,
+            clause_count: clauses,
+            provenance_counts: countClauseProvenance(traced),
+            ambiguity_attested: evaluateAmbiguityAttestation(acceptance).attested,
+        };
+        emitter.emitAcceptanceStamp(payload);
+    }
+    catch {
+        // fail-open
+    }
+}
+/**
+ * Emit acceptance_stamp when plan.acceptance is first written or materially changed.
+ * State-observed: callers pass the before/after blocks from any lifecycle verb (#3355).
+ */
+export function maybeEmitAcceptanceStampFromChange(projectRoot, previous, next, env = process.env) {
+    if (!isMaterialAcceptanceChange(previous, next)) {
+        return false;
+    }
+    emitAcceptanceStampFromPlan(projectRoot, { acceptance: next }, env);
+    return true;
+}
+//# sourceMappingURL=clause-derivation.js.map

package/dist/intake/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./candidates-log.js";
+export * from "./clause-derivation.js";
 export * from "./github-auth-modes.js";
 export { resultToDict } from "./github-auth-modes.js";
 export * from "./github-body.js";

package/dist/intake/index.js

@@ -1,4 +1,5 @@
 export * from "./candidates-log.js";
+export * from "./clause-derivation.js";
 export * from "./github-auth-modes.js";
 export { resultToDict } from "./github-auth-modes.js";
 export * from "./github-body.js";

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

@@ -58,6 +58,8 @@ export declare function buildIssueVbrief(issue: Record<string, unknown>, status:
     infoRootKey?: typeof LEGACY_INFO_ROOT_KEY | typeof MIGRATED_INFO_ROOT_KEY;
     infoVersion?: string;
 }): [Record<string, unknown>, string];
+/** Include a refused-stamp remediation on the ingest result so it is not silent. */
+export declare function formatIngestCreatedMessage(folder: string, filename: string, plan: unknown, dryRun?: boolean): string;
 export declare function targetFilename(number: number, title: string, artifactSuffix?: typeof LEGACY_ARTIFACT_SUFFIX | typeof MIGRATED_ARTIFACT_SUFFIX): string;
 export interface FetchIssueOptions {
     readonly cwd?: string | null;
@@ -116,5 +118,5 @@ export declare function ingestSingleForAccept(n: number, repo: string, options?:
     projectRoot?: string | null;
     status?: IngestStatus;
     cacheRoot?: string | null;
-}): [IngestResult, string | null];
+}): [IngestResult, string | null, string];
 //# sourceMappingURL=issue-ingest.d.ts.map