@testchimp/cli 0.1.28 → 0.1.30

package/dist/cli/program.js

@@ -55,7 +55,9 @@ function addAgentTraceabilityOptions(cmd) {
         .option("--actor-type <type>", "LOCAL_AGENT | CLOUD_AGENT")
         .option("--user-id <id>", "Optional user id")
         .option("--branch-name <name>", "Git branch name")
-        .option("--agent-model <model>", "Optional agent model id (agent/CLI only)");
+        .option("--agent-model <model>", "Optional agent model id (agent/CLI only)")
+        .option("--skill-version <semver>", "TestChimp skill version from SKILL.md frontmatter")
+        .option("--cli-version <semver>", "CLI version (defaults to this package version)");
 }
 function collectAgentTraceabilityFlags(opts) {
     const body = {};
@@ -77,6 +79,10 @@ function collectAgentTraceabilityFlags(opts) {
         body.branchName = String(opts.branchName).trim();
     if (opts.agentModel)
         body.agentModel = String(opts.agentModel).trim();
+    if (opts.skillVersion)
+        body.skillVersion = String(opts.skillVersion).trim();
+    if (opts.cliVersion)
+        body.cliVersion = String(opts.cliVersion).trim();
     return body;
 }
 function stderrProgress(msg) {
@@ -127,8 +133,14 @@ export function buildCliProgram() {
         .option("--branch-name <s>")
         .option("--platform <web|ios|android>")
         .option("--record-types <csv>", "coverage sources: smart_test,manual (aliases: automated,smarttest)")
-        .option("--include-manual", "include manual sessions in addition to automated (default)")
+        .option("--include-manual", "include manual session coverage in addition to automated SmartTests")
         .option("--manual-only", "manual-only coverage (no automated)")
+        .option("--lifecycle-statuses <csv>", "scenario lifecycle allowlist (e.g. ready or draft,ready)")
+        .option("--limit <n>", "top N gaps after filter+rank into rankedScenarios (max 200)", (v) => parseInt(v, 10))
+        .option("--consider-scenario-priority", "rank by scenario priority high→medium→low→unset")
+        .option("--consider-semantic-coverage", "reserved ranking signal (accepted; no server effect yet)")
+        .option("--auto-verification-only", "exclude verification_strategy=manual (server default when unset)")
+        .option("--include-manual-verification", "include verification_strategy=manual (overrides --auto-verification-only)")
         .option("--file-paths <csv>", "comma-separated paths under platform tests root")
         .option("--folder-path <path>", "folder under tests root, slash-separated")
         .action(async (opts) => {
@@ -150,6 +162,22 @@ export function buildCliProgram() {
             recordTypes = ["manual"];
         if (recordTypes && recordTypes.length > 0)
             body.recordTypes = recordTypes;
+        if (opts.lifecycleStatuses) {
+            body.scenarioLifecycleStatuses = String(opts.lifecycleStatuses)
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean);
+        }
+        if (opts.limit != null && !Number.isNaN(opts.limit))
+            body.limit = opts.limit;
+        if (opts.considerScenarioPriority)
+            body.considerScenarioPriority = true;
+        if (opts.considerSemanticCoverage)
+            body.considerSemanticCoverage = true;
+        if (opts.includeManualVerification)
+            body.autoVerificationOnly = false;
+        else if (opts.autoVerificationOnly)
+            body.autoVerificationOnly = true;
         const scope = {};
         if (opts.filePaths)
             scope.filePaths = String(opts.filePaths).split(",").map((s) => s.trim()).filter(Boolean);
@@ -198,6 +226,43 @@ export function buildCliProgram() {
         const out = await runTool("get-execution-history", merged, { postMcp });
         console.log(out);
     });
+    program
+        .command("get-suite-execution-stats")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-suite-execution-stats").description)
+        .addOption(jsonInputOption())
+        .option("--release <s>")
+        .option("--environment <s>")
+        .option("--branch-name <s>")
+        .option("--scenario-id <id>")
+        .option("--test-id <id>")
+        .option("--platform <web|ios|android>")
+        .option("--file-paths <csv>")
+        .option("--folder-path <path>")
+        .action(async (opts) => {
+        const body = {};
+        if (opts.release)
+            body.release = opts.release;
+        if (opts.environment)
+            body.environment = opts.environment;
+        if (opts.branchName)
+            body.branchName = opts.branchName;
+        if (opts.scenarioId)
+            body.scenarioId = opts.scenarioId;
+        if (opts.testId)
+            body.testId = opts.testId;
+        if (opts.platform)
+            body.platform = opts.platform;
+        const scope = {};
+        if (opts.filePaths)
+            scope.filePaths = String(opts.filePaths).split(",").map((s) => s.trim()).filter(Boolean);
+        if (opts.folderPath)
+            scope.folderPath = opts.folderPath;
+        if (Object.keys(scope).length)
+            body.scope = scope;
+        const merged = mergeBodies(body, opts.jsonInput);
+        const out = await runTool("get-suite-execution-stats", merged, { postMcp });
+        console.log(out);
+    });
     program
         .command("fetch-execution-report")
         .description(TOOL_DEFINITIONS.find((t) => t.kebab === "fetch-execution-report").description)
@@ -481,6 +546,40 @@ export function buildCliProgram() {
         }, { postMcp });
         console.log(out);
     });
+    program
+        .command("get-spec-lifecycle-details")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "get-spec-lifecycle-details").description)
+        .addOption(jsonInputOption())
+        .option("--scenario-ids <csv>", "comma-separated scenario ordinals (bare 107 or TS-107 / #TS-107)")
+        .option("--story-ids <csv>", "comma-separated story ordinals (bare 12 or US-12 / #US-12)")
+        .action(async (opts) => {
+        const body = {};
+        if (opts.scenarioIds) {
+            const ids = String(opts.scenarioIds)
+                .split(",")
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+            if (ids.length > 0)
+                body.scenarioIds = ids;
+        }
+        if (opts.storyIds) {
+            const ids = String(opts.storyIds)
+                .split(",")
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+            if (ids.length > 0)
+                body.storyIds = ids;
+        }
+        const merged = mergeBodies(body, opts.jsonInput);
+        if (Array.isArray(merged.scenarioIds) && merged.scenarioIds.length === 0) {
+            delete merged.scenarioIds;
+        }
+        if (Array.isArray(merged.storyIds) && merged.storyIds.length === 0) {
+            delete merged.storyIds;
+        }
+        const out = await runTool("get-spec-lifecycle-details", merged, { postMcp });
+        console.log(out);
+    });
     addAgentTraceabilityOptions(program
         .command("update-test-scenario")
         .description(TOOL_DEFINITIONS.find((t) => t.kebab === "update-test-scenario").description)
@@ -1026,6 +1125,8 @@ export function buildCliProgram() {
         .option("--user-id <id>", "Optional user id for traceability")
         .option("--branch-name <name>", "Git branch")
         .option("--agent-model <model>", "Optional agent model id (agent/CLI only)")
+        .option("--skill-version <semver>", "TestChimp skill version from SKILL.md frontmatter")
+        .option("--cli-version <semver>", "CLI version (defaults to this package version)")
         .requiredOption("--entity-type <type>", "USER_STORY|SCENARIO|SMART_TEST|POLICY|ISSUE|TEST_EXECUTION|TEST_INVOCATION_BATCH|EXPLORATION|EVENT|WORKFLOW")
         .option("--entity-identity <ordinal>", "Project-scoped ordinal id (mutually exclusive with --test-json)")
         .option("--test-json <json>", "TestLocator JSON (folderPath/fileName/testSuite/testName)")
@@ -1051,6 +1152,10 @@ export function buildCliProgram() {
             body.branchName = String(opts.branchName);
         if (opts.agentModel)
             body.agentModel = String(opts.agentModel).trim();
+        if (opts.skillVersion)
+            body.skillVersion = String(opts.skillVersion).trim();
+        if (opts.cliVersion)
+            body.cliVersion = String(opts.cliVersion).trim();
         if (opts.entityIdentity)
             body.entityIdentity = String(opts.entityIdentity);
         if (opts.testJson)
@@ -1075,6 +1180,7 @@ export function buildCliProgram() {
         console.log(await runTool("get-last-run-workflow-detail", merged, { postMcp }));
     });
     for (const kebab of [
+        "get-org-capabilities",
         "list-workflow-executions",
         "get-workflow-execution",
         "get-policy",

package/dist/core/agentTraceability.d.ts

@@ -9,14 +9,31 @@ export type AgentTraceabilityFields = {
     userId?: string;
     branchName?: string;
     agentModel?: string;
+    skillVersion?: string;
+    cliVersion?: string;
     /** Nested form (wins over flat when both present and non-empty). */
     agentTraceability?: Record<string, unknown>;
 };
+/**
+ * Resolve skill / CLI versions for traceability payloads.
+ * CLI version defaults to this package's version; skill version from flag/env only.
+ */
+export declare function resolveToolchainVersions(a: {
+    skillVersion?: string;
+    cliVersion?: string;
+    nested?: Record<string, unknown> | null;
+}): {
+    skillVersion?: string;
+    cliVersion?: string;
+};
 /**
  * Build camelCase AgentActionTraceability for MCP JSON bodies.
  * Returns undefined unless the caller supplied explicit traceability intent
  * **and** a non-empty workflowId (server requires workflow_id for inline Activity).
- * Auto-fills gitSha / agentModel / userId only after that bar is met.
+ * For Activity/timeline attachment the server also requires workflowExecutionId
+ * (stable Plan ULID for the whole run) — omit it and the mutation still succeeds
+ * but no workflow_executions / Activity row is recorded (server does not auto-mint).
+ * Auto-fills gitSha / agentModel / userId / cliVersion only after the workflowId bar is met.
  * Non-empty nested `agentTraceability` wins over flat for overlapping keys.
  */
 export declare function buildAgentTraceabilityPayload(a: AgentTraceabilityFields): Record<string, unknown> | undefined;

package/dist/core/agentTraceability.js

@@ -1,4 +1,5 @@
 import { resolveGitHeadSha } from "./gitSha.js";
+import { PACKAGE_VERSION } from "./version.js";
 function nonEmptyString(v) {
     if (v == null)
         return undefined;
@@ -24,6 +25,10 @@ function hasExplicitTraceabilityIntent(a) {
         return true;
     if (nonEmptyString(a.agentModel))
         return true;
+    if (nonEmptyString(a.skillVersion))
+        return true;
+    if (nonEmptyString(a.cliVersion))
+        return true;
     if (a.agentTraceability && typeof a.agentTraceability === "object") {
         return Object.keys(a.agentTraceability).some((k) => nonEmptyString(a.agentTraceability[k]) != null);
     }
@@ -39,11 +44,28 @@ function normalizeActorType(raw) {
         return "LOCAL_AGENT";
     return undefined;
 }
+/**
+ * Resolve skill / CLI versions for traceability payloads.
+ * CLI version defaults to this package's version; skill version from flag/env only.
+ */
+export function resolveToolchainVersions(a) {
+    const skillVersion = nonEmptyString(a.nested?.skillVersion) ??
+        nonEmptyString(a.skillVersion) ??
+        nonEmptyString(process.env.TESTCHIMP_SKILL_VERSION);
+    const cliVersion = nonEmptyString(a.nested?.cliVersion) ??
+        nonEmptyString(a.cliVersion) ??
+        nonEmptyString(process.env.TESTCHIMP_CLI_VERSION) ??
+        PACKAGE_VERSION;
+    return { skillVersion, cliVersion };
+}
 /**
  * Build camelCase AgentActionTraceability for MCP JSON bodies.
  * Returns undefined unless the caller supplied explicit traceability intent
  * **and** a non-empty workflowId (server requires workflow_id for inline Activity).
- * Auto-fills gitSha / agentModel / userId only after that bar is met.
+ * For Activity/timeline attachment the server also requires workflowExecutionId
+ * (stable Plan ULID for the whole run) — omit it and the mutation still succeeds
+ * but no workflow_executions / Activity row is recorded (server does not auto-mint).
+ * Auto-fills gitSha / agentModel / userId / cliVersion only after the workflowId bar is met.
  * Non-empty nested `agentTraceability` wins over flat for overlapping keys.
  */
 export function buildAgentTraceabilityPayload(a) {
@@ -69,6 +91,11 @@ export function buildAgentTraceabilityPayload(a) {
     const agentModel = nonEmptyString(nested?.agentModel) ??
         nonEmptyString(a.agentModel) ??
         nonEmptyString(process.env.TESTCHIMP_AGENT_MODEL);
+    const { skillVersion, cliVersion } = resolveToolchainVersions({
+        skillVersion: a.skillVersion,
+        cliVersion: a.cliVersion,
+        nested,
+    });
     // Server requires workflow_id for inline mutation Activity — do not send orphan payloads.
     if (!workflowId) {
         return undefined;
@@ -91,5 +118,9 @@ export function buildAgentTraceabilityPayload(a) {
         out.branchName = branchName;
     if (agentModel)
         out.agentModel = agentModel;
+    if (skillVersion)
+        out.skillVersion = skillVersion;
+    if (cliVersion)
+        out.cliVersion = cliVersion;
     return out;
 }

package/dist/core/schemas.d.ts

@@ -28,6 +28,11 @@ export declare const listCoverageInput: z.ZodObject<{
         SMART_TEST: "SMART_TEST";
         MANUAL: "MANUAL";
     }>>>;
+    scenarioLifecycleStatuses: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    considerScenarioPriority: z.ZodOptional<z.ZodBoolean>;
+    considerSemanticCoverage: z.ZodOptional<z.ZodBoolean>;
+    autoVerificationOnly: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export declare const listExecutionInput: z.ZodObject<{
     release: z.ZodOptional<z.ZodString>;
@@ -51,6 +56,29 @@ export declare const listExecutionInput: z.ZodObject<{
     limit: z.ZodOptional<z.ZodNumber>;
     offset: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
+/** Same filters as get-execution-history; rolls up list_execution_history testStats. */
+export declare const suiteExecutionStatsInput: z.ZodObject<{
+    release: z.ZodOptional<z.ZodString>;
+    environment: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodObject<{
+        filePaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        folderPath: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodString]>>;
+    }, z.core.$strip>>;
+    branchName: z.ZodOptional<z.ZodString>;
+    scenarioId: z.ZodOptional<z.ZodString>;
+    testId: z.ZodOptional<z.ZodString>;
+    platform: z.ZodOptional<z.ZodEnum<{
+        web: "web";
+        ios: "ios";
+        android: "android";
+    }>>;
+    dimensionFilters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        dimension: z.ZodString;
+        values: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 export declare const fetchExecutionReportInput: z.ZodObject<{
     batchInvocationId: z.ZodOptional<z.ZodString>;
     jobId: z.ZodOptional<z.ZodString>;
@@ -77,6 +105,8 @@ export declare const agentActionTraceabilitySchema: z.ZodObject<{
     userId: z.ZodOptional<z.ZodString>;
     branchName: z.ZodOptional<z.ZodString>;
     agentModel: z.ZodOptional<z.ZodString>;
+    skillVersion: z.ZodOptional<z.ZodString>;
+    cliVersion: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 /** Flat + nested traceability fields shared by create/update MCP tools. */
 export declare const agentTraceabilityFieldsSchema: z.ZodObject<{
@@ -94,6 +124,8 @@ export declare const agentTraceabilityFieldsSchema: z.ZodObject<{
     userId: z.ZodOptional<z.ZodString>;
     branchName: z.ZodOptional<z.ZodString>;
     agentModel: z.ZodOptional<z.ZodString>;
+    skillVersion: z.ZodOptional<z.ZodString>;
+    cliVersion: z.ZodOptional<z.ZodString>;
     agentTraceability: z.ZodOptional<z.ZodObject<{
         workflowId: z.ZodOptional<z.ZodString>;
         workflowExecutionId: z.ZodOptional<z.ZodString>;
@@ -109,6 +141,8 @@ export declare const agentTraceabilityFieldsSchema: z.ZodObject<{
         userId: z.ZodOptional<z.ZodString>;
         branchName: z.ZodOptional<z.ZodString>;
         agentModel: z.ZodOptional<z.ZodString>;
+        skillVersion: z.ZodOptional<z.ZodString>;
+        cliVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const createUserStoryInput: z.ZodObject<{
@@ -128,6 +162,8 @@ export declare const createUserStoryInput: z.ZodObject<{
     userId: z.ZodOptional<z.ZodString>;
     branchName: z.ZodOptional<z.ZodString>;
     agentModel: z.ZodOptional<z.ZodString>;
+    skillVersion: z.ZodOptional<z.ZodString>;
+    cliVersion: z.ZodOptional<z.ZodString>;
     agentTraceability: z.ZodOptional<z.ZodObject<{
         workflowId: z.ZodOptional<z.ZodString>;
         workflowExecutionId: z.ZodOptional<z.ZodString>;
@@ -143,6 +179,8 @@ export declare const createUserStoryInput: z.ZodObject<{
         userId: z.ZodOptional<z.ZodString>;
         branchName: z.ZodOptional<z.ZodString>;
         agentModel: z.ZodOptional<z.ZodString>;
+        skillVersion: z.ZodOptional<z.ZodString>;
+        cliVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const createTestScenarioInput: z.ZodObject<{
@@ -163,6 +201,8 @@ export declare const createTestScenarioInput: z.ZodObject<{
     userId: z.ZodOptional<z.ZodString>;
     branchName: z.ZodOptional<z.ZodString>;
     agentModel: z.ZodOptional<z.ZodString>;
+    skillVersion: z.ZodOptional<z.ZodString>;
+    cliVersion: z.ZodOptional<z.ZodString>;
     agentTraceability: z.ZodOptional<z.ZodObject<{
         workflowId: z.ZodOptional<z.ZodString>;
         workflowExecutionId: z.ZodOptional<z.ZodString>;
@@ -178,6 +218,8 @@ export declare const createTestScenarioInput: z.ZodObject<{
         userId: z.ZodOptional<z.ZodString>;
         branchName: z.ZodOptional<z.ZodString>;
         agentModel: z.ZodOptional<z.ZodString>;
+        skillVersion: z.ZodOptional<z.ZodString>;
+        cliVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const updatePlanMarkdownInput: z.ZodObject<{
@@ -196,6 +238,8 @@ export declare const updatePlanMarkdownInput: z.ZodObject<{
     userId: z.ZodOptional<z.ZodString>;
     branchName: z.ZodOptional<z.ZodString>;
     agentModel: z.ZodOptional<z.ZodString>;
+    skillVersion: z.ZodOptional<z.ZodString>;
+    cliVersion: z.ZodOptional<z.ZodString>;
     agentTraceability: z.ZodOptional<z.ZodObject<{
         workflowId: z.ZodOptional<z.ZodString>;
         workflowExecutionId: z.ZodOptional<z.ZodString>;
@@ -211,6 +255,8 @@ export declare const updatePlanMarkdownInput: z.ZodObject<{
         userId: z.ZodOptional<z.ZodString>;
         branchName: z.ZodOptional<z.ZodString>;
         agentModel: z.ZodOptional<z.ZodString>;
+        skillVersion: z.ZodOptional<z.ZodString>;
+        cliVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const markPlanItemsImplementationDoneInput: z.ZodObject<{
@@ -222,6 +268,10 @@ export declare const updatePlanItemsLifecycleStatusInput: z.ZodObject<{
     ordinalId: z.ZodCoercedNumber<unknown>;
     status: z.ZodString;
 }, z.core.$strip>;
+export declare const getSpecLifecycleDetailsInput: z.ZodObject<{
+    scenarioIds: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>, z.ZodString>>>;
+    storyIds: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<string, string | number>>, z.ZodString>>>;
+}, z.core.$strip>;
 export declare const getUserStoriesInput: z.ZodObject<{
     userStoryOrdinalIds: z.ZodArray<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
@@ -265,6 +315,8 @@ export declare const updateIssueStatusInput: z.ZodObject<{
     userId: z.ZodOptional<z.ZodString>;
     branchName: z.ZodOptional<z.ZodString>;
     agentModel: z.ZodOptional<z.ZodString>;
+    skillVersion: z.ZodOptional<z.ZodString>;
+    cliVersion: z.ZodOptional<z.ZodString>;
     agentTraceability: z.ZodOptional<z.ZodObject<{
         workflowId: z.ZodOptional<z.ZodString>;
         workflowExecutionId: z.ZodOptional<z.ZodString>;
@@ -280,6 +332,8 @@ export declare const updateIssueStatusInput: z.ZodObject<{
         userId: z.ZodOptional<z.ZodString>;
         branchName: z.ZodOptional<z.ZodString>;
         agentModel: z.ZodOptional<z.ZodString>;
+        skillVersion: z.ZodOptional<z.ZodString>;
+        cliVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const createIssueInput: z.ZodObject<{
@@ -361,6 +415,8 @@ export declare const createIssueInput: z.ZodObject<{
     userId: z.ZodOptional<z.ZodString>;
     branchName: z.ZodOptional<z.ZodString>;
     agentModel: z.ZodOptional<z.ZodString>;
+    skillVersion: z.ZodOptional<z.ZodString>;
+    cliVersion: z.ZodOptional<z.ZodString>;
     agentTraceability: z.ZodOptional<z.ZodObject<{
         workflowId: z.ZodOptional<z.ZodString>;
         workflowExecutionId: z.ZodOptional<z.ZodString>;
@@ -376,6 +432,8 @@ export declare const createIssueInput: z.ZodObject<{
         userId: z.ZodOptional<z.ZodString>;
         branchName: z.ZodOptional<z.ZodString>;
         agentModel: z.ZodOptional<z.ZodString>;
+        skillVersion: z.ZodOptional<z.ZodString>;
+        cliVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const emptyInput: z.ZodObject<{}, z.core.$strip>;
@@ -1332,6 +1390,8 @@ export declare const reportAgentActionInput: z.ZodObject<{
     userId: z.ZodOptional<z.ZodString>;
     branchName: z.ZodOptional<z.ZodString>;
     agentModel: z.ZodOptional<z.ZodString>;
+    skillVersion: z.ZodOptional<z.ZodString>;
+    cliVersion: z.ZodOptional<z.ZodString>;
     traceability: z.ZodOptional<z.ZodObject<{
         workflowId: z.ZodOptional<z.ZodString>;
         workflowExecutionId: z.ZodOptional<z.ZodString>;
@@ -1347,6 +1407,8 @@ export declare const reportAgentActionInput: z.ZodObject<{
         userId: z.ZodOptional<z.ZodString>;
         branchName: z.ZodOptional<z.ZodString>;
         agentModel: z.ZodOptional<z.ZodString>;
+        skillVersion: z.ZodOptional<z.ZodString>;
+        cliVersion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     entityType: z.ZodEnum<{
         SMART_TEST: "SMART_TEST";

package/dist/core/schemas.js

@@ -26,6 +26,19 @@ export const listCoverageInput = z.object({
      * When provided, send proto enum names ("SMART_TEST", "MANUAL") or CLI-friendly aliases ("smart_test", "manual").
      */
     recordTypes: z.array(requirementCoverageRecordTypeSchema).optional(),
+    /** Allowlist of scenario lifecycle statuses (e.g. ["ready"] or ["draft","ready"]). Empty/omit = no status filter. */
+    scenarioLifecycleStatuses: z.array(z.string().min(1)).optional(),
+    /** When set (>0), truncate rankedScenarios to top N after filter+rank (server clamps to 200). */
+    limit: z.number().int().positive().max(200).optional(),
+    /** Rank by scenario priority high > medium > low > unset. */
+    considerScenarioPriority: z.boolean().optional(),
+    /** Reserved for future semantic-gap ranking; accepted by server, ignored in v1. */
+    considerSemanticCoverage: z.boolean().optional(),
+    /**
+     * Exclude scenarios with verification_strategy=manual. Server defaults to true when unset.
+     * Prefer --include-manual-verification (sets false) over setting this explicitly.
+     */
+    autoVerificationOnly: z.boolean().optional(),
 });
 export const listExecutionInput = z.object({
     release: z.string().optional(),
@@ -39,6 +52,8 @@ export const listExecutionInput = z.object({
     limit: z.number().int().positive().max(500).optional(),
     offset: z.number().int().nonnegative().optional(),
 });
+/** Same filters as get-execution-history; rolls up list_execution_history testStats. */
+export const suiteExecutionStatsInput = listExecutionInput;
 export const fetchExecutionReportInput = z
     .object({
     batchInvocationId: z.string().optional(),
@@ -67,6 +82,8 @@ export const agentActionTraceabilitySchema = z
     userId: z.string().optional(),
     branchName: z.string().optional(),
     agentModel: z.string().optional(),
+    skillVersion: z.string().optional(),
+    cliVersion: z.string().optional(),
 })
     .strict();
 /** Flat + nested traceability fields shared by create/update MCP tools. */
@@ -80,6 +97,8 @@ export const agentTraceabilityFieldsSchema = z.object({
     userId: z.string().optional(),
     branchName: z.string().optional(),
     agentModel: z.string().optional(),
+    skillVersion: z.string().optional(),
+    cliVersion: z.string().optional(),
     agentTraceability: agentActionTraceabilitySchema.optional(),
 });
 export const createUserStoryInput = z.object({
@@ -105,6 +124,19 @@ export const updatePlanItemsLifecycleStatusInput = z.object({
     /** draft | ready | in progress | blocked | done | archived */
     status: z.string().min(1),
 });
+export const getSpecLifecycleDetailsInput = z
+    .object({
+    /** Bare ordinals or TS-/ #TS- forms; numbers coerced to strings. */
+    scenarioIds: z
+        .array(z.union([z.string(), z.number()]).transform((v) => String(v).trim()).pipe(z.string().min(1)))
+        .optional(),
+    /** Bare ordinals or US-/ #US- forms; numbers coerced to strings. */
+    storyIds: z
+        .array(z.union([z.string(), z.number()]).transform((v) => String(v).trim()).pipe(z.string().min(1)))
+        .optional(),
+})
+    .refine((v) => (v.scenarioIds != null && v.scenarioIds.length > 0) ||
+    (v.storyIds != null && v.storyIds.length > 0), { message: "Provide scenarioIds and/or storyIds (non-empty)" });
 export const getUserStoriesInput = z
     .object({
     userStoryOrdinalIds: z.array(z.coerce.number().int().positive()).min(1),
@@ -659,6 +691,8 @@ export const reportAgentActionInput = z
     userId: z.string().optional(),
     branchName: z.string().optional(),
     agentModel: z.string().optional(),
+    skillVersion: z.string().optional(),
+    cliVersion: z.string().optional(),
     traceability: agentActionTraceabilitySchema.optional(),
     entityType: agentActionEntityTypeSchema,
     /** Project-scoped ordinal id (or explicitly provided execution/batch id). Mutually exclusive with `test`. */

package/dist/core/tools.js

@@ -2,7 +2,7 @@ import { normalizeScope } from "./normalize.js";
 import { runProvisionEphemeralEnvironmentAndWait } from "./ephemeralWait.js";
 import * as S from "./schemas.js";
 import { resolveGitHeadSha } from "./gitSha.js";
-import { buildAgentTraceabilityPayload } from "./agentTraceability.js";
+import { buildAgentTraceabilityPayload, resolveToolchainVersions } from "./agentTraceability.js";
 function platformToProtoEnum(platform) {
     switch (platform) {
         case "ios":
@@ -55,6 +55,17 @@ function listCoverageBody(args) {
         });
         body.recordTypes = normalized;
     }
+    if (args.scenarioLifecycleStatuses != null && args.scenarioLifecycleStatuses.length > 0) {
+        body.scenarioLifecycleStatuses = args.scenarioLifecycleStatuses.map((s) => String(s).trim()).filter(Boolean);
+    }
+    if (args.limit != null)
+        body.limit = args.limit;
+    if (args.considerScenarioPriority != null)
+        body.considerScenarioPriority = args.considerScenarioPriority;
+    if (args.considerSemanticCoverage != null)
+        body.considerSemanticCoverage = args.considerSemanticCoverage;
+    if (args.autoVerificationOnly != null)
+        body.autoVerificationOnly = args.autoVerificationOnly;
     return body;
 }
 function listExecutionBody(args) {
@@ -89,6 +100,45 @@ function listExecutionBody(args) {
         body.offset = args.offset;
     return body;
 }
+/** Mean success duration above this counts as a slow test (mirrors UI ExecutionTimingSummary). */
+const SLOW_TEST_MEAN_SECS = 30;
+function parseMeanSecs(raw) {
+    if (raw == null)
+        return null;
+    const n = Number(raw);
+    return Number.isFinite(n) && !Number.isNaN(n) && n >= 0 ? n : null;
+}
+/** Suite rollup from list_execution_history testStats (sum of success means = UI Total time). */
+function aggregateSuiteExecutionStats(testStats) {
+    const stats = Array.isArray(testStats) ? testStats : [];
+    let timedTestCount = 0;
+    let sumSuccessMeanSecs = 0;
+    let sumFailMeanSecs = 0;
+    let maxSuccessMeanSecs = 0;
+    let slowTestCount = 0;
+    for (const s of stats) {
+        const successMean = parseMeanSecs(s.successTiming?.meanSecs);
+        if (successMean != null) {
+            timedTestCount += 1;
+            sumSuccessMeanSecs += successMean;
+            if (successMean > maxSuccessMeanSecs)
+                maxSuccessMeanSecs = successMean;
+            if (successMean > SLOW_TEST_MEAN_SECS)
+                slowTestCount += 1;
+        }
+        const failMean = parseMeanSecs(s.failTiming?.meanSecs);
+        if (failMean != null)
+            sumFailMeanSecs += failMean;
+    }
+    return {
+        testCount: stats.length,
+        timedTestCount,
+        sumSuccessMeanSecs,
+        sumFailMeanSecs,
+        maxSuccessMeanSecs: timedTestCount > 0 ? maxSuccessMeanSecs : 0,
+        slowTestCount,
+    };
+}
 function requirementQualitySubjectBody(subjectType, opts) {
     const body = { subjectType };
     const entityId = (opts.subjectEntityId ?? "").trim();
@@ -127,12 +177,22 @@ async function loadRequirementQualityReportJson(args) {
     return {};
 }
 export const TOOL_DEFINITIONS = [
+    {
+        kebab: "get-org-capabilities",
+        description: "Fetch the organization's enabled capabilities (e.g. TRUE_COVERAGE, API_CONTRACT_COVERAGE) and " +
+            "freeTrialActive flag. Call before relying on TrueCoverage / API contract coverage features so " +
+            "playbooks can soft-skip gated insights instead of failing. Authenticated via project API key.",
+        inputSchema: S.emptyInput,
+        execute: async (_args, { postMcp }) => postMcp("/api/mcp/get_org_capabilities", {}),
+    },
     {
         kebab: "get-requirement-coverage",
         description: "Fetch requirement (scenario) coverage under an optional platform-rooted folder scope (tests/... or plans/...). " +
             "Use scope.filePaths or scope.folderPath (platform tests/plans roots). Omit branchName for cross-branch coverage " +
             "(aggregates branch copies; execution jobs deduped by stable hash of tests-root-relative path + test name). " +
-            "Pass branchName only when results must be limited to one Git branch. Optional platform (web|ios|android) filters rollup.",
+            "Pass branchName only when results must be limited to one Git branch. Optional platform (web|ios|android) filters rollup. " +
+            "For top-N gap recommendations: set scenarioLifecycleStatuses, considerScenarioPriority / considerSemanticCoverage, and limit; " +
+            "prefer response rankedScenarios (gaps only). Server excludes verification_strategy=manual by default (autoVerificationOnly).",
         inputSchema: S.listCoverageInput,
         execute: async (args, { postMcp }) => {
             const json = await postMcp("/api/mcp/list_requirement_coverage", listCoverageBody(args));
@@ -150,6 +210,20 @@ export const TOOL_DEFINITIONS = [
             return json;
         },
     },
+    {
+        kebab: "get-suite-execution-stats",
+        description: "Aggregate suite timing from list_execution_history testStats (same filters as get-execution-history). " +
+            "Returns testCount, timedTestCount, sumSuccessMeanSecs (UI ExecutionTimingSummary total), sumFailMeanSecs, " +
+            "maxSuccessMeanSecs, slowTestCount (success mean > 30s). " +
+            "Sum of means is aggregate test CPU-time, not CI wall-clock under parallelism. " +
+            "Compare sumSuccessMeanSecs against any suite budget in the agent — this tool only returns stats.",
+        inputSchema: S.suiteExecutionStatsInput,
+        execute: async (args, { postMcp }) => {
+            const json = await postMcp("/api/mcp/list_execution_history", listExecutionBody(args));
+            const parsed = JSON.parse(json);
+            return JSON.stringify(aggregateSuiteExecutionStats(parsed.testStats));
+        },
+    },
     {
         kebab: "fetch-execution-report",
         description: "Fetch a detailed execution report for failing SmartTests, given a batchInvocationId (batch run) or jobId (single run). " +
@@ -306,7 +380,8 @@ export const TOOL_DEFINITIONS = [
             "status must be one of: ACTIVE, IGNORED, FIXED, DUPLICATE, IN_PROGRESS_BUG, ARCHIVED_BUG, BLOCKED. " +
             "For /testchimp fix issue: set IN_PROGRESS_BUG after applying a code fix; set FIXED only after user confirmation / commits pushed. " +
             "Optional ignoreReason when status is IGNORED: INTENDED_BEHAVIOUR | INACCURATE_ASSESSMENT | NOT_IMPORTANT. " +
-            "Optional agentTraceability records UPDATED Activity inline.",
+            "Optional agentTraceability records UPDATED Activity inline " +
+            "(requires both workflowId and workflowExecutionId for Activity attachment).",
         inputSchema: S.updateIssueStatusInput,
         execute: async (args, { postMcp }) => {
             const a = args;
@@ -330,8 +405,10 @@ export const TOOL_DEFINITIONS = [
             "linkTargets, labels, source, environment, attachments, artifactReference). " +
             "For /testchimp implement TASK_ISSUE creates: set labels=[\"TestChimp Implement\"] (not source), " +
             "severity from task priority, category (e.g. FUNCTIONAL), and linkTargets for STORY and/or SCENARIO ordinals. " +
-            "Optional agentTraceability (or flat workflowId/policyFile/…) records CREATED Activity inline — " +
+            "Optional agentTraceability (or flat workflowId/workflowExecutionId/policyFile/…) records CREATED Activity inline — " +
             "prefer this over a separate report-agent-action for issue creates. " +
+            "For Activity/timeline attachment both workflowId and workflowExecutionId (stable Plan ULID) are required; " +
+            "do not omit workflowExecutionId or mint a new ULID per issue. " +
             "Authenticated via project API key; project is resolved from the key.",
         inputSchema: S.createIssueInput,
         execute: async (args, { postMcp }) => {
@@ -401,6 +478,22 @@ export const TOOL_DEFINITIONS = [
             });
         },
     },
+    {
+        kebab: "get-spec-lifecycle-details",
+        description: "Fetch lifecycle_fields for user stories and/or test scenarios by ordinal id (DB only; no markdown). " +
+            "Pass scenarioIds / storyIds as lists of bare ordinals (canonical) or prefixed forms (TS-107, #US-12). " +
+            "Use after identifying scenarios in scope for create-tests to read verification_strategy (auto|manual) and skip manual ones.",
+        inputSchema: S.getSpecLifecycleDetailsInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            const body = {};
+            if (a.scenarioIds?.length)
+                body.scenarioIds = a.scenarioIds;
+            if (a.storyIds?.length)
+                body.storyIds = a.storyIds;
+            return postMcp("/api/mcp/get_spec_lifecycle_details", body);
+        },
+    },
     {
         kebab: "get-eaas-config",
         description: "Return the project's BunnyShell (Environment-as-a-Service) settings. Secrets are never returned.",
@@ -947,7 +1040,15 @@ export const TOOL_DEFINITIONS = [
                 body.userId = process.env.TESTCHIMP_USER_ID;
             if (a.branchName)
                 body.branchName = a.branchName;
-            // Nested traceability wins for agentModel; only fill from flat/env when nested omits it.
+            // Nested traceability wins for agentModel / skillVersion / cliVersion;
+            // fill from flat/env/package when nested omits them.
+            const { skillVersion, cliVersion } = resolveToolchainVersions({
+                skillVersion: a.skillVersion,
+                cliVersion: a.cliVersion,
+                nested: a.traceability && typeof a.traceability === "object"
+                    ? a.traceability
+                    : null,
+            });
             if (a.traceability && typeof a.traceability === "object") {
                 const nested = { ...a.traceability };
                 const nestedModel = nested.agentModel != null && String(nested.agentModel).trim() !== ""
@@ -960,12 +1061,23 @@ export const TOOL_DEFINITIONS = [
                 else if (flatModel) {
                     nested.agentModel = flatModel;
                 }
+                if (skillVersion)
+                    nested.skillVersion = skillVersion;
+                if (cliVersion)
+                    nested.cliVersion = cliVersion;
                 body.traceability = nested;
             }
             else {
                 const model = a.agentModel?.trim() || process.env.TESTCHIMP_AGENT_MODEL?.trim();
-                if (model) {
-                    body.traceability = { agentModel: model };
+                const nested = {};
+                if (model)
+                    nested.agentModel = model;
+                if (skillVersion)
+                    nested.skillVersion = skillVersion;
+                if (cliVersion)
+                    nested.cliVersion = cliVersion;
+                if (Object.keys(nested).length > 0) {
+                    body.traceability = nested;
                 }
             }
             if (a.test) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@testchimp/cli",
-  "version": "0.1.28",
-  "description": "TestChimp CLI and MCP server \u2014 coverage, plans, EaaS, TrueCoverage, API operations (calls /api/mcp/*)",
+  "version": "0.1.30",
+  "description": "TestChimp CLI and MCP server — coverage, plans, EaaS, TrueCoverage, API operations (calls /api/mcp/*)",
   "type": "module",
   "main": "dist/bin/testchimp.js",
   "types": "dist/bin/testchimp.d.ts",