@deftai/directive-core 0.106.0 → 0.107.0

package/dist/literal-acceptance/run.js

@@ -7,6 +7,7 @@
  */
 import { spawnSync } from "node:child_process";
 import { isAbsolute, resolve } from "node:path";
+import { isInlineProseMention } from "./capture.js";
 import { evaluateCommandSafety, isExecutableLiteralSource } from "./safety.js";
 /** Default shell runner: exact command string via platform shell. */
 export function defaultLiteralAcceptanceRunner(input) {
@@ -95,7 +96,9 @@ export function runLiteralAcceptanceCommands(commands, options) {
             runs: [],
         };
     }
-    const untrusted = commands.filter((c) => c.source === "task_statement" && options.allowTaskStatement !== true);
+    const untrusted = commands.filter((c) => c.source === "task_statement" &&
+        options.allowTaskStatement !== true &&
+        !isInlineProseMention(c));
     const executable = commands.filter((c) => isExecutableLiteralSource(c.source) ||
         (c.source === "task_statement" && options.allowTaskStatement === true));
     // Fail closed: every capture-only stated command must have a matching agent-promoted
@@ -149,8 +152,11 @@ export function runLiteralAcceptanceCommands(commands, options) {
             code: 1,
             message: `Literal acceptance-command gate FAILED (#3267): ${unpromoted.length} stated command(s) ` +
                 `are capture-only (source=task_statement) and have no matching agent-promoted peer.\n` +
-                `Promote the exact command strings (and cwd/expectedStdout/expectedExitCode when stated) ` +
-                `into plan.metadata.swarm.verify_commands (or plan item / explicit metadata), then re-run.\n` +
+                `If the command is this story's acceptance, promote the exact strings ` +
+                `(and cwd/expectedStdout/expectedExitCode when stated) into ` +
+                `plan.metadata.swarm.verify_commands (or plan item / explicit metadata), then re-run.\n` +
+                `If the capture is not an acceptance command, record the exact string in ` +
+                `plan.metadata.literal_acceptance_not_commands without promoting it (#3721).\n` +
                 `Note: an unrelated executable peer or a same-text peer with different context does not waive.\n` +
                 listed,
             commands,

package/dist/literal-acceptance/types.d.ts

@@ -74,6 +74,12 @@ export interface LiteralAcceptanceGateResult {
 }
 /** Metadata key for operator-visible rejected command ledger (#3267). */
 export declare const LITERAL_ACCEPTANCE_REJECTED_METADATA_KEY: "literal_acceptance_rejected";
+/**
+ * Metadata key: command strings the operator recorded as *not* acceptance
+ * commands (#3721). Disposition without promotion — listing a string here does
+ * not assert it is the story's verification.
+ */
+export declare const LITERAL_ACCEPTANCE_NOT_COMMANDS_METADATA_KEY: "literal_acceptance_not_commands";
 /** Injectable shell runner for tests (default: spawnSync shell). */
 export type LiteralAcceptanceRunner = (input: {
     readonly command: string;

package/dist/literal-acceptance/types.js

@@ -19,6 +19,12 @@ export const EXECUTABLE_LITERAL_SOURCES = [
 ];
 /** Metadata key for operator-visible rejected command ledger (#3267). */
 export const LITERAL_ACCEPTANCE_REJECTED_METADATA_KEY = "literal_acceptance_rejected";
+/**
+ * Metadata key: command strings the operator recorded as *not* acceptance
+ * commands (#3721). Disposition without promotion — listing a string here does
+ * not assert it is the story's verification.
+ */
+export const LITERAL_ACCEPTANCE_NOT_COMMANDS_METADATA_KEY = "literal_acceptance_not_commands";
 /** Metadata key on plan.metadata for captured literal commands (#3267). */
 export const LITERAL_ACCEPTANCE_METADATA_KEY = "literal_acceptance_commands";
 /** Alternate camelCase key accepted on read. */

package/dist/policy/runtime-authority.d.ts

@@ -11,6 +11,22 @@ export interface RuntimeAuthorityScopes {
 }
 /** Layers that contribute to a resolved write fence (#516 / #2443 / #2948 Wave 3). */
 export type WriteFenceSource = "project" | "story";
+/**
+ * Whether recognized Shell dest-forms are enforced (#3438 / #3594).
+ *
+ * `off` (default) leaves Shell mutations exactly as they were before #3438:
+ * unrecognized and fail-open. `enforce` routes recognized dest-forms through
+ * `inspectMutationGates` and fail-closes targets it cannot prove.
+ *
+ * ! Default is `off` on purpose. Before #3438 Bash mutations were not gated at
+ * all, so defaulting to `enforce` would land new denials on every consumer with
+ * no opt-out. Opting IN via tracked project policy is a narrowing, which this
+ * fence model permits; a tracked switch that DISABLED enforcement would not be
+ * (see policy/deft-directive-disable.ts — repository-controlled content must
+ * not disable hooks for downstream clones).
+ */
+export type ShellDestFormsMode = "off" | "enforce";
+export declare const SHELL_DEST_FORMS_MODES: readonly ShellDestFormsMode[];
 export interface RuntimeAuthorityPolicy {
     readonly enabled: boolean;
     /** When non-empty, write targets must match at least one pattern. Empty = allow all paths. */
@@ -18,6 +34,8 @@ export interface RuntimeAuthorityPolicy {
     /** Deny wins over allow. */
     readonly denyPaths: readonly string[];
     readonly scopes: RuntimeAuthorityScopes;
+    /** Shell dest-form enforcement (#3438 / #3594). Default `off`. */
+    readonly shellDestForms: ShellDestFormsMode;
     /**
      * Optional story-layer allow globs from `plan.metadata.swarm.file_scope`
      * (populated by `resolveWriteFence` only). When non-empty, path must match

package/dist/policy/runtime-authority.js

@@ -3,6 +3,7 @@ import { readPlanPolicy } from "./plan-extensions.js";
 import { loadProjectDefinition } from "./resolve.js";
 export const FIELD_RUNTIME_AUTHORITY = "plan.policy.runtimeAuthority";
 export const FIELD_RUNTIME_AUTHORITY_CLI_ALIAS = "runtimeAuthority";
+export const SHELL_DEST_FORMS_MODES = ["off", "enforce"];
 export const DEFAULT_RUNTIME_AUTHORITY_SCOPES = {
     edits: true,
     push: false,
@@ -14,6 +15,7 @@ export const DEFAULT_RUNTIME_AUTHORITY_POLICY = {
     allowPaths: [],
     denyPaths: [],
     scopes: DEFAULT_RUNTIME_AUTHORITY_SCOPES,
+    shellDestForms: "off",
 };
 function readBoolean(rec, key, fallback) {
     if (key in rec && typeof rec[key] === "boolean") {
@@ -37,6 +39,11 @@ function readScopes(raw) {
         merge: readBoolean(rec, "merge", DEFAULT_RUNTIME_AUTHORITY_SCOPES.merge),
     };
 }
+function readShellDestForms(raw) {
+    // Unknown / malformed resolves to the safe default rather than throwing, but
+    // validateRuntimeAuthority reports it so a typo is not silent (#3594).
+    return raw === "enforce" ? "enforce" : DEFAULT_RUNTIME_AUTHORITY_POLICY.shellDestForms;
+}
 export function resolveRuntimeAuthorityPolicy(raw) {
     if (raw === null || raw === undefined) {
         return DEFAULT_RUNTIME_AUTHORITY_POLICY;
@@ -50,6 +57,7 @@ export function resolveRuntimeAuthorityPolicy(raw) {
         allowPaths: readStringArray(rec.allowPaths),
         denyPaths: readStringArray(rec.denyPaths),
         scopes: readScopes(rec.scopes),
+        shellDestForms: readShellDestForms(rec.shellDestForms),
     };
 }
 export function validateRuntimeAuthority(value) {
@@ -69,6 +77,9 @@ export function validateRuntimeAuthority(value) {
             errors.push(`${FIELD_RUNTIME_AUTHORITY}.${key} must be an array of path globs`);
         }
     }
+    if ("shellDestForms" in rec && !SHELL_DEST_FORMS_MODES.includes(rec.shellDestForms)) {
+        errors.push(`${FIELD_RUNTIME_AUTHORITY}.shellDestForms must be one of ${SHELL_DEST_FORMS_MODES.join(" | ")}`);
+    }
     if ("scopes" in rec) {
         const scopes = rec.scopes;
         if (typeof scopes !== "object" || scopes === null || Array.isArray(scopes)) {

package/dist/policy/write-fence.js

@@ -140,6 +140,9 @@ export function resolveWriteFence(projectPolicy, storyFileScope, options) {
         allowPaths,
         denyPaths,
         scopes,
+        // Carry the project setting through: resolving a write fence must not
+        // silently enable Shell dest-form enforcement for a story (#3438 / #3594).
+        shellDestForms: projectPolicy.shellDestForms,
         storyAllowPaths: storyAllow,
         fenceSources: sources,
     };

package/dist/preflight-cache/evaluate.js

@@ -300,13 +300,19 @@ function formatDriftFailure(repo, drift) {
     };
 }
 function runDriftProbe(resolvedRepo, cacheRoot, source, options) {
-    if (options.probeDriftFn) {
-        return options.probeDriftFn(resolvedRepo, cacheRoot, source);
-    }
     try {
+        if (options.probeDriftFn) {
+            return options.probeDriftFn(resolvedRepo, cacheRoot, source);
+        }
         return probeCacheDrift({ repo: resolvedRepo, source, cacheRoot });
     }
     catch {
+        // Deliberate fail-open (#3738 / #3422): a thrown probe (429 after retry,
+        // 502/503, DNS, auth) returns null; evaluate treats null as pass.
+        // Work-selection / session:start still inherit this. The write path no
+        // longer executes cache_fresh, so this is not a write-authorization bypass.
+        // Do not silently convert to fail-closed without revisiting #3422 (local
+        // work MAY continue when it does not need the forge).
         return null;
     }
 }

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

@@ -10,7 +10,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { basename, isAbsolute, relative, resolve } from "node:path";
 import { emitAcceptanceStampFromPlan, MISSING_AMBIGUITY_ATTESTATION_CAUSE, stampedAmbiguityAttestationError, } from "../intake/clause-derivation.js";
-import { appendLiteralAcceptanceAdvisory, evaluateLiteralAcceptanceFromPlan, isNoopRefusalReason, runLiteralAcceptanceCommands, stripLiteralAcceptanceAdvisory, } from "../literal-acceptance/index.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";
@@ -205,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,
@@ -271,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;

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).

package/dist/scm/main.js

@@ -2,6 +2,7 @@ import { spawnSync } from "node:child_process";
 import { extractFlag } from "./argv.js";
 import { buildCommand } from "./build-command.js";
 import { REST_OPT_IN_VERBS } from "./constants.js";
+import { DESIGN_CRITIQUE_CHIP_VERB, runDesignCritiqueChip } from "./design-critique-chip.js";
 import { ScmStubError } from "./errors.js";
 import { requireScmReady } from "./readiness.js";
 import { runRestList, runRestView } from "./rest-dispatch.js";
@@ -30,13 +31,26 @@ function guardScmReady(options) {
 export function main(argv, options = {}) {
     if (argv.length < 2) {
         process.stderr.write("usage: scm.py <namespace> <verb> [pass-through args...]\n" +
-            "       (v1 stub: namespace=issue, verb=list|view|close|edit)\n" +
+            "       (v1 stub: namespace=issue, verb=list|view|close|edit|design-critique-chip)\n" +
             "       --rest opt-in is supported on issue view/list (#976)\n");
         return 2;
     }
     const namespace = argv[0] ?? "";
     const verb = argv[1] ?? "";
     let extra = argv.slice(2);
+    if (namespace === "issue" && verb === DESIGN_CRITIQUE_CHIP_VERB) {
+        const blocked = guardScmReady(options);
+        if (blocked !== null)
+            return blocked;
+        const result = runDesignCritiqueChip(extra, { client: options.labelClient });
+        if (result.stdout.length > 0) {
+            process.stdout.write(result.stdout);
+        }
+        if (result.stderr.length > 0) {
+            process.stderr.write(result.stderr);
+        }
+        return result.exitCode;
+    }
     const [restMode, afterRest] = extractFlag(extra, "--rest");
     extra = afterRest;
     if (restMode) {

package/dist/scm/readiness-cli.d.ts

@@ -10,6 +10,8 @@ export interface ScmReadinessCliArgs {
     readonly deep?: boolean;
     readonly depth?: ScmProbeDepth;
     readonly help?: boolean;
+    readonly repo?: string;
+    readonly expectedLogin?: string;
 }
 export declare function parseScmReadinessArgs(argv: readonly string[]): {
     args: ScmReadinessCliArgs;

package/dist/scm/readiness-cli.js

@@ -5,6 +5,7 @@
  * Exit 0 when ready; exit 1 when not ready (loud diagnostic); exit 2 on bad flags.
  */
 import { fileURLToPath } from "node:url";
+import { INSTALLATION_IDENTITY_ISSUE_URL, PRINCIPAL_KIND_USER, } from "../intake/github-auth-modes.js";
 import { clearScmReadyCache, formatScmReadinessLines, probeScmReadiness, scmReadinessToDict, } from "./readiness.js";
 export function parseScmReadinessArgs(argv) {
     const out = {};
@@ -30,6 +31,26 @@ export function parseScmReadinessArgs(argv) {
             }
             out.depth = value;
         }
+        else if (arg === "--repo") {
+            const value = argv[++i];
+            if (value === undefined || value.startsWith("-")) {
+                return { args: out, error: "--repo expects owner/repo" };
+            }
+            out.repo = value;
+        }
+        else if (arg === "--expected-login") {
+            const value = argv[++i];
+            if (value === undefined || value.startsWith("-")) {
+                return { args: out, error: "--expected-login expects a GitHub login" };
+            }
+            out.expectedLogin = value;
+        }
+        else if (arg === "--expected-app-slug" || arg === "--expected-installation-id") {
+            return {
+                args: out,
+                error: `${arg} is not accepted; GitHub App installation identity is deferred to ${INSTALLATION_IDENTITY_ISSUE_URL}`,
+            };
+        }
         else if (arg === "--help" || arg === "-h") {
             out.help = true;
         }
@@ -43,8 +64,19 @@ export function parseScmReadinessArgs(argv) {
     return { args: out, error: null };
 }
 const USAGE = "usage: deft scm:status [--json] [--deep|--shallow|--depth shallow|deep]\n" +
+    "                       [--repo OWNER/REPO] [--expected-login LOGIN]\n" +
     "  Report SCM (gh/ghx) availability + auth state in this execution env (#2275).\n" +
+    "  Deep probes derive the target repo (flag / GH_REPO / GITHUB_REPOSITORY / origin)\n" +
+    "  and compare an expected user login when one is supplied (#3665).\n" +
+    "  GitHub App installation identity is deferred to #3693.\n" +
     "  Exit 0 ready / 1 not ready / 2 config error.\n";
+function expectedPrincipalFromArgs(args) {
+    const login = args.expectedLogin?.trim() ?? "";
+    if (login.length > 0) {
+        return { kind: PRINCIPAL_KIND_USER, login };
+    }
+    return undefined;
+}
 export function scmReadinessMain(args, options = {}) {
     const writeOut = options.writeOut ?? ((s) => process.stdout.write(s));
     const writeErr = options.writeErr ?? ((s) => process.stderr.write(s));
@@ -52,12 +84,21 @@ export function scmReadinessMain(args, options = {}) {
         writeOut(USAGE);
         return 0;
     }
+    const expectedPrincipal = expectedPrincipalFromArgs(args);
+    if (expectedPrincipal !== undefined && "error" in expectedPrincipal) {
+        writeErr(`error: ${expectedPrincipal.error}\n${USAGE}`);
+        return 2;
+    }
     const depth = args.depth ?? (args.deep ? "deep" : "shallow");
     // Explicit probe always re-evaluates (credentials may have changed since
     // session:start). Clears the process-scoped requireScmReady cache too.
     clearScmReadyCache();
     const probe = options.probe ?? probeScmReadiness;
-    const report = probe({ depth });
+    const report = probe({
+        depth,
+        repo: args.repo,
+        expectedPrincipal,
+    });
     if (args.json) {
         writeOut(`${JSON.stringify(scmReadinessToDict(report), null, 2)}\n`);
     }

package/dist/scm/readiness.d.ts

@@ -18,7 +18,7 @@
  * env token presence + optional short `gh auth status`). Deep API validation
  * is opt-in via `deep: true` (session:start --with-network).
  */
-import { findInjectedToken, type GhRunner, GITHUB_AUTH_MODE_HOST_GH, GITHUB_AUTH_MODE_INJECTED_TOKEN } from "../intake/github-auth-modes.js";
+import { type ExpectedGithubWorkerPrincipal, findInjectedToken, type GhRunner, GITHUB_AUTH_MODE_HOST_GH, GITHUB_AUTH_MODE_INJECTED_TOKEN } from "../intake/github-auth-modes.js";
 import { type RuntimeCapabilityReport } from "../intake/platform-capabilities.js";
 import { type WhichFn } from "./binary.js";
 import { BINARY_PREFERENCE } from "./constants.js";
@@ -64,6 +64,7 @@ export interface ProbeScmReadinessOptions {
     readonly runtimeReport?: RuntimeCapabilityReport;
     readonly githubAuthMode?: string | null;
     readonly repo?: string;
+    readonly expectedPrincipal?: ExpectedGithubWorkerPrincipal | null;
     readonly runGh?: GhRunner;
     /** When false, skip even `gh auth status` on the shallow path (tests / pure PATH). */
     readonly checkAuthStatus?: boolean;

package/dist/scm/readiness.js

@@ -105,7 +105,12 @@ function mapDeepFailureToAuthState(result) {
         return "missing-token";
     if (result.failureKind === "gh_auth_failed")
         return "unauthenticated";
-    if (result.failureKind === "api_unreachable" || result.failureKind === "repo_access_denied") {
+    if (result.failureKind === "api_unreachable" ||
+        result.failureKind === "repo_access_denied" ||
+        result.failureKind === "missing_expected_principal" ||
+        result.failureKind === "principal_mismatch" ||
+        result.failureKind === "missing_target_repo" ||
+        result.failureKind === "installation_identity_unverifiable") {
         return "unauthenticated";
     }
     return "unknown";
@@ -192,6 +197,7 @@ export function probeScmReadiness(options = {}) {
             environ: env,
             runtimeReport,
             repo: options.repo,
+            expectedPrincipal: options.expectedPrincipal,
             runGh: deepRunner,
         });
         if (deep.ok) {