@zivis/cli 0.1.0-alpha.46 → 0.1.0-alpha.52

package/dist/commands/assurance/index.d.ts

@@ -29,5 +29,7 @@ export interface AssuranceStatusResponse {
         openCritical: number;
         openHigh: number;
     };
+    trustRoomUrl?: string | null;
+    trustRoomSource?: string | null;
 }
 export declare function registerAssuranceCommands(program: Command): void;

package/dist/commands/assurance/index.js

@@ -2,6 +2,7 @@ import { ApiClient, ApiError } from "@zivis/mcp/api-client";
 import { resolveConfigFromBinding } from "@zivis/mcp/project-binding";
 import { requireApplicationId } from "@zivis/mcp/resolve-application-id";
 import { jsonEnvelope, printJson, failCommand, EXIT } from "../../internal/cli-output.js";
+import { trustRoomJsonFields, trustRoomHumanLines } from "../../internal/trust-room-link.js";
 function buildClient(opts) {
     const config = opts.session
         ? { ...resolveConfigFromBinding(process.cwd()), session: opts.session }
@@ -50,12 +51,14 @@ export function registerAssuranceCommands(program) {
                 query.set("category", opts.category);
             const status = await client.get(`/api/assurance/status?${query.toString()}`);
             if (json) {
-                printJson(jsonEnvelope("assurance status", { result: "ok", ...status }));
+                printJson(jsonEnvelope("assurance status", { result: "ok", ...status, ...trustRoomJsonFields(status) }));
                 return;
             }
             console.log(`Model: ${status.model.displayName} (${status.model.key})${status.model.version ? ` v${status.model.version}` : ""}`);
             if (!status.evaluatedAt) {
                 console.log("No completed evaluation for this Application/model yet.");
+                for (const line of trustRoomHumanLines(status))
+                    console.log(line);
                 return;
             }
             console.log(`Overall: score_raw=${fmtScore(status.overall.scoreRaw)} coverage=${fmtPct(status.overall.coverage)} (${status.overall.determinedCount}/${status.overall.totalCount} determined)`);
@@ -69,6 +72,8 @@ export function registerAssuranceCommands(program) {
                 console.log(`Last evaluated git SHA: ${status.lastEvaluatedGitSha ?? "unknown"}`);
                 console.log(`Framework id: ${status.model.frameworkId ?? "—"}`);
             }
+            for (const line of trustRoomHumanLines(status))
+                console.log(line);
         }
         catch (err) {
             if (isAmbiguousModelError(err)) {

package/dist/commands/run/index.js

@@ -1,9 +1,10 @@
 import * as fs from "node:fs/promises";
 import { ApiClient } from "@zivis/mcp/api-client";
 import { resolveConfigFromBinding } from "@zivis/mcp/project-binding";
-import { DEVX_RUN_CONTRACT_VERSION, completeDevXRunRemote, cancelDevXRunRemote, isRetryableDevXRunError, } from "../../internal/devx-run.js";
+import { DEVX_RUN_CONTRACT_VERSION, completeDevXRunRemote, cancelDevXRunRemote, reportDevXRunItems, isRetryableDevXRunError, } from "../../internal/devx-run.js";
 import { writeDevXRunCompleteOutboxEntry } from "../../internal/sync-outbox.js";
 import { jsonEnvelope, printJson, EXIT, errorMessage, failCommand } from "../../internal/cli-output.js";
+import { trustRoomJsonFields, trustRoomHumanLines } from "../../internal/trust-room-link.js";
 async function readInput(inputArg) {
     const raw = inputArg === "-" ? await readStdin() : await fs.readFile(inputArg, "utf-8");
     try {
@@ -59,6 +60,7 @@ export function registerRunCommands(program) {
                         coverage: reconciliation.coverage,
                     }
                     : {}),
+                ...trustRoomJsonFields(response),
             });
             if (json) {
                 printJson(output);
@@ -78,6 +80,12 @@ export function registerRunCommands(program) {
                     if (reconciliation.evidence.length)
                         console.log(`  ${reconciliation.evidence.length} artifact(s) persisted`);
                 }
+                const trustRoomLines = trustRoomHumanLines(response);
+                if (trustRoomLines.length) {
+                    console.log("");
+                    for (const line of trustRoomLines)
+                        console.log(line);
+                }
             }
             process.exit(EXIT.OK);
         }
@@ -101,6 +109,71 @@ export function registerRunCommands(program) {
             failCommand("run complete", err, json);
         }
     });
+    run
+        .command("report <runId>")
+        .description("post confirmed findings/evidence/observations against a pending run as you go, without completing it (ZIV-332)")
+        .requiredOption("--input <path>", "path to a JSON item-batch file ({ findings?, evidence?, observations? }), or '-' for stdin")
+        .option("--json", "emit JSON only on stdout")
+        .action(async (runId, opts) => {
+        const json = !!opts.json;
+        let items;
+        try {
+            items = await readInput(opts.input);
+        }
+        catch (err) {
+            failCommand("run report", err, json);
+        }
+        if (!items || typeof items !== "object" || Array.isArray(items)) {
+            failCommand("run report", new Error("--input must be a JSON object with findings[], evidence[], and/or observations[]"), json);
+        }
+        const config = resolveConfigFromBinding(process.cwd());
+        const client = new ApiClient(config);
+        try {
+            const response = await reportDevXRunItems(client, { runId, items: items });
+            const output = jsonEnvelope("run report", {
+                run_id: runId,
+                outcome: response.outcome,
+                findings: response.items.findings,
+                evidence: response.items.evidence,
+                observations: response.items.observations,
+                ...(response.rejectedObservations?.length ? { rejected_observations: response.rejectedObservations } : {}),
+                run_totals: response.runTotals,
+            });
+            if (json) {
+                printJson(output);
+            }
+            else {
+                const findings = response.items.findings;
+                const evidence = response.items.evidence;
+                const observations = response.items.observations;
+                const created = findings.filter((f) => f.action === "created").length;
+                const matched = findings.length - created;
+                const retest = findings.filter((f) => f.retestRecommendation !== null).length;
+                const withHistory = findings.filter((f) => f.dispositionHistory.length > 0).length;
+                const total = findings.length + evidence.length + observations.length;
+                console.log(`zivis run report: applied ${total} item${total === 1 ? "" : "s"} (run ${runId} stays pending)`);
+                if (created)
+                    console.log(`  + ${created} new finding${created === 1 ? "" : "s"}`);
+                if (matched)
+                    console.log(`  = ${matched} matched existing finding${matched === 1 ? "" : "s"}`);
+                if (retest)
+                    console.log(`  ↻ ${retest} retest recommendation${retest === 1 ? "" : "s"} — cite in retests[] on run complete`);
+                if (withHistory)
+                    console.log(`  ⚑ ${withHistory} finding${withHistory === 1 ? "" : "s"} with prior disposition history — surface to the human; never auto-apply`);
+                if (evidence.length)
+                    console.log(`  ${evidence.length} evidence item${evidence.length === 1 ? "" : "s"} persisted`);
+                if (observations.length)
+                    console.log(`  ${observations.length} observation${observations.length === 1 ? "" : "s"} recorded`);
+                if (response.rejectedObservations?.length)
+                    console.log(`  ! ${response.rejectedObservations.length} observation(s) rejected — see --json for reasons`);
+                console.log(`  run totals so far: ${response.runTotals.findings} findings / ${response.runTotals.evidence} evidence / ${response.runTotals.observations} observations`);
+            }
+            process.exit(EXIT.OK);
+        }
+        catch (err) {
+            failCommand("run report", err, json);
+        }
+    });
     run
         .command("cancel <runId>")
         .description("cancel a pending run")

package/dist/commands/share/index.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from "commander";
+export interface ShareResponse {
+    trustRoomId: string;
+    trustRoomName: string;
+    trustRoomUrl: string;
+    accessUrl: string;
+    email: string;
+    permission: string;
+    status: "shared" | "already_shared";
+    isNewUser: boolean;
+    emailSent: boolean;
+}
+export declare function registerShareCommands(program: Command): void;
+export default registerShareCommands;

package/dist/commands/share/index.js

@@ -0,0 +1,100 @@
+import readline from "node:readline/promises";
+import { ApiClient } from "@zivis/mcp/api-client";
+import { resolveConfigFromBinding } from "@zivis/mcp/project-binding";
+import { requireApplicationId } from "@zivis/mcp/resolve-application-id";
+import { jsonEnvelope, printJson, failCommand, EXIT } from "../../internal/cli-output.js";
+const COMMAND = "share";
+const PERMISSIONS = ["view", "comment", "edit", "admin"];
+async function prompt(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return (await rl.question(question)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+function isValidEmail(value) {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+}
+export function registerShareCommands(program) {
+    program
+        .command("share")
+        .description("share this Application's current Assurance Room with someone by email")
+        .argument("[email]", "who to share with (prompted for when omitted)")
+        .option("-s, --session <name>", "named session for multi-tenant")
+        .option("--app <id>", "Application id (defaults to the bound Application)")
+        .option("--permission <level>", `access level: ${PERMISSIONS.join(" | ")}`, "view")
+        .option("--json", "emit machine-readable JSON")
+        .action(async (emailArg, opts) => {
+        const json = Boolean(opts.json);
+        try {
+            const permission = (opts.permission ?? "view").toLowerCase();
+            if (!PERMISSIONS.includes(permission)) {
+                throw new Error(`--permission must be one of: ${PERMISSIONS.join(", ")}`);
+            }
+            const resolvedApp = requireApplicationId(opts.app, process.cwd());
+            if (!resolvedApp.ok) {
+                if (json) {
+                    printJson(jsonEnvelope(COMMAND, { result: "error", error: resolvedApp.message }));
+                }
+                else {
+                    console.error(`zivis ${COMMAND}: ${resolvedApp.message}`);
+                }
+                process.exit(EXIT.INVALID_OR_INDETERMINATE);
+            }
+            let email = (emailArg ?? "").trim();
+            if (!email) {
+                if (json) {
+                    throw new Error("An email argument is required with --json (no prompting).");
+                }
+                email = await prompt("Share this Assurance Room with (email): ");
+            }
+            if (!isValidEmail(email)) {
+                throw new Error(`'${email}' does not look like an email address.`);
+            }
+            const config = opts.session
+                ? { ...resolveConfigFromBinding(process.cwd()), session: opts.session }
+                : resolveConfigFromBinding(process.cwd());
+            const client = new ApiClient(config);
+            const res = await client.post("/api/assurance/share", {
+                applicationId: resolvedApp.id,
+                email,
+                permission,
+            });
+            if (json) {
+                printJson(jsonEnvelope(COMMAND, {
+                    result: "ok",
+                    status: res.status,
+                    email: res.email,
+                    permission: res.permission,
+                    is_new_user: res.isNewUser,
+                    email_sent: res.emailSent,
+                    trust_room_id: res.trustRoomId,
+                    trust_room_url: res.trustRoomUrl,
+                    access_url: res.accessUrl,
+                }));
+                return;
+            }
+            if (res.status === "already_shared") {
+                console.log(`${res.email} already has access to ${res.trustRoomName}.`);
+            }
+            else {
+                console.log(`Shared ${res.trustRoomName} with ${res.email} (${res.permission}).`);
+            }
+            if (res.isNewUser) {
+                console.log(`${res.email} has no ZIVIS account yet — they'll create one when they open the link.`);
+            }
+            if (!res.emailSent) {
+                console.log("Access was granted, but the invitation email could not be sent.");
+                console.log("Pass this link on directly:");
+            }
+            console.log("");
+            console.log(`Assurance Room: ${res.accessUrl}`);
+        }
+        catch (err) {
+            failCommand(COMMAND, err, json);
+        }
+    });
+}
+export default registerShareCommands;

package/dist/commands/sync/index.js

@@ -121,10 +121,14 @@ async function runFlush(opts) {
     const client = new ApiClient(config);
     let succeeded = 0;
     let failed = 0;
+    const trustRoomUrls = [];
     for (const { filePath, entry } of pending) {
         try {
             if (entry.kind === "devx-run-complete") {
-                await completeDevXRunRemote(client, { runId: entry.runId, contractVersion: entry.contractVersion, result: entry.result });
+                const completed = await completeDevXRunRemote(client, { runId: entry.runId, contractVersion: entry.contractVersion, result: entry.result });
+                if (completed.trustRoomUrl && !trustRoomUrls.includes(completed.trustRoomUrl)) {
+                    trustRoomUrls.push(completed.trustRoomUrl);
+                }
             }
             else {
                 await syncApplicationInventory({
@@ -143,10 +147,12 @@ async function runFlush(opts) {
         }
     }
     if (format === "json") {
-        process.stdout.write(JSON.stringify({ succeeded, failed, remaining: failed }, null, 2) + "\n");
+        process.stdout.write(JSON.stringify({ succeeded, failed, remaining: failed, ...(trustRoomUrls.length ? { trust_room_urls: trustRoomUrls } : {}) }, null, 2) + "\n");
     }
     else {
         process.stdout.write(`\nFlushed outbox: ${succeeded} succeeded, ${failed} still failing (left queued).\n`);
+        for (const url of trustRoomUrls)
+            process.stdout.write(`Trust Room: ${url}\n`);
     }
     return failed > 0 ? 1 : 0;
 }

package/dist/commands/test/index.js

@@ -5,7 +5,7 @@ import { ApiClient } from "@zivis/mcp/api-client";
 import { resolveConfigFromBinding } from "@zivis/mcp/project-binding";
 import { requireApplicationId } from "@zivis/mcp/resolve-application-id";
 import { renderSecurityContext } from "../../internal/security-context.js";
-import { startTestRun, listTestScopes } from "../../internal/test-scope.js";
+import { startTestRun, listTestScopes, tryBuildChangeRecommendation, } from "../../internal/test-scope.js";
 import { LocalPackRegistryClient, registryDirOverride } from "../../internal/packs/registry-client.js";
 import { NpmPackRegistryClient } from "../../internal/packs/npm-registry-client.js";
 import { PackUnavailableError, PackIntegrityError, UnknownScopeError } from "../../internal/packs/types.js";
@@ -38,9 +38,10 @@ function getCliVersion() {
 export function registerTestCommand(program) {
     program
         .command("test [scope]")
-        .description("run a Zivis-guided AppSec review — full/adaptive by default, or targeted at a stable scope")
+        .description("run a Zivis-guided AppSec review — change-aware by default once a prior run exists, full/adaptive on the first run or with --full, or targeted at a stable scope")
         .option("--list", "list available scopes from the verified AppSec methodology pack")
         .option("--app <id>", "Application id (defaults to the bound Application)")
+        .option("--full", "skip the change-aware recommendation and always run a full adaptive review")
         .option("--json", "emit JSON only on stdout")
         .action(async (scope, opts) => {
         const json = !!opts.json;
@@ -49,6 +50,7 @@ export function registerTestCommand(program) {
         const apiClient = new ApiClient(config);
         const registryClient = buildRegistryClient();
         const cliVersion = getCliVersion();
+        const deps = { apiClient, registryClient };
         if (opts.list) {
             try {
                 const listing = await listTestScopes(registryClient, cliVersion);
@@ -70,7 +72,30 @@ export function registerTestCommand(program) {
             if (!resolvedApp.ok) {
                 throw new UsageError(resolvedApp.message);
             }
-            const { envelope, resolvedScope, contextOutcome } = await startTestRun({ apiClient, registryClient }, { applicationId: resolvedApp.id, scopeId: scope, cwd, cliVersion });
+            let precomputedContext;
+            if (!scope && !opts.full) {
+                const changeOutcome = await tryBuildChangeRecommendation(deps, { applicationId: resolvedApp.id, cwd, cliVersion });
+                if (changeOutcome.kind === "recommendation" || changeOutcome.kind === "up-to-date" || changeOutcome.kind === "no-scope-match") {
+                    if (json) {
+                        printJson(jsonEnvelope("test", changeOutcomeToJson(changeOutcome)));
+                    }
+                    else {
+                        printChangeOutcomeHuman(changeOutcome);
+                    }
+                    process.exit(EXIT.OK);
+                }
+                precomputedContext = changeOutcome.contextOutcome;
+                if (!json && changeOutcome.kind === "sha-not-found") {
+                    console.error(`[zivis] Last-tested commit ${shortSha(changeOutcome.sha)} not found locally (shallow clone, force-push, or unrelated history?) — running a full adaptive review.`);
+                }
+            }
+            const { envelope, resolvedScope, contextOutcome } = await startTestRun(deps, {
+                applicationId: resolvedApp.id,
+                scopeId: scope,
+                cwd,
+                cliVersion,
+                precomputedContext,
+            });
             const output = jsonEnvelope("test", { ...envelope });
             if (json) {
                 printJson(output);
@@ -114,3 +139,60 @@ function printRunHuman(envelope, resolvedScope, contextOutcome) {
     }
     console.log(`\nWhen finished: ${envelope.result_contract.complete_command}`);
 }
+function shortSha(sha) {
+    return sha.slice(0, 8);
+}
+function joinWithAnd(items) {
+    if (items.length <= 1)
+        return items[0] ?? "";
+    if (items.length === 2)
+        return `${items[0]} and ${items[1]}`;
+    return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+function filesLabel(count) {
+    return `${count} file${count === 1 ? "" : "s"}`;
+}
+function printChangeOutcomeHuman(outcome) {
+    switch (outcome.kind) {
+        case "up-to-date":
+            console.log(`zivis test: no files changed since last-tested commit ${shortSha(outcome.sha)}. Nothing to recommend.`);
+            console.log(`Run \`zivis test --full\` for a full adaptive review anyway, or \`zivis test <scope>\` for a specific one.`);
+            return;
+        case "no-scope-match":
+            console.log(`${filesLabel(outcome.changedFileCount)} changed since ${shortSha(outcome.sha)}, but none map to a known methodology scope.`);
+            console.log(`Run \`zivis test --full\` for a full adaptive review, \`zivis test <scope>\` for a specific one, or \`zivis test --list\` to see all scopes.`);
+            return;
+        case "recommendation": {
+            const { sha, changedFileCount, scopes, testIds } = outcome;
+            console.log(`${filesLabel(changedFileCount)} changed since ${shortSha(sha)}.`);
+            console.log(`Changes touch ${joinWithAnd(scopes.map((s) => s.label))}.`);
+            console.log("");
+            console.log("Recommended:");
+            for (const s of scopes)
+                console.log(`  zivis test ${s.id}`);
+            if (testIds.length > 0) {
+                console.log("");
+                console.log(`${testIds.join(", ")} ${testIds.length === 1 ? "is" : "are"} especially relevant.`);
+            }
+            console.log("");
+            console.log(`Run \`zivis test --full\` for a full adaptive review instead.`);
+            return;
+        }
+    }
+}
+function changeOutcomeToJson(outcome) {
+    switch (outcome.kind) {
+        case "up-to-date":
+            return { result: "up_to_date", since: outcome.sha };
+        case "no-scope-match":
+            return { result: "no_scope_match", since: outcome.sha, changed_file_count: outcome.changedFileCount };
+        case "recommendation":
+            return {
+                result: "recommendation",
+                since: outcome.sha,
+                changed_file_count: outcome.changedFileCount,
+                scopes: outcome.scopes,
+                test_ids: outcome.testIds,
+            };
+    }
+}

package/dist/index.js

@@ -15,6 +15,7 @@ import { registerCreditsCommands } from "./commands/credits/index.js";
 import { registerOpenCommands } from "./commands/open/index.js";
 import { registerSyncCommands } from "./commands/sync/index.js";
 import { registerAssuranceCommands } from "./commands/assurance/index.js";
+import { registerShareCommands } from "./commands/share/index.js";
 import { registerGateCommand } from "./commands/gate/index.js";
 import { registerRunCommands } from "./commands/run/index.js";
 import { registerTestCommand } from "./commands/test/index.js";
@@ -54,6 +55,7 @@ registerCreditsCommands(program);
 registerOpenCommands(program);
 registerSyncCommands(program);
 registerAssuranceCommands(program);
+registerShareCommands(program);
 registerGateCommand(program);
 registerRunCommands(program);
 registerTestCommand(program);

package/dist/internal/change-recommendation.d.ts

@@ -0,0 +1,6 @@
+import type { PackScopeEntry } from "./packs/types.js";
+export interface ChangeRecommendation {
+    scopeIds: string[];
+    testIds: string[];
+}
+export declare function buildChangeRecommendation(changedFiles: string[], resolvedScopes: Pick<PackScopeEntry, "id" | "label" | "tests">[]): ChangeRecommendation | null;

package/dist/internal/change-recommendation.js

@@ -0,0 +1,113 @@
+function globToRegex(glob) {
+    const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    let pattern = escaped;
+    const leadingDoubleStarSlash = pattern.startsWith("**/");
+    if (leadingDoubleStarSlash)
+        pattern = pattern.slice(3);
+    const DOUBLE_STAR_TOKEN = "@@DOUBLESTAR@@";
+    pattern = pattern
+        .replace(/\*\*/g, DOUBLE_STAR_TOKEN)
+        .replace(/\*/g, "[^/]*")
+        .replace(new RegExp(DOUBLE_STAR_TOKEN, "g"), ".*");
+    if (leadingDoubleStarSlash)
+        pattern = `(?:.*/)?${pattern}`;
+    return new RegExp(`^${pattern}$`, "i");
+}
+const REGEX_CACHE = new Map();
+function compiledGlob(glob) {
+    let rx = REGEX_CACHE.get(glob);
+    if (!rx) {
+        rx = globToRegex(glob);
+        REGEX_CACHE.set(glob, rx);
+    }
+    return rx;
+}
+function matchesAnyGlob(filePath, globs) {
+    const normalized = filePath.replace(/\\/g, "/");
+    return globs.some((glob) => compiledGlob(glob).test(normalized));
+}
+const CHANGE_SCOPE_HEURISTICS = [
+    { scopeId: "auth", globs: ["**/*password*", "**/*passwd*", "**/*bcrypt*", "**/*argon2*", "**/*scrypt*", "**/*hash*"], testIds: ["AUTH-001"] },
+    { scopeId: "auth", globs: ["**/*login*", "**/*signin*", "**/*sign-in*", "**/*credential*"], testIds: ["AUTH-003"] },
+    { scopeId: "auth", globs: ["**/*mfa*", "**/*otp*", "**/*two-factor*", "**/*2fa*", "**/*step-up*"], testIds: ["AUTH-004"] },
+    { scopeId: "auth", globs: ["**/*reset-password*", "**/*forgot-password*", "**/*password-reset*", "**/*account-recovery*"], testIds: ["AUTH-005"] },
+    { scopeId: "auth", globs: ["**/*rate-limit*", "**/*throttle*", "**/*lockout*"], testIds: ["AUTH-006"] },
+    { scopeId: "auth", globs: ["**/auth/**", "**/authentication/**", "**/*oauth*", "**/*sso*", "**/*saml*"] },
+    { scopeId: "authorization", globs: ["**/*rbac*", "**/*permission*", "**/*acl*"], testIds: ["AUTHZ-001", "AUTHZ-002"] },
+    { scopeId: "authorization", globs: ["**/*tenant*", "**/*multi-tenant*", "**/*org-scope*"], testIds: ["AUTHZ-003"] },
+    { scopeId: "authorization", globs: ["**/authz/**", "**/authorization/**", "**/*entitlement*", "**/*role*"] },
+    { scopeId: "session", globs: ["**/*jwt*"], testIds: ["SESSION-006"] },
+    { scopeId: "session", globs: ["**/*csrf*"], testIds: ["SESSION-005"] },
+    { scopeId: "session", globs: ["**/*cookie*"], testIds: ["SESSION-004"] },
+    { scopeId: "session", globs: ["**/session/**", "**/*sessions*", "**/*token*"] },
+    { scopeId: "api", globs: ["**/routes/**", "**/route/**", "**/controllers/**", "**/api/**", "**/*.graphql", "**/openapi*.*", "**/swagger*.*"] },
+    { scopeId: "input", globs: ["**/*sql*", "**/*query-builder*", "**/*raw-query*"], testIds: ["INPUT-001"] },
+    { scopeId: "input", globs: ["**/*template*"], testIds: ["INPUT-003"] },
+    { scopeId: "input", globs: ["**/*path-traversal*", "**/*path-join*"], testIds: ["INPUT-004"] },
+    { scopeId: "input", globs: ["**/*deserializ*", "**/*unmarshal*", "**/*pickle*"], testIds: ["INPUT-005"] },
+    { scopeId: "input", globs: ["**/*sanitiz*", "**/*validat*", "**/*escape*"] },
+    { scopeId: "data", globs: ["**/*encrypt*", "**/*crypto*", "**/*cipher*"], testIds: ["DATA-003", "DATA-005"] },
+    { scopeId: "data", globs: ["**/models/**", "**/entities/**", "**/schema.prisma", "**/*.sql"] },
+    { scopeId: "secrets", globs: ["**/*.env*", "**/*secret*", "**/*credentials*"], testIds: ["SECRETS-001"] },
+    { scopeId: "secrets", globs: ["**/.github/workflows/**"], testIds: ["SECRETS-006"] },
+    {
+        scopeId: "dependencies",
+        globs: [
+            "**/package.json",
+            "**/package-lock.json",
+            "**/pnpm-lock.yaml",
+            "**/yarn.lock",
+            "**/go.mod",
+            "**/go.sum",
+            "**/requirements*.txt",
+            "**/Pipfile*",
+            "**/Gemfile*",
+            "**/*.csproj",
+        ],
+    },
+    { scopeId: "ssrf", globs: ["**/*webhook*"], testIds: ["SSRF-001"] },
+    { scopeId: "ssrf", globs: ["**/*fetch*", "**/*http-client*", "**/*outbound*", "**/*proxy*"] },
+    { scopeId: "uploads", globs: ["**/*content-type*", "**/*mime-type*", "**/*filetype*"], testIds: ["UPLOAD-001"] },
+    { scopeId: "uploads", globs: ["**/*blob-storage*", "**/*s3*", "**/*azurite*", "**/*storage-service*"], testIds: ["UPLOAD-002"] },
+    { scopeId: "uploads", globs: ["**/*filename*"], testIds: ["UPLOAD-003"] },
+    { scopeId: "uploads", globs: ["**/*svg*"], testIds: ["UPLOAD-006"] },
+    { scopeId: "uploads", globs: ["**/*upload*", "**/*multipart*", "**/*attachment*"] },
+    { scopeId: "frontend", globs: ["**/*.tsx", "**/*.jsx", "**/components/**", "**/*.vue", "**/*.svelte"] },
+    { scopeId: "infra", globs: ["**/*.tf", "**/Dockerfile*", "**/docker-compose*.yml", "**/docker-compose*.yaml", "**/k8s/**", "**/helm/**", "**/.github/workflows/**"] },
+    { scopeId: "ai", globs: ["**/*llm*", "**/*prompt*", "**/*agent*", "**/*anthropic*", "**/*openai*", "**/*rag*", "**/*embedding*"] },
+];
+export function buildChangeRecommendation(changedFiles, resolvedScopes) {
+    const scopesById = new Map(resolvedScopes.map((s) => [s.id, s]));
+    const matchedScopeIds = new Set();
+    const matchedTestIdsByScope = new Map();
+    for (const rule of CHANGE_SCOPE_HEURISTICS) {
+        if (!scopesById.has(rule.scopeId))
+            continue;
+        if (!changedFiles.some((file) => matchesAnyGlob(file, rule.globs)))
+            continue;
+        matchedScopeIds.add(rule.scopeId);
+        if (rule.testIds?.length) {
+            const set = matchedTestIdsByScope.get(rule.scopeId) ?? new Set();
+            for (const id of rule.testIds)
+                set.add(id);
+            matchedTestIdsByScope.set(rule.scopeId, set);
+        }
+    }
+    if (matchedScopeIds.size === 0)
+        return null;
+    const scopeIds = resolvedScopes.filter((s) => matchedScopeIds.has(s.id)).map((s) => s.id);
+    const testIds = [];
+    for (const scopeId of scopeIds) {
+        const candidateIds = matchedTestIdsByScope.get(scopeId);
+        if (!candidateIds)
+            continue;
+        const tests = scopesById.get(scopeId)?.tests ?? [];
+        for (const test of tests) {
+            if (test.deprecated)
+                continue;
+            if (candidateIds.has(test.id))
+                testIds.push(test.id);
+        }
+    }
+    return { scopeIds, testIds };
+}

package/dist/internal/devx-run.d.ts

@@ -51,10 +51,13 @@ export interface DevXRunReconciliationSummary {
         applicability: string;
     }>;
 }
+export type TrustRoomLinkSource = string;
 export interface DevXRunOutcome {
     outcome: "completed" | "cancelled" | "idempotent-replay";
     run: DevXRunWire;
     reconciliation?: DevXRunReconciliationSummary;
+    trustRoomUrl?: string | null;
+    trustRoomSource?: TrustRoomLinkSource | null;
 }
 export declare function isRetryableDevXRunError(err: unknown): boolean;
 export declare function completeDevXRunRemote(client: DevXRunApi, params: {
@@ -66,3 +69,61 @@ export declare function cancelDevXRunRemote(client: DevXRunApi, params: {
     runId: string;
     reason?: string | null;
 }): Promise<DevXRunOutcome>;
+export interface DevXRunItemsPayload {
+    findings?: unknown[];
+    evidence?: unknown[];
+    observations?: unknown[];
+}
+export interface DevXRunItemFindingWire {
+    index: number;
+    action: "created" | "updated" | "matched_existing";
+    findingId: string;
+    match: {
+        basis: "fingerprint";
+        fingerprint: string;
+    };
+    retestRecommendation: {
+        recommended: true;
+        reason: string;
+        instruction: string;
+    } | null;
+    dispositionHistory: Array<Record<string, unknown>>;
+}
+export interface DevXRunItemEvidenceWire {
+    index: number;
+    action: "created" | "matched_existing";
+    evidenceId: string;
+    match: {
+        basis: "content_hash";
+        contentHash: string;
+    };
+}
+export interface DevXRunItemObservationWire {
+    testId: string;
+    action: "created" | "matched_existing";
+    observationId: string;
+    scopeId: string;
+    result: string;
+}
+export interface DevXRunItemsOutcome {
+    runId: string;
+    outcome: "applied";
+    items: {
+        findings: DevXRunItemFindingWire[];
+        evidence: DevXRunItemEvidenceWire[];
+        observations: DevXRunItemObservationWire[];
+    };
+    rejectedObservations?: Array<{
+        test_id: string;
+        reason: string;
+    }>;
+    runTotals: {
+        findings: number;
+        evidence: number;
+        observations: number;
+    };
+}
+export declare function reportDevXRunItems(client: DevXRunApi, params: {
+    runId: string;
+    items: DevXRunItemsPayload;
+}): Promise<DevXRunItemsOutcome>;

package/dist/internal/devx-run.js

@@ -34,3 +34,6 @@ export async function cancelDevXRunRemote(client, params) {
         reason: params.reason ?? null,
     });
 }
+export async function reportDevXRunItems(client, params) {
+    return client.post(`/api/devx-runs/${params.runId}/items`, params.items);
+}

package/dist/internal/git.d.ts

@@ -6,3 +6,4 @@ export interface GitMetadata {
 }
 export declare function readGitMetadata(rootDir?: string): Promise<GitMetadata>;
 export declare function getCurrentGitSha(rootDir?: string): Promise<string | undefined>;
+export declare function getChangedFilesSince(cwd: string, sha: string): Promise<string[] | undefined>;

package/dist/internal/git.js

@@ -18,6 +18,21 @@ export async function readGitMetadata(rootDir = process.cwd()) {
 export async function getCurrentGitSha(rootDir = process.cwd()) {
     return tryGit(rootDir, "rev-parse HEAD");
 }
+const GIT_SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
+export async function getChangedFilesSince(cwd, sha) {
+    if (!GIT_SHA_PATTERN.test(sha))
+        return undefined;
+    try {
+        const { stdout } = await execAsync(`git diff --name-only ${sha} HEAD`, { cwd });
+        return stdout
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean);
+    }
+    catch {
+        return undefined;
+    }
+}
 async function tryGit(cwd, args) {
     try {
         const { stdout } = await execAsync(`git ${args}`, { cwd });

package/dist/internal/packs/index.d.ts

@@ -1,4 +1,4 @@
-export type { PackType, PackContentEntry, PackScopeEntry, PackSignature, PackManifestV1, PackVersionSummary, PackVersionListing, PackSource, ResolvedScope, ResolvedPack, PackRegistryClient, } from "./types.js";
+export type { PackType, PackContentEntry, PackScopeEntry, PackTestEntry, PackSignature, PackManifestV1, PackVersionSummary, PackVersionListing, PackSource, ResolvedScope, ResolvedPack, PackRegistryClient, } from "./types.js";
 export { PackIntegrityError, PackUnavailableError, UnknownScopeError } from "./types.js";
 export { resolveCompatiblePack, resolveScope, listAvailableScopes } from "./resolve.js";
 export type { ResolveOptions } from "./resolve.js";

package/dist/internal/packs/resolve.js

@@ -82,7 +82,7 @@ export async function resolveScope(resolved, scopeId) {
     }
     const fs = await import("node:fs/promises");
     const content = await fs.readFile(`${resolved.cacheDir}/${scope.path}`, "utf-8");
-    return { id: scope.id, label: scope.label, description: scope.description, content };
+    return { id: scope.id, label: scope.label, description: scope.description, content, tests: scope.tests ?? [] };
 }
 export function listAvailableScopes(resolved) {
     return resolved.scopes.map(({ id, label, description }) => ({ id, label, description }));

package/dist/internal/packs/types.d.ts

@@ -3,10 +3,16 @@ export interface PackContentEntry {
     path: string;
     sha256: string;
 }
+export interface PackTestEntry {
+    id: string;
+    title: string;
+    deprecated?: boolean;
+}
 export interface PackScopeEntry extends PackContentEntry {
     id: string;
     label: string;
     description: string;
+    tests?: PackTestEntry[];
 }
 export interface PackSignature {
     algorithm: "ed25519";
@@ -41,6 +47,7 @@ export interface ResolvedScope {
     label: string;
     description: string;
     content: string;
+    tests: PackTestEntry[];
 }
 export interface ResolvedPack {
     packId: string;

package/dist/internal/security-context.d.ts

@@ -42,6 +42,7 @@ export interface SecurityContext {
         methodology: string | null;
     } | null;
     trustRoomUrl: string | null;
+    trustRoomSource?: string | null;
     generatedAt: string;
     gaps: {
         field: string;

package/dist/internal/test-scope.d.ts

@@ -1,6 +1,6 @@
 import { type DevXRunApi } from "./devx-run.js";
 import { type SecurityContextApi, type SecurityContextOutcome } from "./security-context.js";
-import type { PackRegistryClient } from "./packs/types.js";
+import type { PackRegistryClient, PackTestEntry } from "./packs/types.js";
 export interface TestRunDeps {
     apiClient: DevXRunApi & SecurityContextApi;
     registryClient: PackRegistryClient;
@@ -10,10 +10,12 @@ export interface StartTestRunParams {
     scopeId?: string;
     cwd: string;
     cliVersion: string;
+    precomputedContext?: SecurityContextOutcome;
 }
 export interface ResolvedScopeSummary {
     id: string;
     label: string;
+    tests: PackTestEntry[];
 }
 export interface TestRunEnvelope {
     run_id: string;
@@ -56,6 +58,35 @@ export interface StartTestRunResult {
     contextOutcome: SecurityContextOutcome;
 }
 export declare function startTestRun(deps: TestRunDeps, params: StartTestRunParams): Promise<StartTestRunResult>;
+export type ChangeRecommendationOutcome = {
+    kind: "no-prior-context";
+    contextOutcome: SecurityContextOutcome;
+} | {
+    kind: "sha-not-found";
+    sha: string;
+    contextOutcome: SecurityContextOutcome;
+} | {
+    kind: "up-to-date";
+    sha: string;
+} | {
+    kind: "no-scope-match";
+    sha: string;
+    changedFileCount: number;
+} | {
+    kind: "recommendation";
+    sha: string;
+    changedFileCount: number;
+    scopes: {
+        id: string;
+        label: string;
+    }[];
+    testIds: string[];
+};
+export declare function tryBuildChangeRecommendation(deps: TestRunDeps, params: {
+    applicationId: string;
+    cwd: string;
+    cliVersion: string;
+}): Promise<ChangeRecommendationOutcome>;
 export interface TestScopeListing {
     pack: string;
     version: string;

package/dist/internal/test-scope.js

@@ -1,34 +1,48 @@
-import { readGitMetadata } from "./git.js";
+import { readGitMetadata, getChangedFilesSince } from "./git.js";
 import { startDevXRun, DEVX_RUN_CONTRACT_VERSION } from "./devx-run.js";
 import { fetchSecurityContext } from "./security-context.js";
 import { resolveCompatiblePack, resolveScope, listAvailableScopes } from "./packs/resolve.js";
 import { writeRunWorkFile } from "./run-workdir.js";
+import { buildChangeRecommendation } from "./change-recommendation.js";
 function scopeContentPath(resolved, scopeId) {
     const entry = resolved.scopes.find((s) => s.id === scopeId);
     return entry ? `${resolved.cacheDir}/${entry.path}` : resolved.cacheDir;
 }
+function formatDeclaredTestCatalog(tests) {
+    return tests
+        .filter((t) => !t.deprecated)
+        .map((t) => `${t.id} — ${t.title}`)
+        .join("; ");
+}
 function buildAgentInstructions(resolvedScope) {
     if (resolvedScope) {
+        const catalog = formatDeclaredTestCatalog(resolvedScope.tests);
         return [
             `Read the base methodology and the "${resolvedScope.label}" scope guidance at methodology.scope.path.`,
             `Focus this review on the "${resolvedScope.label}" scope. Requested intent is scope=${resolvedScope.id} — this does not mean other areas were evaluated.`,
+            ...(catalog
+                ? [
+                    `This scope's declared test catalog: ${catalog}. When you emit observations[].test_id, use exactly one of these declared ids for the check you actually ran — never invent a slug from the prose. If none of them matches what you ran, do not fabricate a new id; describe it in coverage_note instead.`,
+                ]
+                : []),
             `You may report incidental findings outside this scope if you actually find them, but keep result provenance honest: do not claim coverage you did not perform.`,
             `Use your own repository understanding, shell, and tools to perform the review. When finished, complete the run using result_contract.complete_command.`,
         ];
     }
     return [
         `Read the methodology at methodology.path and perform a full, adaptive AppSec review — decide applicability yourself rather than mechanically executing every category.`,
+        `Each scope you apply declares its own stable, permanent test catalog (tests[] in the pack manifest, e.g. AUTH-001, UPLOAD-002 — see the scope's manifest entry). When you emit observations[].test_id, use the declared id for the check you actually ran — never invent a slug from the prose.`,
         `Use your own repository understanding, shell, and tools to perform the review. When finished, complete the run using result_contract.complete_command.`,
     ];
 }
 export async function startTestRun(deps, params) {
     const [git, contextOutcome, resolvedPack] = await Promise.all([
         readGitMetadata(params.cwd),
-        fetchSecurityContext(deps.apiClient, params.applicationId),
+        params.precomputedContext ?? fetchSecurityContext(deps.apiClient, params.applicationId),
         resolveCompatiblePack("appsec", { registryClient: deps.registryClient, cliVersion: params.cliVersion }),
     ]);
     const scope = params.scopeId ? await resolveScope(resolvedPack, params.scopeId) : null;
-    const resolvedScope = scope ? { id: scope.id, label: scope.label } : null;
+    const resolvedScope = scope ? { id: scope.id, label: scope.label, tests: scope.tests } : null;
     const started = await startDevXRun(deps.apiClient, {
         applicationId: params.applicationId,
         runType: "test",
@@ -59,6 +73,24 @@ export async function startTestRun(deps, params) {
     };
     return { envelope, resolvedScope, contextOutcome };
 }
+export async function tryBuildChangeRecommendation(deps, params) {
+    const contextOutcome = await fetchSecurityContext(deps.apiClient, params.applicationId);
+    const sha = contextOutcome.available ? contextOutcome.context.lastTestedGitSha : null;
+    if (!sha)
+        return { kind: "no-prior-context", contextOutcome };
+    const changedFiles = await getChangedFilesSince(params.cwd, sha);
+    if (changedFiles === undefined)
+        return { kind: "sha-not-found", sha, contextOutcome };
+    if (changedFiles.length === 0)
+        return { kind: "up-to-date", sha };
+    const resolvedPack = await resolveCompatiblePack("appsec", { registryClient: deps.registryClient, cliVersion: params.cliVersion });
+    const recommendation = buildChangeRecommendation(changedFiles, resolvedPack.scopes);
+    if (!recommendation)
+        return { kind: "no-scope-match", sha, changedFileCount: changedFiles.length };
+    const scopesById = new Map(resolvedPack.scopes.map((s) => [s.id, s]));
+    const scopes = recommendation.scopeIds.map((id) => ({ id, label: scopesById.get(id).label }));
+    return { kind: "recommendation", sha, changedFileCount: changedFiles.length, scopes, testIds: recommendation.testIds };
+}
 export async function listTestScopes(registryClient, cliVersion) {
     const resolvedPack = await resolveCompatiblePack("appsec", { registryClient, cliVersion });
     return {

package/dist/internal/trust-room-link.d.ts

@@ -0,0 +1,10 @@
+export interface TrustRoomLinkFields {
+    trustRoomUrl?: string | null;
+    trustRoomSource?: string | null;
+}
+export interface TrustRoomJsonFields {
+    trust_room_url?: string;
+    trust_room_source?: string;
+}
+export declare function trustRoomJsonFields(link: TrustRoomLinkFields | null | undefined): TrustRoomJsonFields;
+export declare function trustRoomHumanLines(link: TrustRoomLinkFields | null | undefined): string[];

package/dist/internal/trust-room-link.js

@@ -0,0 +1,15 @@
+export function trustRoomJsonFields(link) {
+    const url = link?.trustRoomUrl;
+    if (!url)
+        return {};
+    return {
+        trust_room_url: url,
+        ...(link?.trustRoomSource ? { trust_room_source: link.trustRoomSource } : {}),
+    };
+}
+export function trustRoomHumanLines(link) {
+    const url = link?.trustRoomUrl;
+    if (!url)
+        return [];
+    return [`Trust Room: ${url}`];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zivis/cli",
-  "version": "0.1.0-alpha.46",
+  "version": "0.1.0-alpha.52",
   "description": "ZIVIS CLI — threat modeling, scans, and MCP server for IDE integration",
   "license": "Apache-2.0",
   "homepage": "https://zivis.ai",
@@ -34,7 +34,7 @@
     "open": "^10.1.0",
     "tar": "^7.5.22",
     "web-tree-sitter": "^0.26.8",
-    "@zivis/mcp": "0.1.7"
+    "@zivis/mcp": "0.1.10"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",