@deftai/directive-core 0.104.0 → 0.106.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

@@ -6,15 +6,61 @@
  * 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 declare const MISSING_AMBIGUITY_ATTESTATION_CAUSE: "missing_ambiguity_attestation";
+export declare const AMBIGUITY_ATTESTATION_REMEDIATION = "record ambiguity readings or attest none_found";
+export interface AmbiguityAttestationCheck {
+    readonly ok: boolean;
+    readonly attested: boolean;
+    readonly kind: "ambiguous-clause" | "none_found" | "missing";
+    readonly message: string;
+    readonly cause?: typeof MISSING_AMBIGUITY_ATTESTATION_CAUSE;
+    readonly remediation?: 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[];
+    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;
+/**
+ * Fail-closed check for a *stamped* plan.acceptance (#3559).
+ * Command-only / empty floor blocks are not stamps; they keep the empty-resolution path.
+ */
+export declare function stampedAmbiguityAttestationError(acceptance: unknown): AmbiguityAttestationCheck | null;
+/**
+ * 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.

package/dist/intake/clause-derivation.js

@@ -5,8 +5,12 @@
  * 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 { 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";
+export const MISSING_AMBIGUITY_ATTESTATION_CAUSE = "missing_ambiguity_attestation";
+export const AMBIGUITY_ATTESTATION_REMEDIATION = "record ambiguity readings or attest none_found";
 const NARRATIVE_KEYS = [
     "Overview",
     "Description",
@@ -76,6 +80,194 @@ export function collectTaskStatementFromPlan(plan) {
     }
     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; ${AMBIGUITY_ATTESTATION_REMEDIATION}`;
+function missingAttestationCheck() {
+    return {
+        ok: false,
+        attested: false,
+        kind: "missing",
+        message: AMBIGUITY_ATTESTATION_MISSING,
+        cause: MISSING_AMBIGUITY_ATTESTATION_CAUSE,
+        remediation: AMBIGUITY_ATTESTATION_REMEDIATION,
+    };
+}
+/** 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 missingAttestationCheck();
+    }
+    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 missingAttestationCheck();
+}
+/**
+ * Fail-closed check for a *stamped* plan.acceptance (#3559).
+ * Command-only / empty floor blocks are not stamps; they keep the empty-resolution path.
+ */
+export function stampedAmbiguityAttestationError(acceptance) {
+    const rec = asRecord(acceptance);
+    if (rec === null) {
+        return null;
+    }
+    if (readAcceptanceClauses(rec).length === 0) {
+        return null;
+    }
+    const check = evaluateAmbiguityAttestation(rec);
+    return check.ok ? null : check;
+}
+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 = [
@@ -117,6 +309,7 @@ export function applyClauseDerivationToPlan(plan, options = {}) {
             ? existing.source_rung
             : "stated"
         : "derived";
+    const previousAcceptance = plan.acceptance;
     plan.acceptance = {
         ...(existing ?? {}),
         commands: hasCommands ? commands : [],
@@ -125,13 +318,32 @@ export function applyClauseDerivationToPlan(plan, options = {}) {
         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,
-        notice: formatAmbiguousClauseNotice(clauses),
+        clauses: quality.clauses,
+        notice: quality.notice,
     };
 }
 /** Stable fingerprint of plan.acceptance for first-write / material-change detection (#3355). */
@@ -176,18 +388,35 @@ export function emitAcceptanceStampFromPlan(projectRoot, plan, env = process.env
         return;
     }
     try {
-        const sessionId = typeof env.DEFT_SESSION_ID === "string" && env.DEFT_SESSION_ID.trim().length > 0
-            ? env.DEFT_SESSION_ID.trim()
-            : "clause-derivation";
-        const emitter = new RunSummaryEmitter({ projectRoot, sessionId, env });
+        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;
-        emitter.emitAcceptanceStamp({
+        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

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

package/dist/intake/issue-ingest.js

@@ -5,6 +5,7 @@ import { scan } from "../cache/scanner.js";
 import { assertWriteTargetSafe, ProjectionContainmentError } from "../fs/projection-containment.js";
 import { hasArtifactSuffix, resolveLifecycleRoot } from "../layout/resolve.js";
 import { captureAndAttachLiteralAcceptance } from "../literal-acceptance/index.js";
+import { stampIntendedPlacement } from "../preflight/intended-placement.js";
 import { stampAcceptanceFromLiteralCapture } from "../product-first-done-gate/index.js";
 import { call } from "../scm/call.js";
 import { resolveProjectRoot } from "../scope/project-context.js";
@@ -14,7 +15,7 @@ import { slugify, TODAY } from "../vbrief-build/build.js";
 import { EMITTED_VBRIEF_VERSION } from "../vbrief-build/constants.js";
 import { stampDerivedClausesOnAcceptance } from "../verify-ac/clauses.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 { emitAcceptanceStampFromPlan } from "./clause-derivation.js";
+import { applyClauseQualityForIngest, emitAcceptanceStampFromPlan } from "./clause-derivation.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). */
@@ -480,11 +481,13 @@ export function buildIssueVbrief(issue, status, repoUrl, options = {}) {
         // #3323: when no commands were stated, derive numbered clauses before product edit.
         const derived = stampDerivedClausesOnAcceptance(plan, [title, overviewSource].filter((s) => s.length > 0).join("\n\n"));
         Object.assign(plan, derived.plan);
+        applyClauseQualityForIngest(plan);
     }
     else {
         // No body: still record none_stated acceptance so absence is a decision.
         Object.assign(plan, stampAcceptanceFromLiteralCapture(plan));
     }
+    stampIntendedPlacement(plan);
     const infoRootKey = options.infoRootKey ?? LEGACY_INFO_ROOT_KEY;
     const infoVersion = options.infoVersion ?? EMITTED_VBRIEF_VERSION;
     const briefLabel = infoRootKey === MIGRATED_INFO_ROOT_KEY ? "xBRIEF" : "vBRIEF";
@@ -499,6 +502,24 @@ export function buildIssueVbrief(issue, status, repoUrl, options = {}) {
         folder,
     ];
 }
+/** Include a refused-stamp remediation on the ingest result so it is not silent. */
+export function formatIngestCreatedMessage(folder, filename, plan, dryRun = false) {
+    const lead = dryRun
+        ? `DRY-RUN would write ${folder}/${filename}`
+        : `CREATED ${folder}/${filename}`;
+    if (typeof plan !== "object" || plan === null || Array.isArray(plan)) {
+        return lead;
+    }
+    const acceptance = plan.acceptance;
+    if (typeof acceptance !== "object" || acceptance === null || Array.isArray(acceptance)) {
+        return lead;
+    }
+    const notice = acceptance.quality_notice;
+    if (typeof notice !== "string" || notice.trim().length === 0) {
+        return lead;
+    }
+    return `${lead}\n${notice.trim()}`;
+}
 export function targetFilename(number, title, artifactSuffix = LEGACY_ARTIFACT_SUFFIX) {
     const slug = slugify(title) || `issue-${number}`;
     return `${TODAY}-${number}-${slug}${artifactSuffix}`;
@@ -707,7 +728,7 @@ export function ingestOne(issue, options) {
     const folderPath = join(options.vbriefDir, folder);
     const target = join(folderPath, filename);
     if (options.dryRun) {
-        return ["dryrun", target, `DRY-RUN would write ${folder}/${filename}`];
+        return ["dryrun", target, formatIngestCreatedMessage(folder, filename, vbrief.plan, true)];
     }
     // Gate lifecycle folder + leaf before mkdir/write so folder/parent symlinks
     // cannot divert issue:ingest / triage:accept outside the project (#2869).
@@ -724,7 +745,7 @@ export function ingestOne(issue, options) {
     mkdirSync(folderPath, { recursive: true });
     writeFileSync(target, `${JSON.stringify(vbrief, null, 2)}\n`, "utf8");
     emitAcceptanceStampFromPlan(projectRoot, vbrief.plan);
-    return ["created", target, `CREATED ${folder}/${filename}`];
+    return ["created", target, formatIngestCreatedMessage(folder, filename, vbrief.plan)];
 }
 export function ingestBulk(issues, options) {
     let filtered = issues;
@@ -753,6 +774,7 @@ export function ingestBulk(issues, options) {
         duplicate: [],
         dryrun: [],
         failed: [],
+        notices: [],
     };
     for (const issue of filtered) {
         let ingested;
@@ -770,9 +792,12 @@ export function ingestBulk(issues, options) {
             }
             throw exc;
         }
-        const [result, path, _msg] = ingested;
+        const [result, path, msg] = ingested;
         const rel = path !== null ? path.replace(`${options.vbriefDir}/`, "").replace(/\\/g, "/") : "";
         summary[result].push(rel);
+        if (msg.includes("\n")) {
+            summary.notices.push(msg);
+        }
         if (result === "created" && path !== null) {
             const num = Number(issue.number);
             const existing = refs.get(num) ?? [];
@@ -840,6 +865,9 @@ export function issueIngestMain(args) {
         for (const entry of created) {
             process.stdout.write(`  CREATED ${entry}\n`);
         }
+        for (const notice of summary.notices ?? []) {
+            process.stdout.write(`${notice}\n`);
+        }
         for (const entry of dryrun) {
             process.stdout.write(`  DRY-RUN ${entry}\n`);
         }
@@ -890,12 +918,13 @@ export function ingestSingleForAccept(n, repo, options = {}) {
     if (issue === null) {
         throw new Error(`failed to fetch GitHub issue #${n} from ${repo} (unified cache miss + live gh api fetch failed; see stderr)`);
     }
-    const [result, path] = ingestOne(issue, {
+    // Forward ingestOne's notice-bearing third return so triage:accept can
+    // print a refused-stamp remediation instead of only the decision id (#3398).
+    return ingestOne(issue, {
         vbriefDir,
         status: options.status ?? "proposed",
         repoUrl,
         cwd: root,
     });
-    return [result, path];
 }
 //# sourceMappingURL=issue-ingest.js.map

package/dist/lifecycle/completed-tracked-on-delivery.d.ts

@@ -25,6 +25,11 @@ export interface EvaluateCompletedTrackedOptions {
     readonly repo?: string | null;
     /** Explicit delivery tip ref (e.g. origin/master). Overrides policy/git default. */
     readonly tip?: string | null;
+    /**
+     * When set, check only this issue number (#3476 drive-to DONE).
+     * Sibling unlanded closed issues do not fail the per-issue scan.
+     */
+    readonly issue?: number | null;
     readonly runGh?: RunGhFn;
     readonly skipGh?: boolean;
     readonly runGit?: GitRunner;