@deftai/directive-core 0.105.0 → 0.107.0

package/dist/product-first-done-gate/evaluate.js

@@ -9,11 +9,12 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { basename, isAbsolute, relative, resolve } from "node:path";
-import { emitAcceptanceStampFromPlan } from "../intake/clause-derivation.js";
-import { appendLiteralAcceptanceAdvisory, evaluateLiteralAcceptanceFromPlan, isNoopRefusalReason, runLiteralAcceptanceCommands, stripLiteralAcceptanceAdvisory, } from "../literal-acceptance/index.js";
+import { emitAcceptanceStampFromPlan, MISSING_AMBIGUITY_ATTESTATION_CAUSE, stampedAmbiguityAttestationError, } from "../intake/clause-derivation.js";
+import { appendLiteralAcceptanceAdvisory, evaluateLiteralAcceptanceFromPlan, isExecutableLiteralSource, isInlineProseMention, isNoopRefusalReason, readNotAcceptanceCommands, readStoredLiteralAcceptanceCommands, runLiteralAcceptanceCommands, stripLiteralAcceptanceAdvisory, } from "../literal-acceptance/index.js";
 import { ENV_RUN_SUMMARY_PATH, RunSummaryEmitter, } from "../run-summary/index.js";
 import { maybeBankOnAcPass } from "../session/ac-pass-banking.js";
 import { resolveAcReuse, resolveScopeIdForAcReuse, snapshotFromReuseFields, } from "../session/ac-pass-reuse.js";
+import { gitHead } from "../session/git.js";
 import { hashProductState } from "../session/product-state-hash.js";
 import { resolveVerifyAcSessionId, writeVerifyAcSessionCache, } from "../session/verify-ac-session-cache.js";
 import { formatClauseWalkMessage, walkAcceptanceClauses, } from "../verify-ac/clauses.js";
@@ -162,6 +163,24 @@ export function evaluateVerifyAcFromPlan(plan, options = {}) {
         }, optionsWithScope, plan);
     }
     const projectRoot = resolve(optionsWithScope.projectRoot ?? process.cwd());
+    const attestationError = stampedAmbiguityAttestationError(optionsWithScope.observedAcceptance !== undefined
+        ? optionsWithScope.observedAcceptance
+        : plan.acceptance);
+    if (attestationError !== null) {
+        return applyOracle({
+            ok: false,
+            code: 2,
+            message: optionsWithScope.quiet === true ? "" : attestationError.message,
+            commands: [],
+            runs: [],
+            sourceRung: acceptance.source_rung,
+            noneStated: acceptance.none_stated,
+            acceptance,
+            resolution: "config",
+            resolvedCommandCount: 0,
+            cause: attestationError.cause ?? MISSING_AMBIGUITY_ATTESTATION_CAUSE,
+        }, optionsWithScope, plan);
+    }
     const reused = tryReuseVerifyAc(plan, acceptance, optionsWithScope, projectRoot);
     if (reused !== null) {
         return applyOracle(reused, optionsWithScope, plan);
@@ -186,9 +205,10 @@ export function evaluateVerifyAcFromPlan(plan, options = {}) {
     // the #3267 ledger is a parallel store and can be empty while stated commands exist.
     // Stated was previously excluded, so rung=stated + empty ledger printed "nothing to run".
     // Do not override a blocking rejected ledger or a config error.
-    if (shouldRunPlanAcceptanceDirectly(base, acceptance)) {
+    if (shouldRunPlanAcceptanceDirectly(base, acceptance, plan)) {
         const runner = optionsWithScope.runner;
-        const direct = runLiteralAcceptanceCommands(acceptance.commands.map((c) => ({
+        const directCommands = statedAcceptanceCommands(acceptance, plan);
+        const direct = runLiteralAcceptanceCommands(directCommands.map((c) => ({
             command: c.command,
             cwd: c.cwd ?? null,
             expectedStdout: c.expectedStdout ?? null,
@@ -252,8 +272,38 @@ export function evaluateVerifyAcFromPlan(plan, options = {}) {
     }
     return applyOracle(annotate(base, acceptance, optionsWithScope.quiet), optionsWithScope, plan);
 }
-function shouldRunPlanAcceptanceDirectly(base, acceptance) {
-    if (acceptance.commands.length === 0)
+function hasNonDefaultAcceptanceContext(command) {
+    const cwd = command.cwd !== undefined && command.cwd !== null && String(command.cwd).trim();
+    const stdout = command.expectedStdout !== undefined &&
+        command.expectedStdout !== null &&
+        String(command.expectedStdout).length > 0;
+    const exit = typeof command.expectedExitCode === "number" && command.expectedExitCode !== 0;
+    return Boolean(cwd) || stdout || exit;
+}
+function hasStructuredAcceptancePeer(plan, command) {
+    return readStoredLiteralAcceptanceCommands(plan).some((c) => c.command === command && isExecutableLiteralSource(c.source));
+}
+/**
+ * True when a plan.acceptance.commands row is only an ingest copy of an inline
+ * prose mention (or an operator not-command disposition) and has no structured
+ * peer. Independently authored rows — promoted verify_commands, or a command
+ * with its own cwd/expectedStdout/exit — still run (#3721 Greptile).
+ */
+function isInlineScrapedAcceptanceCommand(plan, command) {
+    if (hasNonDefaultAcceptanceContext(command))
+        return false;
+    if (hasStructuredAcceptancePeer(plan, command.command))
+        return false;
+    if (readNotAcceptanceCommands(plan).has(command.command))
+        return true;
+    return readStoredLiteralAcceptanceCommands(plan).some((c) => c.command === command.command && isInlineProseMention(c));
+}
+/** plan.acceptance.commands minus ingest-copied inline mentions (#3721). */
+function statedAcceptanceCommands(acceptance, plan) {
+    return acceptance.commands.filter((c) => !isInlineScrapedAcceptanceCommand(plan, c));
+}
+function shouldRunPlanAcceptanceDirectly(base, acceptance, plan) {
+    if (statedAcceptanceCommands(acceptance, plan).length === 0)
         return false;
     if (base.runs.length > 0)
         return false;
@@ -372,6 +422,8 @@ function emitAcceptanceOutcome(result, options, projectRoot) {
                 outcome: row.outcome,
             })),
             served_from: result.servedFrom ?? "executed",
+            ...(result.cause !== undefined ? { cause: result.cause } : {}),
+            miss_reason: (result.servedFrom ?? "executed") === "executed" ? result.missReason : undefined,
         });
     }
     catch {
@@ -524,10 +576,27 @@ function applyOracle(result, options, plan = {}) {
             next = { ...next, resolution: "fail" };
         }
     }
+    const servedFrom = next.servedFrom ?? "executed";
+    let missReason = next.missReason;
+    if (servedFrom === "executed" && (missReason === undefined || missReason.length === 0)) {
+        const reuse = resolveAcReuse({
+            projectRoot,
+            plan,
+            scopeId: options.bankScopeId,
+            sessionId: options.sessionId,
+            env: options.env,
+            productPaths: options.productPaths,
+            allowCache: (options.reuseMode ?? "auto") === "auto",
+            allowBank: true,
+        });
+        if (reuse.kind === "miss")
+            missReason = reuse.reason;
+    }
     const stamped = {
         ...next,
         message: options.quiet === true ? next.message : labelVerdict(next),
-        servedFrom: next.servedFrom ?? "executed",
+        servedFrom,
+        missReason: servedFrom === "executed" ? missReason : undefined,
     };
     persistVerifyAcSessionCache(stamped, options, projectRoot, plan);
     if (options.skipAcceptanceEmit !== true) {
@@ -634,14 +703,14 @@ export function resolveOracleScopeKey(plan, xbriefPath, projectRoot) {
     return rel;
 }
 /**
- * After executable AC pass, FINALIZE the banking checkpoint (#3285).
- * Soft/advisory passes with zero runs do not bank. Fail-open on ledger errors.
+ * After verified-pass, FINALIZE the banking checkpoint (#3285 / #3558).
+ * Soft/advisory empty-pass still skips. Ledger I/O failures fail closed.
  */
 function maybeAttachAcPassBank(result, plan, xbriefPath, options) {
     if (options.bankOnPass === false) {
         return result;
     }
-    if (!result.ok || result.runs.length === 0) {
+    if (!result.ok || result.resolution !== "verified-pass") {
         return result;
     }
     const projectRoot = resolve(options.projectRoot ?? process.cwd());
@@ -661,8 +730,11 @@ function maybeAttachAcPassBank(result, plan, xbriefPath, options) {
             projectRoot,
             scopeId,
             executableRuns: result.runs.length,
+            verifiedPass: true,
             quiet: options.quiet,
             productStateHash: hashed.complete ? hashed.digest : null,
+            environ: options.env,
+            headSha: gitHead(projectRoot).head,
         });
         if (options.quiet || banked.notes.length === 0) {
             return result;

package/dist/release/closed-verb-gate.d.ts

@@ -0,0 +1,12 @@
+import type { ClosedVerbDecision } from "../authz/types.js";
+import type { ReleaseConfig, ReleaseSeams } from "./types.js";
+export declare const TAG_PUSH_CLOSED_VERB: "release-publish";
+export declare function evaluateReleaseTagPushGate(version: string, projectRoot: string, seams: ReleaseSeams, repo: string): ClosedVerbDecision;
+/**
+ * Fail closed before git tag + atomic tag push when skipTag is false.
+ * Dry-run and `--skip-tag` do not require a grant (no npm distribution).
+ * Returns EXIT_OK to continue, EXIT_VIOLATION to halt. Never spends the grant
+ * — draft-flip `release:publish` still owns markGrantUsed (#1095).
+ */
+export declare function assertTagPushClosedVerb(config: ReleaseConfig, seams: ReleaseSeams): number;
+//# sourceMappingURL=closed-verb-gate.d.ts.map

package/dist/release/closed-verb-gate.js

@@ -0,0 +1,51 @@
+/**
+ * Closed-verb gate on the tag-push / npm-publish boundary (#3527).
+ *
+ * Reuses the draft-flip evaluator (`evaluateReleasePublishGate`) so the
+ * distributing step carries the same authz tier. Does not delete or weaken
+ * the later `release:publish` draft-flip check.
+ */
+import { closedVerbEnvBypassKey } from "../authz/closed-verb.js";
+import { evaluateReleasePublishGate } from "../release-publish/pipeline.js";
+import { EXIT_OK, EXIT_VIOLATION, TOTAL_STEPS } from "./constants.js";
+function emitGate(label, status) {
+    process.stderr.write(`[10/${TOTAL_STEPS}] ${label}... ${status}\n`);
+}
+export const TAG_PUSH_CLOSED_VERB = "release-publish";
+export function evaluateReleaseTagPushGate(version, projectRoot, seams, repo) {
+    return evaluateReleasePublishGate(version, projectRoot, {
+        grants: seams.closedVerbGrants,
+        env: seams.closedVerbEnv,
+        repo,
+    });
+}
+/**
+ * Fail closed before git tag + atomic tag push when skipTag is false.
+ * Dry-run and `--skip-tag` do not require a grant (no npm distribution).
+ * Returns EXIT_OK to continue, EXIT_VIOLATION to halt. Never spends the grant
+ * — draft-flip `release:publish` still owns markGrantUsed (#1095).
+ */
+export function assertTagPushClosedVerb(config, seams) {
+    if (config.skipTag) {
+        return EXIT_OK;
+    }
+    const tag = `v${config.version}`;
+    const label = `Closed-verb gate ${TAG_PUSH_CLOSED_VERB} ${tag} (tag-push / npm-publish)`;
+    if (config.dryRun) {
+        emitGate(label, "DRYRUN (would require human-origin grant or DEFT_ALLOW_RELEASE_PUBLISH=1 before tag push)");
+        return EXIT_OK;
+    }
+    const gate = evaluateReleaseTagPushGate(config.version, config.projectRoot, seams, config.repo);
+    if (!gate.allowed) {
+        const bypassKey = gate.envBypassKey ??
+            closedVerbEnvBypassKey(TAG_PUSH_CLOSED_VERB, config.projectRoot) ??
+            "DEFT_ALLOW_RELEASE_PUBLISH";
+        emitGate(label, `FAIL (${gate.code}: ${gate.reason})`);
+        process.stderr.write(`[release] denied code=${gate.code} — set ${bypassKey}=1 or ` +
+            `mint \`deft authz:grant -- --template ${TAG_PUSH_CLOSED_VERB} --target ${config.version}\`\n`);
+        return EXIT_VIOLATION;
+    }
+    emitGate(label, `OK (${gate.code}${gate.humanApprovalRef !== null ? ` grant=${gate.humanApprovalRef}` : ""})`);
+    return EXIT_OK;
+}
+//# sourceMappingURL=closed-verb-gate.js.map

package/dist/release/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./auto-hatch.js";
 export * from "./build-dist.js";
+export * from "./closed-verb-gate.js";
 export * from "./constants.js";
 export * from "./coverage-debt-ledger.js";
 export * from "./flags.js";

package/dist/release/index.js

@@ -1,6 +1,7 @@
 /* v8 ignore file -- re-export barrel; covered via main.ts */
 export * from "./auto-hatch.js";
 export * from "./build-dist.js";
+export * from "./closed-verb-gate.js";
 export * from "./constants.js";
 export * from "./coverage-debt-ledger.js";
 export * from "./flags.js";

package/dist/release/pipeline.js

@@ -4,6 +4,7 @@ import { assertProjectionContained } from "../fs/projection-containment.js";
 import { readCoverageTotalsFromReport } from "../vitest-runner/coverage-debt.js";
 import { buildCoverageDebtIssueDraft, classifyStep5FailureWithFreshness, evaluateAutoHatch, formatAutoHatchBanner, parseExitCodeFromReason, reasonLooksLikeTimeout, } from "./auto-hatch.js";
 import { prependUpgradeBanner, promoteChangelog, sectionForVersion } from "./changelog.js";
+import { assertTagPushClosedVerb } from "./closed-verb-gate.js";
 import { EXIT_CONFIG_ERROR, EXIT_OK, EXIT_VIOLATION, RELEASE_ARTIFACTS, RELEASE_CHECK_TIMEOUT_MINUTES, TOTAL_STEPS, VERIFY_DRAFT_INTERVAL_SECONDS, VERIFY_DRAFT_MAX_ATTEMPTS, } from "./constants.js";
 import { createCoverageDebtIssue, probeOpenCoverageDebtLedger } from "./coverage-debt-ledger.js";
 import { checkTagAvailable, createGithubRelease, readTextFile, verifyReleaseDraft } from "./gh.js";
@@ -373,6 +374,12 @@ export function runPipeline(config, seams = {}) {
             return EXIT_VIOLATION;
         }
     }
+    // Step 10–11 boundary: closed-verb gate before tag + atomic push (#3527).
+    // npm publish fires on tag push; draft-flip `release:publish` stays (#1095).
+    const tagPushGate = assertTagPushClosedVerb(config, seams);
+    if (tagPushGate !== EXIT_OK) {
+        return tagPushGate;
+    }
     // Step 10: git tag.
     label = `Tag v${version}`;
     if (config.skipTag) {

package/dist/release/types.d.ts

@@ -1,3 +1,5 @@
+import type { EnvMap } from "../authz/closed-verb.js";
+import type { HumanOriginGrant } from "../authz/types.js";
 export interface ReleaseConfig {
     readonly version: string;
     readonly repo: string;
@@ -77,5 +79,15 @@ export interface ReleaseSeams {
     readonly headSha?: (projectRoot: string) => string | null;
     /** #3187 — CI detector; when true suite stamp is never trusted. */
     readonly isCi?: () => boolean;
+    /**
+     * #3527 — closed-verb grants for the tag-push / npm-publish gate.
+     * When omitted, production loads active human-origin grants from disk.
+     */
+    readonly closedVerbGrants?: readonly HumanOriginGrant[];
+    /**
+     * #3527 — env map for DEFT_ALLOW_RELEASE_PUBLISH. When omitted, process.env.
+     * Tests inject `{}` so a host env bypass cannot leak into fail-closed cases.
+     */
+    readonly closedVerbEnv?: EnvMap;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/render/constants.d.ts

@@ -1,6 +1,7 @@
 /** Canonical v0.6 status enum (matches `scripts/spec_validate.py`). */
 export declare const VALID_STATUSES: Set<string>;
-export declare const VALID_VBRIEF_VERSIONS: Set<string>;
+export { VALID_VBRIEF_VERSIONS } from "../vbrief-validate/constants.js";
+export { resolveInfoBlock } from "../vbrief-validate/schema.js";
 export declare const SPECIFICATION_NARRATIVE_KEY_ORDER: readonly ["Overview", "ProblemStatement", "Goals", "UserStories", "Requirements", "SuccessMetrics", "EdgeCases", "Architecture", "TechDecisions", "ImplementationPhases", "PreImplementationGates"];
 /** Migration capture narrative; omitted from default compact SPECIFICATION.md (#1566). */
 export declare const LEGACY_ARTIFACTS_NARRATIVE_KEY = "LegacyArtifacts";

package/dist/render/constants.js

@@ -10,7 +10,8 @@ export const VALID_STATUSES = new Set([
     "failed",
     "cancelled",
 ]);
-export const VALID_VBRIEF_VERSIONS = new Set(["0.6"]);
+export { VALID_VBRIEF_VERSIONS } from "../vbrief-validate/constants.js";
+export { resolveInfoBlock } from "../vbrief-validate/schema.js";
 export const SPECIFICATION_NARRATIVE_KEY_ORDER = [
     "Overview",
     "ProblemStatement",

package/dist/render/framework-commands.js

@@ -85,6 +85,9 @@ export const COMMANDS = {
     "verify:orphan-active": spec("verify:orphan-active", "verify_orphan_active:main", {
         projectRootArg: "--project-root",
     }),
+    "verify:lifecycle-visible": spec("verify:lifecycle-visible", "verify_lifecycle_visible:main", {
+        projectRootArg: "--project-root",
+    }),
     "verify:completed-tracked": spec("verify:completed-tracked", "verify_completed_tracked:main", {
         projectRootArg: "--project-root",
     }),
@@ -302,6 +305,7 @@ const ENTRYPOINT_VERB = {
     "preflight_cache:main": "preflight-cache",
     "preflight_wip_cap:main": "verify-wip-cap",
     "verify_orphan_active:main": "verify-orphan-active",
+    "verify_lifecycle_visible:main": "verify-lifecycle-visible",
     "verify_completed_tracked:main": "verify-completed-tracked",
     "pack_render:main": "pack-render",
     "validate_strategy_output:main": "validate-strategy-output",

package/dist/render/spec-validate.js

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync } from "node:fs";
 import { basename } from "node:path";
-import { VALID_STATUSES, VALID_VBRIEF_VERSIONS } from "./constants.js";
+import { VALID_INFO_ROOT_KEYS, VALID_VBRIEF_VERSIONS } from "../vbrief-validate/constants.js";
+import { resolveInfoBlock } from "../vbrief-validate/schema.js";
+import { VALID_STATUSES } from "./constants.js";
 function validateNarratives(narratives, path, errors) {
     if (typeof narratives !== "object" || narratives === null || Array.isArray(narratives)) {
         errors.push(`${path} must be an object`);
@@ -46,19 +48,28 @@ function validatePlanItem(item, path, errors) {
 }
 function validateSchema(data) {
     const errors = [];
-    if (!("vBRIEFInfo" in data)) {
-        errors.push("missing required top-level key 'vBRIEFInfo'");
+    const resolved = resolveInfoBlock(data);
+    if (resolved === null) {
+        let infoShapeError = false;
+        for (const key of VALID_INFO_ROOT_KEYS) {
+            if (!(key in data))
+                continue;
+            const info = data[key];
+            if (info === null || Array.isArray(info) || typeof info !== "object") {
+                errors.push(`'${key}' must be an object`);
+                infoShapeError = true;
+                break;
+            }
+        }
+        if (!infoShapeError) {
+            errors.push("missing required top-level key 'vBRIEFInfo' or 'xBRIEFInfo'");
+        }
     }
     else {
-        const info = data.vBRIEFInfo;
-        if (typeof info !== "object" || info === null || Array.isArray(info)) {
-            errors.push("'vBRIEFInfo' must be an object");
-        }
-        else {
-            const version = info.version;
-            if (!VALID_VBRIEF_VERSIONS.has(String(version))) {
-                errors.push(`'vBRIEFInfo.version' must be '0.6' (canonical v0.6 schema, #533), got ${JSON.stringify(version)}. Run \`task migrate:vbrief\` to upgrade pre-existing v0.5 vBRIEFs in-place.`);
-            }
+        const version = resolved.info.version;
+        if (!VALID_VBRIEF_VERSIONS.has(String(version))) {
+            const allowed = [...VALID_VBRIEF_VERSIONS].map((v) => `'${v}'`).join(", ");
+            errors.push(`'${resolved.key}.version' must be one of ${allowed} (canonical v0.6/v0.8 schema, #2107), got ${JSON.stringify(version)}. Run \`task migrate:xbrief\` to upgrade pre-existing v0.5 vBRIEFs in-place.`);
         }
     }
     if (!("plan" in data)) {

package/dist/run-summary/types.d.ts

@@ -128,6 +128,10 @@ export interface AcceptanceRunSummaryPayload {
     readonly clause_outcomes?: readonly AcceptanceClauseOutcomeRow[];
     /** bank | cache | executed — how verify:ac obtained this result (#3387). */
     readonly served_from?: "bank" | "cache" | "executed";
+    /** Config-error cause when outcome is config-error (#3559). */
+    readonly cause?: string;
+    /** Reuse-gate miss cause when served_from is executed (#3558). */
+    readonly miss_reason?: string;
 }
 /** Intake-time stamp: which rung locked, whether commands were stated, counts (#3323). */
 export interface AcceptanceStampRunSummaryPayload {

package/dist/scm/design-critique-chip.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Chip-only remaining-set write for design-critique catalog labels (#3642).
+ *
+ * Parent attach of triage-ready / recut mechanism-shaped MUST use this verb,
+ * not `gh api POST .../labels` and not additive `scm:issue:edit --add-label`.
+ */
+import { type DesignCritiqueCatalogChip } from "../design-critique/exclusive-chip.js";
+import type { LabelClient } from "../vbrief-reconcile/types.js";
+export declare const DESIGN_CRITIQUE_CHIP_VERB: "design-critique-chip";
+export declare const DESIGN_CRITIQUE_CHIP_USAGE: string;
+export interface DesignCritiqueChipArgs {
+    readonly issue: number;
+    readonly chip: DesignCritiqueCatalogChip;
+    readonly repo: string | null;
+    readonly json: boolean;
+}
+export interface DesignCritiqueChipSeams {
+    readonly client?: LabelClient;
+    /** Default OWNER/NAME when --repo is omitted (git origin). */
+    readonly resolveDefaultRepo?: () => string | null;
+}
+export interface DesignCritiqueChipResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** Fail-closed chip name. Closed catalog only. */
+export declare function resolveDesignCritiqueChipArg(raw: string): DesignCritiqueCatalogChip;
+export declare function parseDesignCritiqueChipArgs(extra: readonly string[]): DesignCritiqueChipArgs;
+/** Resolve OWNER/NAME from `git remote get-url origin`. */
+export declare function resolveRepoFromGitOrigin(): string | null;
+/**
+ * GET current labels, remaining-set replace via applyDesignCritiqueCatalogChip.
+ * One LabelClient.apply write. Other facets stay.
+ */
+export declare function runDesignCritiqueChip(extra: readonly string[], seams?: DesignCritiqueChipSeams): DesignCritiqueChipResult;
+//# sourceMappingURL=design-critique-chip.d.ts.map

package/dist/scm/design-critique-chip.js

@@ -0,0 +1,171 @@
+/**
+ * Chip-only remaining-set write for design-critique catalog labels (#3642).
+ *
+ * Parent attach of triage-ready / recut mechanism-shaped MUST use this verb,
+ * not `gh api POST .../labels` and not additive `scm:issue:edit --add-label`.
+ */
+import { spawnSync } from "node:child_process";
+import { applyDesignCritiqueCatalogChip, } from "../design-critique/exclusive-chip.js";
+import { parseGithubOwnerRepo } from "../policy/sync-default.js";
+import { ScmLabelClient, ScmLabelError } from "../vbrief-reconcile/labels.js";
+import { extractFlag, extractValueFlag } from "./argv.js";
+import { InvalidRepoError, splitRepo } from "./gh-rest.js";
+import { pyRepr } from "./py-format.js";
+export const DESIGN_CRITIQUE_CHIP_VERB = "design-critique-chip";
+export const DESIGN_CRITIQUE_CHIP_USAGE = "usage: scm issue design-critique-chip --issue N --chip triage-ready|mechanism-shaped [--repo OWNER/NAME] [--json]\n" +
+    "       Parent attach of design-critique:triage-ready / recut mechanism-shaped.\n" +
+    "       Closed catalog remaining-set replace. One write. Other facets stay.\n";
+const CHIP_ALIASES = {
+    "triage-ready": "design-critique:triage-ready",
+    "mechanism-shaped": "design-critique:mechanism-shaped",
+    "design-critique:triage-ready": "design-critique:triage-ready",
+    "design-critique:mechanism-shaped": "design-critique:mechanism-shaped",
+};
+/** Fail-closed chip name. Closed catalog only. */
+export function resolveDesignCritiqueChipArg(raw) {
+    const chip = CHIP_ALIASES[raw];
+    if (chip === undefined) {
+        throw new Error(`unknown design-critique chip ${pyRepr(raw)}; expected triage-ready|mechanism-shaped ` +
+            "(or design-critique:triage-ready|design-critique:mechanism-shaped)");
+    }
+    return chip;
+}
+function parseIssueNumber(raw, source) {
+    const issueN = Number.parseInt(raw, 10);
+    if (Number.isNaN(issueN) || issueN <= 0 || String(issueN) !== raw) {
+        throw new Error(`${source} must be a positive integer; got ${pyRepr(raw)}`);
+    }
+    return issueN;
+}
+export function parseDesignCritiqueChipArgs(extra) {
+    let remainder = [...extra];
+    const [help] = extractFlag(remainder, "--help");
+    const [helpShort] = extractFlag(remainder, "-h");
+    if (help || helpShort) {
+        throw new ChipUsageError(DESIGN_CRITIQUE_CHIP_USAGE.trimEnd());
+    }
+    const [json, afterJson] = extractFlag(remainder, "--json");
+    remainder = afterJson;
+    const [repoRaw, afterRepo] = extractValueFlag(remainder, "--repo");
+    remainder = afterRepo;
+    const [chipRaw, afterChip] = extractValueFlag(remainder, "--chip");
+    remainder = afterChip;
+    const [issueFlag, afterIssue] = extractValueFlag(remainder, "--issue");
+    remainder = afterIssue;
+    const leftoverFlags = remainder.filter((t) => t.startsWith("-"));
+    if (leftoverFlags.length > 0) {
+        throw new Error(`unrecognized flags: ${pyRepr(leftoverFlags)}. Supported: --issue, --chip, --repo, --json.`);
+    }
+    const positionals = remainder.filter((t) => !t.startsWith("-"));
+    if (chipRaw === null || chipRaw.length === 0) {
+        throw new Error("missing --chip triage-ready|mechanism-shaped");
+    }
+    const chip = resolveDesignCritiqueChipArg(chipRaw);
+    let issueRaw = issueFlag;
+    if (positionals.length > 1) {
+        throw new Error(`expected at most one positional issue number; got ${pyRepr(positionals)}`);
+    }
+    if (positionals.length === 1) {
+        const positional = positionals[0] ?? "";
+        if (issueRaw !== null && issueRaw !== positional) {
+            throw new Error(`--issue ${pyRepr(issueRaw)} conflicts with positional ${pyRepr(positional)}`);
+        }
+        issueRaw = positional;
+    }
+    if (issueRaw === null || issueRaw.length === 0) {
+        throw new Error("missing --issue N");
+    }
+    const issue = parseIssueNumber(issueRaw, "--issue");
+    if (repoRaw !== null && repoRaw.length > 0) {
+        splitRepo(repoRaw);
+    }
+    return { issue, chip, repo: repoRaw !== null && repoRaw.length > 0 ? repoRaw : null, json };
+}
+/** Resolve OWNER/NAME from `git remote get-url origin`. */
+export function resolveRepoFromGitOrigin() {
+    const result = spawnSync("git", ["remote", "get-url", "origin"], {
+        encoding: "utf8",
+        env: process.env,
+    });
+    if (result.status !== 0)
+        return null;
+    const stdout = typeof result.stdout === "string" ? result.stdout : "";
+    return parseGithubOwnerRepo(stdout);
+}
+class ChipUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ChipUsageError";
+    }
+}
+/**
+ * GET current labels, remaining-set replace via applyDesignCritiqueCatalogChip.
+ * One LabelClient.apply write. Other facets stay.
+ */
+export function runDesignCritiqueChip(extra, seams = {}) {
+    let args;
+    try {
+        args = parseDesignCritiqueChipArgs(extra);
+    }
+    catch (err) {
+        if (err instanceof ChipUsageError) {
+            return { exitCode: 0, stdout: `${err.message}\n`, stderr: "" };
+        }
+        if (err instanceof InvalidRepoError) {
+            return { exitCode: 2, stdout: "", stderr: `error: invalid --repo value: ${err.message}\n` };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return { exitCode: 2, stdout: "", stderr: `error: ${message}\n` };
+    }
+    const repo = args.repo ?? (seams.resolveDefaultRepo ?? resolveRepoFromGitOrigin)();
+    if (repo === null || repo.length === 0) {
+        return {
+            exitCode: 2,
+            stdout: "",
+            stderr: "error: missing --repo OWNER/NAME (could not resolve from git origin)\n",
+        };
+    }
+    try {
+        splitRepo(repo);
+    }
+    catch (err) {
+        if (err instanceof InvalidRepoError) {
+            return { exitCode: 2, stdout: "", stderr: `error: invalid --repo value: ${err.message}\n` };
+        }
+        throw err;
+    }
+    const client = seams.client ?? new ScmLabelClient();
+    try {
+        const applied = applyDesignCritiqueCatalogChip(client, repo, args.issue, args.chip);
+        const payload = {
+            repo,
+            issue: args.issue,
+            chip: args.chip,
+            add: [...applied.add],
+            remove: [...applied.remove],
+            remaining: [...applied.remaining],
+        };
+        if (args.json) {
+            return { exitCode: 0, stdout: `${JSON.stringify(payload)}\n`, stderr: "" };
+        }
+        const wrote = applied.add.length > 0 || applied.remove.length > 0;
+        const detail = applied.remove.length > 0
+            ? `removed ${applied.remove.join(", ")}`
+            : wrote
+                ? "added"
+                : "already exclusive";
+        return {
+            exitCode: 0,
+            stdout: `${wrote ? "applied" : "unchanged"} ${args.chip} on ${repo}#${args.issue} (${detail})\n`,
+            stderr: "",
+        };
+    }
+    catch (err) {
+        if (err instanceof ScmLabelError) {
+            return { exitCode: 1, stdout: "", stderr: `error: ${err.message}\n` };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return { exitCode: 1, stdout: "", stderr: `error: ${message}\n` };
+    }
+}
+//# sourceMappingURL=design-critique-chip.js.map

package/dist/scm/index.d.ts

@@ -3,6 +3,7 @@ export * from "./binary.js";
 export * from "./build-command.js";
 export * from "./call.js";
 export * from "./constants.js";
+export * from "./design-critique-chip.js";
 export * from "./errors.js";
 export * from "./gh-rest.js";
 export * from "./main.js";

package/dist/scm/index.js

@@ -3,6 +3,7 @@ export * from "./binary.js";
 export * from "./build-command.js";
 export * from "./call.js";
 export * from "./constants.js";
+export * from "./design-critique-chip.js";
 export * from "./errors.js";
 export * from "./gh-rest.js";
 export * from "./main.js";

package/dist/scm/main.d.ts

@@ -1,3 +1,4 @@
+import type { LabelClient } from "../vbrief-reconcile/types.js";
 import type { GhRestSeams } from "./gh-rest.js";
 export interface MainOptions {
     readonly whichFn?: Parameters<typeof import("./binary.js").resolveBinary>[0];
@@ -8,6 +9,8 @@ export interface MainOptions {
      * Production CLI always probes.
      */
     readonly skipReadiness?: boolean;
+    /** LabelClient seam for `issue design-critique-chip` (#3642). */
+    readonly labelClient?: LabelClient;
 }
 /**
  * CLI entry point. Returns the underlying binary's exit code (or 2 on arg error).