@testchimp/cli 0.1.21 → 0.1.23

package/dist/cli/program.js

@@ -5,6 +5,7 @@ import { DEFAULT_BACKEND, postMcp } from "../core/client.js";
 import { deepMerge } from "../core/merge.js";
 import { runTool } from "../core/tools.js";
 import { TOOL_DEFINITIONS } from "../core/tools.js";
+import { resolveGitHeadSha } from "../core/gitSha.js";
 import { PACKAGE_VERSION } from "../core/version.js";
 export { PACKAGE_VERSION };
 function parseRecordTypesCsv(raw) {
@@ -43,6 +44,41 @@ function mergeBodies(flagBody, jsonInputRaw) {
         return flagBody;
     return deepMerge(flagBody, extra);
 }
+/** Shared agent policy/traceability flags for mutating CRUD commands. */
+function addAgentTraceabilityOptions(cmd) {
+    return cmd
+        .option("--workflow-id <id>", "Catalog workflow id for agent Activity")
+        .option("--workflow-execution-id <ulid>", "Stable ULID for the whole agent run")
+        .option("--policy-file <name>", "Policy filename (e.g. run-qa.policy.md)")
+        .option("--policy-version <semver>", "Policy version from frontmatter")
+        .option("--git-sha <sha>", "Git SHA (defaults to HEAD)")
+        .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)");
+}
+function collectAgentTraceabilityFlags(opts) {
+    const body = {};
+    if (opts.workflowId)
+        body.workflowId = String(opts.workflowId).trim();
+    if (opts.workflowExecutionId)
+        body.workflowExecutionId = String(opts.workflowExecutionId).trim();
+    if (opts.policyFile)
+        body.policyFile = String(opts.policyFile).trim();
+    if (opts.policyVersion)
+        body.policyVersion = String(opts.policyVersion).trim();
+    if (opts.gitSha)
+        body.gitSha = String(opts.gitSha).trim();
+    if (opts.actorType)
+        body.actorType = String(opts.actorType).trim();
+    if (opts.userId)
+        body.userId = String(opts.userId).trim();
+    if (opts.branchName)
+        body.branchName = String(opts.branchName).trim();
+    if (opts.agentModel)
+        body.agentModel = String(opts.agentModel).trim();
+    return body;
+}
 function stderrProgress(msg) {
     console.error(`[testchimp] ${msg}`);
 }
@@ -175,48 +211,50 @@ export function buildCliProgram() {
         const out = await runTool("fetch-execution-report", merged, { postMcp });
         console.log(out);
     });
-    program
+    addAgentTraceabilityOptions(program
         .command("create-user-story")
         .description(TOOL_DEFINITIONS.find((t) => t.kebab === "create-user-story").description)
         .addOption(jsonInputOption())
         .requiredOption("--platform-file-path <path>")
-        .requiredOption("--title <title>")
-        .action(async (opts) => {
-        const body = { platformFilePath: opts.platformFilePath, title: opts.title };
+        .requiredOption("--title <title>")).action(async (opts) => {
+        const body = {
+            platformFilePath: opts.platformFilePath,
+            title: opts.title,
+            ...collectAgentTraceabilityFlags(opts),
+        };
         const merged = mergeBodies(body, opts.jsonInput);
         const out = await runTool("create-user-story", merged, { postMcp });
         console.log(out);
     });
-    program
+    addAgentTraceabilityOptions(program
         .command("create-test-scenario")
         .description(TOOL_DEFINITIONS.find((t) => t.kebab === "create-test-scenario").description)
         .addOption(jsonInputOption())
         .requiredOption("--platform-file-path <path>")
         .requiredOption("--title <title>")
-        .requiredOption("--user-story-ordinal-id <n>")
-        .action(async (opts) => {
+        .requiredOption("--user-story-ordinal-id <n>")).action(async (opts) => {
         const body = {
             platformFilePath: opts.platformFilePath,
             title: opts.title,
             userStoryOrdinalId: Number(opts.userStoryOrdinalId),
+            ...collectAgentTraceabilityFlags(opts),
         };
         const merged = mergeBodies(body, opts.jsonInput);
         const out = await runTool("create-test-scenario", merged, { postMcp });
         console.log(out);
     });
-    program
+    addAgentTraceabilityOptions(program
         .command("update-user-story")
         .description(TOOL_DEFINITIONS.find((t) => t.kebab === "update-user-story").description)
         .addOption(jsonInputOption())
         .option("--content <markdown>", "full markdown including frontmatter")
-        .option("--content-file <path>", "read markdown from file")
-        .action(async (opts) => {
+        .option("--content-file <path>", "read markdown from file")).action(async (opts) => {
         let content = opts.content;
         if (opts.contentFile)
             content = await readFile(String(opts.contentFile), "utf8");
         if (!content)
             throw new Error("Provide --content or --content-file (or full body via --json-input)");
-        const body = { content };
+        const body = { content, ...collectAgentTraceabilityFlags(opts) };
         const merged = mergeBodies(body, opts.jsonInput);
         const out = await runTool("update-user-story", merged, { postMcp });
         console.log(out);
@@ -285,15 +323,16 @@ export function buildCliProgram() {
         const out = await runTool("get-issue-details", { issueId: String(merged.issueId).trim() }, { postMcp });
         console.log(out);
     });
-    program
+    addAgentTraceabilityOptions(program
         .command("update-issue-status")
         .description(TOOL_DEFINITIONS.find((t) => t.kebab === "update-issue-status").description)
         .addOption(jsonInputOption())
         .option("--issue-id <id>", "Issue ordinal id (#B-123, B-123, B123, or 123)")
         .option("--status <status>", "ACTIVE | IGNORED | FIXED | DUPLICATE | IN_PROGRESS_BUG | ARCHIVED_BUG | BLOCKED")
-        .option("--ignore-reason <reason>", "When status=IGNORED: INTENDED_BEHAVIOUR | INACCURATE_ASSESSMENT | NOT_IMPORTANT")
-        .action(async (opts) => {
-        const body = {};
+        .option("--ignore-reason <reason>", "When status=IGNORED: INTENDED_BEHAVIOUR | INACCURATE_ASSESSMENT | NOT_IMPORTANT")).action(async (opts) => {
+        const body = {
+            ...collectAgentTraceabilityFlags(opts),
+        };
         if (opts.issueId)
             body.issueId = String(opts.issueId).trim();
         if (opts.status)
@@ -307,16 +346,10 @@ export function buildCliProgram() {
         if (!merged.status || String(merged.status).trim() === "") {
             throw new Error("status is required (ACTIVE | IGNORED | FIXED | DUPLICATE | IN_PROGRESS_BUG | ARCHIVED_BUG | BLOCKED)");
         }
-        const out = await runTool("update-issue-status", {
-            issueId: String(merged.issueId).trim(),
-            status: String(merged.status).trim(),
-            ...(merged.ignoreReason
-                ? { ignoreReason: String(merged.ignoreReason).trim() }
-                : {}),
-        }, { postMcp });
+        const out = await runTool("update-issue-status", merged, { postMcp });
         console.log(out);
     });
-    program
+    addAgentTraceabilityOptions(program
         .command("create-issue")
         .description(TOOL_DEFINITIONS.find((t) => t.kebab === "create-issue").description)
         .addOption(jsonInputOption())
@@ -331,9 +364,10 @@ export function buildCliProgram() {
         .option("--assignee <userId>", "Assignee user id")
         .option("--labels <csv>", "Comma-separated labels")
         .option("--source <name>", "External ingest source identifier (stored as label source:<name>)")
-        .option("--environment <name>", "Environment tag (defaults to QA when omitted)")
-        .action(async (opts) => {
-        const body = {};
+        .option("--environment <name>", "Environment tag (defaults to QA when omitted)")).action(async (opts) => {
+        const body = {
+            ...collectAgentTraceabilityFlags(opts),
+        };
         if (opts.title)
             body.title = String(opts.title).trim();
         if (opts.description)
@@ -394,18 +428,50 @@ export function buildCliProgram() {
         console.log(out);
     });
     program
+        .command("update-plan-items-lifecycle-status")
+        .description(TOOL_DEFINITIONS.find((t) => t.kebab === "update-plan-items-lifecycle-status").description)
+        .addOption(jsonInputOption())
+        .option("--entity-type <type>", "story | scenario")
+        .option("--ordinal-id <n>", "numeric US-/TS- ordinal")
+        .option("--status <status>", "draft | ready | in progress | blocked | done | archived")
+        .action(async (opts) => {
+        const body = {};
+        if (opts.entityType)
+            body.entityType = String(opts.entityType).trim();
+        if (opts.ordinalId != null && String(opts.ordinalId).trim() !== "") {
+            body.ordinalId = Number(String(opts.ordinalId).trim());
+        }
+        if (opts.status)
+            body.status = String(opts.status).trim();
+        const merged = mergeBodies(body, opts.jsonInput);
+        if (!merged.entityType || String(merged.entityType).trim() === "") {
+            throw new Error("entity-type is required (story | scenario)");
+        }
+        if (merged.ordinalId == null || !Number.isFinite(merged.ordinalId) || merged.ordinalId <= 0) {
+            throw new Error("ordinal-id is required (positive integer)");
+        }
+        if (!merged.status || String(merged.status).trim() === "") {
+            throw new Error("status is required (draft | ready | in progress | blocked | done | archived)");
+        }
+        const out = await runTool("update-plan-items-lifecycle-status", {
+            entityType: String(merged.entityType).trim(),
+            ordinalId: merged.ordinalId,
+            status: String(merged.status).trim(),
+        }, { postMcp });
+        console.log(out);
+    });
+    addAgentTraceabilityOptions(program
         .command("update-test-scenario")
         .description(TOOL_DEFINITIONS.find((t) => t.kebab === "update-test-scenario").description)
         .addOption(jsonInputOption())
         .option("--content <markdown>")
-        .option("--content-file <path>")
-        .action(async (opts) => {
+        .option("--content-file <path>")).action(async (opts) => {
         let content = opts.content;
         if (opts.contentFile)
             content = await readFile(String(opts.contentFile), "utf8");
         if (!content)
             throw new Error("Provide --content or --content-file (or full body via --json-input)");
-        const body = { content };
+        const body = { content, ...collectAgentTraceabilityFlags(opts) };
         const merged = mergeBodies(body, opts.jsonInput);
         const out = await runTool("update-test-scenario", merged, { postMcp });
         console.log(out);
@@ -904,43 +970,43 @@ export function buildCliProgram() {
         .addOption(jsonInputOption())
         .requiredOption("--workflow-id <id>", "Catalog workflow id")
         .requiredOption("--workflow-execution-id <ulid>", "Stable ULID for the whole run")
-        .requiredOption("--action-type <type>", "CREATED|UPDATED|DELETED|ANALYZED|ACTION_COMPLETED|ACTION_FAILED")
+        .requiredOption("--action-type <type>", "CREATED|UPDATED|DELETED|ANALYZED|IMPLEMENTED|ACTION_COMPLETED|ACTION_FAILED")
         .option("--policy-file <name>", "Policy filename")
         .option("--policy-version <semver>", "Policy version from frontmatter")
         .option("--git-sha <sha>", "Current HEAD sha")
         .option("--actor-type <type>", "LOCAL_AGENT|CLOUD_AGENT (or local-agent|cloud-agent)")
         .option("--user-id <id>", "Optional user id for traceability")
         .option("--branch-name <name>", "Git branch")
-        .option("--entity-type <type>", "test|story|scenario|issue|workflow|…")
+        .option("--agent-model <model>", "Optional agent model id (agent/CLI only)")
+        .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)")
-        .option("--detail-json <json>", "Optional detail payload")
         .action(async (opts) => {
         const body = {
             workflowId: String(opts.workflowId),
             workflowExecutionId: String(opts.workflowExecutionId),
             actionType: String(opts.actionType),
+            entityType: String(opts.entityType),
         };
         if (opts.policyFile)
             body.policyFile = String(opts.policyFile);
         if (opts.policyVersion)
             body.policyVersion = String(opts.policyVersion);
-        if (opts.gitSha)
-            body.gitSha = String(opts.gitSha);
+        const gitSha = resolveGitHeadSha(opts.gitSha ? String(opts.gitSha) : undefined);
+        if (gitSha)
+            body.gitSha = gitSha;
         if (opts.actorType)
             body.actorType = String(opts.actorType);
         if (opts.userId)
             body.userId = String(opts.userId);
         if (opts.branchName)
             body.branchName = String(opts.branchName);
-        if (opts.entityType)
-            body.entityType = String(opts.entityType);
+        if (opts.agentModel)
+            body.agentModel = String(opts.agentModel).trim();
         if (opts.entityIdentity)
             body.entityIdentity = String(opts.entityIdentity);
         if (opts.testJson)
             body.test = JSON.parse(String(opts.testJson));
-        if (opts.detailJson)
-            body.detailJson = String(opts.detailJson);
         const merged = mergeBodies(body, opts.jsonInput);
         console.log(await runTool("report-agent-action", merged, { postMcp }));
     });

package/dist/core/agentTraceability.d.ts

@@ -0,0 +1,22 @@
+/** Flat CLI/MCP fields that map to AgentActionTraceability. */
+export type AgentTraceabilityFields = {
+    workflowId?: string;
+    workflowExecutionId?: string;
+    policyFile?: string;
+    policyVersion?: string;
+    gitSha?: string;
+    actorType?: string;
+    userId?: string;
+    branchName?: string;
+    agentModel?: string;
+    /** Nested form (wins over flat when both present and non-empty). */
+    agentTraceability?: Record<string, unknown>;
+};
+/**
+ * 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.
+ * 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

@@ -0,0 +1,95 @@
+import { resolveGitHeadSha } from "./gitSha.js";
+function nonEmptyString(v) {
+    if (v == null)
+        return undefined;
+    const s = String(v).trim();
+    return s === "" ? undefined : s;
+}
+function hasExplicitTraceabilityIntent(a) {
+    if (nonEmptyString(a.workflowId))
+        return true;
+    if (nonEmptyString(a.workflowExecutionId))
+        return true;
+    if (nonEmptyString(a.policyFile))
+        return true;
+    if (nonEmptyString(a.policyVersion))
+        return true;
+    if (nonEmptyString(a.gitSha))
+        return true;
+    if (nonEmptyString(a.actorType))
+        return true;
+    if (nonEmptyString(a.userId))
+        return true;
+    if (nonEmptyString(a.branchName))
+        return true;
+    if (nonEmptyString(a.agentModel))
+        return true;
+    if (a.agentTraceability && typeof a.agentTraceability === "object") {
+        return Object.keys(a.agentTraceability).some((k) => nonEmptyString(a.agentTraceability[k]) != null);
+    }
+    return false;
+}
+function normalizeActorType(raw) {
+    if (raw == null)
+        return undefined;
+    const s = String(raw).toUpperCase().replace(/-/g, "_");
+    if (s === "CLOUD_AGENT")
+        return "CLOUD_AGENT";
+    if (s === "LOCAL_AGENT")
+        return "LOCAL_AGENT";
+    return undefined;
+}
+/**
+ * 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.
+ * Non-empty nested `agentTraceability` wins over flat for overlapping keys.
+ */
+export function buildAgentTraceabilityPayload(a) {
+    if (!hasExplicitTraceabilityIntent(a)) {
+        return undefined;
+    }
+    const nested = a.agentTraceability &&
+        typeof a.agentTraceability === "object" &&
+        Object.keys(a.agentTraceability).some((k) => nonEmptyString(a.agentTraceability[k]) != null)
+        ? { ...a.agentTraceability }
+        : null;
+    const out = {};
+    const workflowId = nonEmptyString(nested?.workflowId) ?? nonEmptyString(a.workflowId);
+    const workflowExecutionId = nonEmptyString(nested?.workflowExecutionId) ?? nonEmptyString(a.workflowExecutionId);
+    const policyFile = nonEmptyString(nested?.policyFile) ?? nonEmptyString(a.policyFile);
+    const policyVersion = nonEmptyString(nested?.policyVersion) ?? nonEmptyString(a.policyVersion);
+    const gitShaExplicit = nonEmptyString(nested?.gitSha) ?? nonEmptyString(a.gitSha);
+    const actorType = normalizeActorType(nested?.actorType) ?? normalizeActorType(a.actorType);
+    const userId = nonEmptyString(nested?.userId) ??
+        nonEmptyString(a.userId) ??
+        nonEmptyString(process.env.TESTCHIMP_USER_ID);
+    const branchName = nonEmptyString(nested?.branchName) ?? nonEmptyString(a.branchName);
+    const agentModel = nonEmptyString(nested?.agentModel) ??
+        nonEmptyString(a.agentModel) ??
+        nonEmptyString(process.env.TESTCHIMP_AGENT_MODEL);
+    // Server requires workflow_id for inline mutation Activity — do not send orphan payloads.
+    if (!workflowId) {
+        return undefined;
+    }
+    out.workflowId = workflowId;
+    if (workflowExecutionId)
+        out.workflowExecutionId = workflowExecutionId;
+    if (policyFile)
+        out.policyFile = policyFile;
+    if (policyVersion)
+        out.policyVersion = policyVersion;
+    const gitSha = resolveGitHeadSha(gitShaExplicit);
+    if (gitSha)
+        out.gitSha = gitSha;
+    if (actorType)
+        out.actorType = actorType;
+    if (userId)
+        out.userId = userId;
+    if (branchName)
+        out.branchName = branchName;
+    if (agentModel)
+        out.agentModel = agentModel;
+    return out;
+}

package/dist/core/gitSha.d.ts

@@ -0,0 +1,2 @@
+/** Current git HEAD when running in a repo; used when agents omit git_sha on report-agent-action. */
+export declare function resolveGitHeadSha(provided?: string): string | undefined;

package/dist/core/gitSha.js

@@ -0,0 +1,14 @@
+import { execSync } from "node:child_process";
+/** Current git HEAD when running in a repo; used when agents omit git_sha on report-agent-action. */
+export function resolveGitHeadSha(provided) {
+    const trimmed = provided?.trim();
+    if (trimmed) {
+        return trimmed;
+    }
+    try {
+        return execSync("git rev-parse HEAD", { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/schemas.d.ts

@@ -54,22 +54,173 @@ export declare const fetchExecutionReportInput: z.ZodObject<{
     batchInvocationId: z.ZodOptional<z.ZodString>;
     jobId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+export declare const agentActorTypeSchema: z.ZodEnum<{
+    LOCAL_AGENT: "LOCAL_AGENT";
+    CLOUD_AGENT: "CLOUD_AGENT";
+    "local-agent": "local-agent";
+    "cloud-agent": "cloud-agent";
+}>;
+/** Nested AgentActionTraceability (agent_traceability.proto) for mutating MCP CRUDs. */
+export declare const agentActionTraceabilitySchema: z.ZodObject<{
+    workflowId: z.ZodOptional<z.ZodString>;
+    workflowExecutionId: z.ZodOptional<z.ZodString>;
+    policyFile: z.ZodOptional<z.ZodString>;
+    policyVersion: z.ZodOptional<z.ZodString>;
+    gitSha: z.ZodOptional<z.ZodString>;
+    actorType: z.ZodOptional<z.ZodEnum<{
+        LOCAL_AGENT: "LOCAL_AGENT";
+        CLOUD_AGENT: "CLOUD_AGENT";
+        "local-agent": "local-agent";
+        "cloud-agent": "cloud-agent";
+    }>>;
+    userId: z.ZodOptional<z.ZodString>;
+    branchName: z.ZodOptional<z.ZodString>;
+    agentModel: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** Flat + nested traceability fields shared by create/update MCP tools. */
+export declare const agentTraceabilityFieldsSchema: z.ZodObject<{
+    workflowId: z.ZodOptional<z.ZodString>;
+    workflowExecutionId: z.ZodOptional<z.ZodString>;
+    policyFile: z.ZodOptional<z.ZodString>;
+    policyVersion: z.ZodOptional<z.ZodString>;
+    gitSha: z.ZodOptional<z.ZodString>;
+    actorType: z.ZodOptional<z.ZodEnum<{
+        LOCAL_AGENT: "LOCAL_AGENT";
+        CLOUD_AGENT: "CLOUD_AGENT";
+        "local-agent": "local-agent";
+        "cloud-agent": "cloud-agent";
+    }>>;
+    userId: z.ZodOptional<z.ZodString>;
+    branchName: z.ZodOptional<z.ZodString>;
+    agentModel: z.ZodOptional<z.ZodString>;
+    agentTraceability: z.ZodOptional<z.ZodObject<{
+        workflowId: z.ZodOptional<z.ZodString>;
+        workflowExecutionId: z.ZodOptional<z.ZodString>;
+        policyFile: z.ZodOptional<z.ZodString>;
+        policyVersion: z.ZodOptional<z.ZodString>;
+        gitSha: z.ZodOptional<z.ZodString>;
+        actorType: z.ZodOptional<z.ZodEnum<{
+            LOCAL_AGENT: "LOCAL_AGENT";
+            CLOUD_AGENT: "CLOUD_AGENT";
+            "local-agent": "local-agent";
+            "cloud-agent": "cloud-agent";
+        }>>;
+        userId: z.ZodOptional<z.ZodString>;
+        branchName: z.ZodOptional<z.ZodString>;
+        agentModel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
 export declare const createUserStoryInput: z.ZodObject<{
     platformFilePath: z.ZodString;
     title: z.ZodString;
+    workflowId: z.ZodOptional<z.ZodString>;
+    workflowExecutionId: z.ZodOptional<z.ZodString>;
+    policyFile: z.ZodOptional<z.ZodString>;
+    policyVersion: z.ZodOptional<z.ZodString>;
+    gitSha: z.ZodOptional<z.ZodString>;
+    actorType: z.ZodOptional<z.ZodEnum<{
+        LOCAL_AGENT: "LOCAL_AGENT";
+        CLOUD_AGENT: "CLOUD_AGENT";
+        "local-agent": "local-agent";
+        "cloud-agent": "cloud-agent";
+    }>>;
+    userId: z.ZodOptional<z.ZodString>;
+    branchName: z.ZodOptional<z.ZodString>;
+    agentModel: z.ZodOptional<z.ZodString>;
+    agentTraceability: z.ZodOptional<z.ZodObject<{
+        workflowId: z.ZodOptional<z.ZodString>;
+        workflowExecutionId: z.ZodOptional<z.ZodString>;
+        policyFile: z.ZodOptional<z.ZodString>;
+        policyVersion: z.ZodOptional<z.ZodString>;
+        gitSha: z.ZodOptional<z.ZodString>;
+        actorType: z.ZodOptional<z.ZodEnum<{
+            LOCAL_AGENT: "LOCAL_AGENT";
+            CLOUD_AGENT: "CLOUD_AGENT";
+            "local-agent": "local-agent";
+            "cloud-agent": "cloud-agent";
+        }>>;
+        userId: z.ZodOptional<z.ZodString>;
+        branchName: z.ZodOptional<z.ZodString>;
+        agentModel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const createTestScenarioInput: z.ZodObject<{
     platformFilePath: z.ZodString;
     title: z.ZodString;
     userStoryOrdinalId: z.ZodCoercedNumber<unknown>;
+    workflowId: z.ZodOptional<z.ZodString>;
+    workflowExecutionId: z.ZodOptional<z.ZodString>;
+    policyFile: z.ZodOptional<z.ZodString>;
+    policyVersion: z.ZodOptional<z.ZodString>;
+    gitSha: z.ZodOptional<z.ZodString>;
+    actorType: z.ZodOptional<z.ZodEnum<{
+        LOCAL_AGENT: "LOCAL_AGENT";
+        CLOUD_AGENT: "CLOUD_AGENT";
+        "local-agent": "local-agent";
+        "cloud-agent": "cloud-agent";
+    }>>;
+    userId: z.ZodOptional<z.ZodString>;
+    branchName: z.ZodOptional<z.ZodString>;
+    agentModel: z.ZodOptional<z.ZodString>;
+    agentTraceability: z.ZodOptional<z.ZodObject<{
+        workflowId: z.ZodOptional<z.ZodString>;
+        workflowExecutionId: z.ZodOptional<z.ZodString>;
+        policyFile: z.ZodOptional<z.ZodString>;
+        policyVersion: z.ZodOptional<z.ZodString>;
+        gitSha: z.ZodOptional<z.ZodString>;
+        actorType: z.ZodOptional<z.ZodEnum<{
+            LOCAL_AGENT: "LOCAL_AGENT";
+            CLOUD_AGENT: "CLOUD_AGENT";
+            "local-agent": "local-agent";
+            "cloud-agent": "cloud-agent";
+        }>>;
+        userId: z.ZodOptional<z.ZodString>;
+        branchName: z.ZodOptional<z.ZodString>;
+        agentModel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const updatePlanMarkdownInput: z.ZodObject<{
     content: z.ZodString;
+    workflowId: z.ZodOptional<z.ZodString>;
+    workflowExecutionId: z.ZodOptional<z.ZodString>;
+    policyFile: z.ZodOptional<z.ZodString>;
+    policyVersion: z.ZodOptional<z.ZodString>;
+    gitSha: z.ZodOptional<z.ZodString>;
+    actorType: z.ZodOptional<z.ZodEnum<{
+        LOCAL_AGENT: "LOCAL_AGENT";
+        CLOUD_AGENT: "CLOUD_AGENT";
+        "local-agent": "local-agent";
+        "cloud-agent": "cloud-agent";
+    }>>;
+    userId: z.ZodOptional<z.ZodString>;
+    branchName: z.ZodOptional<z.ZodString>;
+    agentModel: z.ZodOptional<z.ZodString>;
+    agentTraceability: z.ZodOptional<z.ZodObject<{
+        workflowId: z.ZodOptional<z.ZodString>;
+        workflowExecutionId: z.ZodOptional<z.ZodString>;
+        policyFile: z.ZodOptional<z.ZodString>;
+        policyVersion: z.ZodOptional<z.ZodString>;
+        gitSha: z.ZodOptional<z.ZodString>;
+        actorType: z.ZodOptional<z.ZodEnum<{
+            LOCAL_AGENT: "LOCAL_AGENT";
+            CLOUD_AGENT: "CLOUD_AGENT";
+            "local-agent": "local-agent";
+            "cloud-agent": "cloud-agent";
+        }>>;
+        userId: z.ZodOptional<z.ZodString>;
+        branchName: z.ZodOptional<z.ZodString>;
+        agentModel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const markPlanItemsImplementationDoneInput: z.ZodObject<{
     scenarioOrdinalIds: z.ZodOptional<z.ZodArray<z.ZodCoercedNumber<unknown>>>;
     userStoryOrdinalIds: z.ZodOptional<z.ZodArray<z.ZodCoercedNumber<unknown>>>;
 }, z.core.$strip>;
+export declare const updatePlanItemsLifecycleStatusInput: z.ZodObject<{
+    entityType: z.ZodString;
+    ordinalId: z.ZodCoercedNumber<unknown>;
+    status: z.ZodString;
+}, z.core.$strip>;
 export declare const getUserStoriesInput: z.ZodObject<{
     userStoryOrdinalIds: z.ZodArray<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
@@ -98,6 +249,36 @@ export declare const updateIssueStatusInput: z.ZodObject<{
         INACCURATE_ASSESSMENT: "INACCURATE_ASSESSMENT";
         NOT_IMPORTANT: "NOT_IMPORTANT";
     }>>;
+    workflowId: z.ZodOptional<z.ZodString>;
+    workflowExecutionId: z.ZodOptional<z.ZodString>;
+    policyFile: z.ZodOptional<z.ZodString>;
+    policyVersion: z.ZodOptional<z.ZodString>;
+    gitSha: z.ZodOptional<z.ZodString>;
+    actorType: z.ZodOptional<z.ZodEnum<{
+        LOCAL_AGENT: "LOCAL_AGENT";
+        CLOUD_AGENT: "CLOUD_AGENT";
+        "local-agent": "local-agent";
+        "cloud-agent": "cloud-agent";
+    }>>;
+    userId: z.ZodOptional<z.ZodString>;
+    branchName: z.ZodOptional<z.ZodString>;
+    agentModel: z.ZodOptional<z.ZodString>;
+    agentTraceability: z.ZodOptional<z.ZodObject<{
+        workflowId: z.ZodOptional<z.ZodString>;
+        workflowExecutionId: z.ZodOptional<z.ZodString>;
+        policyFile: z.ZodOptional<z.ZodString>;
+        policyVersion: z.ZodOptional<z.ZodString>;
+        gitSha: z.ZodOptional<z.ZodString>;
+        actorType: z.ZodOptional<z.ZodEnum<{
+            LOCAL_AGENT: "LOCAL_AGENT";
+            CLOUD_AGENT: "CLOUD_AGENT";
+            "local-agent": "local-agent";
+            "cloud-agent": "cloud-agent";
+        }>>;
+        userId: z.ZodOptional<z.ZodString>;
+        branchName: z.ZodOptional<z.ZodString>;
+        agentModel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const createIssueInput: z.ZodObject<{
     title: z.ZodString;
@@ -164,6 +345,36 @@ export declare const createIssueInput: z.ZodObject<{
     environment: z.ZodOptional<z.ZodString>;
     attachments: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
     artifactReference: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    workflowId: z.ZodOptional<z.ZodString>;
+    workflowExecutionId: z.ZodOptional<z.ZodString>;
+    policyFile: z.ZodOptional<z.ZodString>;
+    policyVersion: z.ZodOptional<z.ZodString>;
+    gitSha: z.ZodOptional<z.ZodString>;
+    actorType: z.ZodOptional<z.ZodEnum<{
+        LOCAL_AGENT: "LOCAL_AGENT";
+        CLOUD_AGENT: "CLOUD_AGENT";
+        "local-agent": "local-agent";
+        "cloud-agent": "cloud-agent";
+    }>>;
+    userId: z.ZodOptional<z.ZodString>;
+    branchName: z.ZodOptional<z.ZodString>;
+    agentModel: z.ZodOptional<z.ZodString>;
+    agentTraceability: z.ZodOptional<z.ZodObject<{
+        workflowId: z.ZodOptional<z.ZodString>;
+        workflowExecutionId: z.ZodOptional<z.ZodString>;
+        policyFile: z.ZodOptional<z.ZodString>;
+        policyVersion: z.ZodOptional<z.ZodString>;
+        gitSha: z.ZodOptional<z.ZodString>;
+        actorType: z.ZodOptional<z.ZodEnum<{
+            LOCAL_AGENT: "LOCAL_AGENT";
+            CLOUD_AGENT: "CLOUD_AGENT";
+            "local-agent": "local-agent";
+            "cloud-agent": "cloud-agent";
+        }>>;
+        userId: z.ZodOptional<z.ZodString>;
+        branchName: z.ZodOptional<z.ZodString>;
+        agentModel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export declare const emptyInput: z.ZodObject<{}, z.core.$strip>;
 export declare const getBranchSpecificEndpointConfigInput: z.ZodObject<{
@@ -730,8 +941,8 @@ export declare const requirementFindingUserStateSchema: z.ZodEnum<{
 }>;
 /** RequirementQualityReportSource — proto enum names. */
 export declare const requirementQualityReportSourceSchema: z.ZodEnum<{
-    CLOUD: "CLOUD";
     LOCAL_AGENT: "LOCAL_AGENT";
+    CLOUD: "CLOUD";
 }>;
 /** SuggestedFixKind — proto enum names. */
 export declare const suggestedFixKindSchema: z.ZodEnum<{
@@ -859,8 +1070,8 @@ export declare const requirementQualityReportSchema: z.ZodObject<{
         title: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     source: z.ZodOptional<z.ZodEnum<{
-        CLOUD: "CLOUD";
         LOCAL_AGENT: "LOCAL_AGENT";
+        CLOUD: "CLOUD";
     }>>;
     metrics: z.ZodOptional<z.ZodObject<{
         overall: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
@@ -944,8 +1155,8 @@ export declare const reportRequirementQualityFindingsInput: z.ZodObject<{
             title: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         source: z.ZodOptional<z.ZodEnum<{
-            CLOUD: "CLOUD";
             LOCAL_AGENT: "LOCAL_AGENT";
+            CLOUD: "CLOUD";
         }>>;
         metrics: z.ZodOptional<z.ZodObject<{
             overall: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
@@ -1015,11 +1226,18 @@ export declare const reportRequirementQualityFindingsInput: z.ZodObject<{
     subjectEntityId: z.ZodOptional<z.ZodString>;
     ordinalId: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
-export declare const agentActorTypeSchema: z.ZodEnum<{
-    LOCAL_AGENT: "LOCAL_AGENT";
-    CLOUD_AGENT: "CLOUD_AGENT";
-    "local-agent": "local-agent";
-    "cloud-agent": "cloud-agent";
+/** Closed vocabulary for report-agent-action entity_type (agent_workflow.proto AgentActionEntityType). */
+export declare const agentActionEntityTypeSchema: z.ZodEnum<{
+    SMART_TEST: "SMART_TEST";
+    SCENARIO: "SCENARIO";
+    ISSUE: "ISSUE";
+    TEST_EXECUTION: "TEST_EXECUTION";
+    USER_STORY: "USER_STORY";
+    POLICY: "POLICY";
+    TEST_INVOCATION_BATCH: "TEST_INVOCATION_BATCH";
+    EXPLORATION: "EXPLORATION";
+    EVENT: "EVENT";
+    WORKFLOW: "WORKFLOW";
 }>;
 export declare const agentActionTypeSchema: z.ZodEnum<{
     failed: "failed";
@@ -1029,6 +1247,7 @@ export declare const agentActionTypeSchema: z.ZodEnum<{
     ANALYZED: "ANALYZED";
     ACTION_COMPLETED: "ACTION_COMPLETED";
     ACTION_FAILED: "ACTION_FAILED";
+    IMPLEMENTED: "IMPLEMENTED";
     created: "created";
     updated: "updated";
     deleted: "deleted";
@@ -1036,6 +1255,7 @@ export declare const agentActionTypeSchema: z.ZodEnum<{
     completed: "completed";
     action_completed: "action_completed";
     action_failed: "action_failed";
+    implemented: "implemented";
 }>;
 export declare const reportAgentActionInput: z.ZodObject<{
     workflowId: z.ZodString;
@@ -1051,7 +1271,35 @@ export declare const reportAgentActionInput: z.ZodObject<{
     }>>;
     userId: z.ZodOptional<z.ZodString>;
     branchName: z.ZodOptional<z.ZodString>;
-    entityType: z.ZodOptional<z.ZodString>;
+    agentModel: z.ZodOptional<z.ZodString>;
+    traceability: z.ZodOptional<z.ZodObject<{
+        workflowId: z.ZodOptional<z.ZodString>;
+        workflowExecutionId: z.ZodOptional<z.ZodString>;
+        policyFile: z.ZodOptional<z.ZodString>;
+        policyVersion: z.ZodOptional<z.ZodString>;
+        gitSha: z.ZodOptional<z.ZodString>;
+        actorType: z.ZodOptional<z.ZodEnum<{
+            LOCAL_AGENT: "LOCAL_AGENT";
+            CLOUD_AGENT: "CLOUD_AGENT";
+            "local-agent": "local-agent";
+            "cloud-agent": "cloud-agent";
+        }>>;
+        userId: z.ZodOptional<z.ZodString>;
+        branchName: z.ZodOptional<z.ZodString>;
+        agentModel: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    entityType: z.ZodEnum<{
+        SMART_TEST: "SMART_TEST";
+        SCENARIO: "SCENARIO";
+        ISSUE: "ISSUE";
+        TEST_EXECUTION: "TEST_EXECUTION";
+        USER_STORY: "USER_STORY";
+        POLICY: "POLICY";
+        TEST_INVOCATION_BATCH: "TEST_INVOCATION_BATCH";
+        EXPLORATION: "EXPLORATION";
+        EVENT: "EVENT";
+        WORKFLOW: "WORKFLOW";
+    }>;
     entityIdentity: z.ZodOptional<z.ZodString>;
     test: z.ZodOptional<z.ZodObject<{
         folderPath: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -1067,6 +1315,7 @@ export declare const reportAgentActionInput: z.ZodObject<{
         ANALYZED: "ANALYZED";
         ACTION_COMPLETED: "ACTION_COMPLETED";
         ACTION_FAILED: "ACTION_FAILED";
+        IMPLEMENTED: "IMPLEMENTED";
         created: "created";
         updated: "updated";
         deleted: "deleted";
@@ -1074,8 +1323,8 @@ export declare const reportAgentActionInput: z.ZodObject<{
         completed: "completed";
         action_completed: "action_completed";
         action_failed: "action_failed";
+        implemented: "implemented";
     }>;
-    detailJson: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const getLastRunWorkflowDetailInput: z.ZodObject<{
     workflowId: z.ZodString;

package/dist/core/schemas.js

@@ -53,22 +53,57 @@ export const fetchExecutionReportInput = z
         });
     }
 });
+export const agentActorTypeSchema = z.enum(["LOCAL_AGENT", "CLOUD_AGENT", "local-agent", "cloud-agent"]);
+/** Nested AgentActionTraceability (agent_traceability.proto) for mutating MCP CRUDs. */
+export const agentActionTraceabilitySchema = z
+    .object({
+    workflowId: z.string().optional(),
+    workflowExecutionId: z.string().optional(),
+    policyFile: z.string().optional(),
+    policyVersion: z.string().optional(),
+    gitSha: z.string().optional(),
+    actorType: agentActorTypeSchema.optional(),
+    userId: z.string().optional(),
+    branchName: z.string().optional(),
+    agentModel: z.string().optional(),
+})
+    .strict();
+/** Flat + nested traceability fields shared by create/update MCP tools. */
+export const agentTraceabilityFieldsSchema = z.object({
+    workflowId: z.string().optional(),
+    workflowExecutionId: z.string().optional(),
+    policyFile: z.string().optional(),
+    policyVersion: z.string().optional(),
+    gitSha: z.string().optional(),
+    actorType: agentActorTypeSchema.optional(),
+    userId: z.string().optional(),
+    branchName: z.string().optional(),
+    agentModel: z.string().optional(),
+    agentTraceability: agentActionTraceabilitySchema.optional(),
+});
 export const createUserStoryInput = z.object({
     platformFilePath: z.string().min(1),
     title: z.string().min(1),
-});
+}).merge(agentTraceabilityFieldsSchema);
 export const createTestScenarioInput = z.object({
     platformFilePath: z.string().min(1),
     title: z.string().min(1),
     userStoryOrdinalId: z.coerce.number().int().positive(),
-});
+}).merge(agentTraceabilityFieldsSchema);
 export const updatePlanMarkdownInput = z.object({
     content: z.string().min(1),
-});
+}).merge(agentTraceabilityFieldsSchema);
 export const markPlanItemsImplementationDoneInput = z.object({
     scenarioOrdinalIds: z.array(z.coerce.number().int().positive()).optional(),
     userStoryOrdinalIds: z.array(z.coerce.number().int().positive()).optional(),
 });
+export const updatePlanItemsLifecycleStatusInput = z.object({
+    /** story | scenario (also accepts user_story / USER_STORY / SCENARIO) */
+    entityType: z.string().min(1),
+    ordinalId: z.coerce.number().int().positive(),
+    /** draft | ready | in progress | blocked | done | archived */
+    status: z.string().min(1),
+});
 export const getUserStoriesInput = z
     .object({
     userStoryOrdinalIds: z.array(z.coerce.number().int().positive()).min(1),
@@ -98,7 +133,7 @@ export const updateIssueStatusInput = z.object({
     ignoreReason: z
         .enum(["INTENDED_BEHAVIOUR", "INACCURATE_ASSESSMENT", "NOT_IMPORTANT"])
         .optional(),
-});
+}).merge(agentTraceabilityFieldsSchema);
 const linkedEntityTypeSchema = z.enum([
     "STORY",
     "SCENARIO",
@@ -164,7 +199,7 @@ export const createIssueInput = z.object({
     environment: z.string().optional(),
     attachments: z.array(z.record(z.string(), z.unknown())).optional(),
     artifactReference: z.record(z.string(), z.unknown()).optional(),
-});
+}).merge(agentTraceabilityFieldsSchema);
 export const emptyInput = z.object({});
 export const getBranchSpecificEndpointConfigInput = z.object({
     branchName: z.string().optional(),
@@ -500,7 +535,19 @@ export const reportRequirementQualityFindingsInput = z
         });
     }
 });
-export const agentActorTypeSchema = z.enum(["LOCAL_AGENT", "CLOUD_AGENT", "local-agent", "cloud-agent"]);
+/** Closed vocabulary for report-agent-action entity_type (agent_workflow.proto AgentActionEntityType). */
+export const agentActionEntityTypeSchema = z.enum([
+    "USER_STORY",
+    "SCENARIO",
+    "SMART_TEST",
+    "POLICY",
+    "ISSUE",
+    "TEST_EXECUTION",
+    "TEST_INVOCATION_BATCH",
+    "EXPLORATION",
+    "EVENT",
+    "WORKFLOW",
+]);
 export const agentActionTypeSchema = z.enum([
     "CREATED",
     "UPDATED",
@@ -508,6 +555,7 @@ export const agentActionTypeSchema = z.enum([
     "ANALYZED",
     "ACTION_COMPLETED",
     "ACTION_FAILED",
+    "IMPLEMENTED",
     "created",
     "updated",
     "deleted",
@@ -516,6 +564,7 @@ export const agentActionTypeSchema = z.enum([
     "failed",
     "action_completed",
     "action_failed",
+    "implemented",
 ]);
 export const reportAgentActionInput = z
     .object({
@@ -527,20 +576,85 @@ export const reportAgentActionInput = z
     actorType: agentActorTypeSchema.optional(),
     userId: z.string().optional(),
     branchName: z.string().optional(),
-    entityType: z.string().optional(),
+    agentModel: z.string().optional(),
+    traceability: agentActionTraceabilitySchema.optional(),
+    entityType: agentActionEntityTypeSchema,
     /** Project-scoped ordinal id (or explicitly provided execution/batch id). Mutually exclusive with `test`. */
     entityIdentity: z.string().optional(),
     /** SmartTest TestLocator. Mutually exclusive with `entityIdentity`. */
     test: testLocatorSchema.optional(),
     actionType: agentActionTypeSchema,
-    detailJson: z.string().optional(),
 })
     .superRefine((val, ctx) => {
-    if (val.test && val.entityIdentity) {
+    const actionNorm = val.actionType.toString().toUpperCase().replace(/-/g, "_");
+    const isCompletion = actionNorm === "ACTION_COMPLETED" ||
+        actionNorm === "ACTION_FAILED" ||
+        actionNorm === "COMPLETED" ||
+        actionNorm === "FAILED";
+    if (isCompletion) {
+        if (val.entityType !== "WORKFLOW") {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "ACTION_COMPLETED / ACTION_FAILED require entityType WORKFLOW",
+                path: ["entityType"],
+            });
+        }
+        const identity = (val.entityIdentity ?? "").trim();
+        if (identity === "" || identity !== val.workflowId.trim()) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "entityIdentity must equal workflowId for WORKFLOW completion",
+                path: ["entityIdentity"],
+            });
+        }
+        if (val.test) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "test must not be set for WORKFLOW completion",
+                path: ["test"],
+            });
+        }
+        return;
+    }
+    if (val.entityType === "WORKFLOW") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "WORKFLOW entityType is only valid with ACTION_COMPLETED / ACTION_FAILED",
+            path: ["entityType"],
+        });
+        return;
+    }
+    if (actionNorm === "IMPLEMENTED" &&
+        val.entityType !== "USER_STORY" &&
+        val.entityType !== "SCENARIO") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "IMPLEMENTED is only valid for USER_STORY or SCENARIO",
+            path: ["entityType"],
+        });
+    }
+    if (val.entityType === "SMART_TEST") {
+        if (!val.test) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "SMART_TEST requires test (TestLocator)",
+                path: ["test"],
+            });
+        }
+        if (val.entityIdentity != null && val.entityIdentity.trim() !== "") {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "SMART_TEST forbids entityIdentity; use test (TestLocator)",
+                path: ["entityIdentity"],
+            });
+        }
+        return;
+    }
+    if (!(val.entityIdentity ?? "").trim()) {
         ctx.addIssue({
             code: z.ZodIssueCode.custom,
-            message: "Provide either test (TestLocator) or entityIdentity (ordinal), not both",
-            path: ["test"],
+            message: `entityIdentity is required for ${val.entityType}`,
+            path: ["entityIdentity"],
         });
     }
 });

package/dist/core/tools.js

@@ -1,6 +1,8 @@
 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";
 function platformToProtoEnum(platform) {
     switch (platform) {
         case "ios":
@@ -166,14 +168,20 @@ export const TOOL_DEFINITIONS = [
             "Response includes content: canonical stub markdown already containing id: US-<ordinalId>. " +
             "BLOCKING workflow: call this FIRST → Write the returned content to the repo plans/stories path " +
             "(edit body as needed but keep id:) → call update-user-story with the full markdown. " +
-            "Never write story markdown that omits id. platformFilePath must be under plans/stories/ and end with .md.",
+            "Never write story markdown that omits id. platformFilePath must be under plans/stories/ and end with .md. " +
+            "Optional agentTraceability (or flat workflowId/workflowExecutionId/policyFile/policyVersion/gitSha/…) " +
+            "records AGENT_WORKFLOW_ACTIVITY inline — no separate report-agent-action needed for this create.",
         inputSchema: S.createUserStoryInput,
         execute: async (args, { postMcp }) => {
             const a = args;
-            return postMcp("/api/mcp/create_user_story", {
+            const body = {
                 platformFilePath: a.platformFilePath,
                 title: a.title,
-            });
+            };
+            const trace = buildAgentTraceabilityPayload(a);
+            if (trace)
+                body.agentTraceability = trace;
+            return postMcp("/api/mcp/create_user_story", body);
         },
     },
     {
@@ -184,37 +192,52 @@ export const TOOL_DEFINITIONS = [
             "(edit body as needed but keep id: and story:) → call update-test-scenario with the full markdown. " +
             "Never write scenario markdown that omits id. update-test-scenario rejects missing id/story with a clear error. " +
             "platformFilePath must be under plans/scenarios/ and end with .md. " +
-            "userStoryOrdinalId is the numeric part of the parent US-<n> id.",
+            "userStoryOrdinalId is the numeric part of the parent US-<n> id. " +
+            "Optional agentTraceability records Activity inline (no separate report-agent-action for this create).",
         inputSchema: S.createTestScenarioInput,
         execute: async (args, { postMcp }) => {
             const a = args;
-            return postMcp("/api/mcp/create_test_scenario", {
+            const body = {
                 platformFilePath: a.platformFilePath,
                 title: a.title,
                 userStoryOrdinalId: a.userStoryOrdinalId,
-            });
+            };
+            const trace = buildAgentTraceabilityPayload(a);
+            if (trace)
+                body.agentTraceability = trace;
+            return postMcp("/api/mcp/create_test_scenario", body);
         },
     },
     {
         kebab: "update-user-story",
         description: "Sync a user story markdown file to the platform after local edits. " +
             "Requires frontmatter id: US-<n> (platform-issued). Missing id returns an error telling you to call create-user-story first. " +
-            "Parses frontmatter (id, title, priority) and updates the linked support file and entity.",
+            "Parses frontmatter (id, title, priority) and updates the linked support file and entity. " +
+            "Optional agentTraceability records UPDATED Activity inline.",
         inputSchema: S.updatePlanMarkdownInput,
         execute: async (args, { postMcp }) => {
             const a = args;
-            return postMcp("/api/mcp/update_user_story", { content: a.content });
+            const body = { content: a.content };
+            const trace = buildAgentTraceabilityPayload(a);
+            if (trace)
+                body.agentTraceability = trace;
+            return postMcp("/api/mcp/update_user_story", body);
         },
     },
     {
         kebab: "update-test-scenario",
         description: "Sync a test scenario markdown file to the platform after local edits. " +
             "Requires frontmatter id: TS-<n> and story: US-<n>. Missing either returns an error telling you to call create-test-scenario first. " +
-            "Parses frontmatter and updates linking if story changes.",
+            "Parses frontmatter and updates linking if story changes. " +
+            "Optional agentTraceability records UPDATED Activity inline.",
         inputSchema: S.updatePlanMarkdownInput,
         execute: async (args, { postMcp }) => {
             const a = args;
-            return postMcp("/api/mcp/update_test_scenario", { content: a.content });
+            const body = { content: a.content };
+            const trace = buildAgentTraceabilityPayload(a);
+            if (trace)
+                body.agentTraceability = trace;
+            return postMcp("/api/mcp/update_test_scenario", body);
         },
     },
     {
@@ -274,7 +297,8 @@ export const TOOL_DEFINITIONS = [
         description: "Update a TestChimp issue status by ordinal id (same flexible issueId formats as get-issue-details). " +
             "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 ignoreReason when status is IGNORED: INTENDED_BEHAVIOUR | INACCURATE_ASSESSMENT | NOT_IMPORTANT. " +
+            "Optional agentTraceability records UPDATED Activity inline.",
         inputSchema: S.updateIssueStatusInput,
         execute: async (args, { postMcp }) => {
             const a = args;
@@ -284,6 +308,9 @@ export const TOOL_DEFINITIONS = [
             };
             if (a.ignoreReason)
                 body.ignoreReason = a.ignoreReason;
+            const trace = buildAgentTraceabilityPayload(a);
+            if (trace)
+                body.agentTraceability = trace;
             return postMcp("/api/mcp/update_issue_status", body);
         },
     },
@@ -293,6 +320,8 @@ export const TOOL_DEFINITIONS = [
             "Use simple fields for common creates, or pass the full curated contract via --json-input " +
             "(description, issueType, category, severity, status, reportedReleaseId, dueDateMillis, assignee, " +
             "linkTargets, labels, source, environment, attachments, artifactReference). " +
+            "Optional agentTraceability (or flat workflowId/policyFile/…) records CREATED Activity inline — " +
+            "prefer this over a separate report-agent-action for issue creates. " +
             "Authenticated via project API key; project is resolved from the key.",
         inputSchema: S.createIssueInput,
         execute: async (args, { postMcp }) => {
@@ -326,6 +355,9 @@ export const TOOL_DEFINITIONS = [
                 body.attachments = a.attachments;
             if (a.artifactReference != null)
                 body.artifactReference = a.artifactReference;
+            const trace = buildAgentTraceabilityPayload(a);
+            if (trace)
+                body.agentTraceability = trace;
             return postMcp("/api/mcp/create_issue", body);
         },
     },
@@ -344,6 +376,21 @@ export const TOOL_DEFINITIONS = [
             return postMcp("/api/mcp/mark_plan_items_implementation_done", body);
         },
     },
+    {
+        kebab: "update-plan-items-lifecycle-status",
+        description: "Update lifecycle_fields.status for one user story or test scenario (DB only; does not rewrite plan markdown). " +
+            "entityType: story | scenario; ordinalId: numeric US-/TS- ordinal; status: draft | ready | in progress | blocked | done | archived. " +
+            "Used after /testchimp implement to set status to ready (unless policy overrides).",
+        inputSchema: S.updatePlanItemsLifecycleStatusInput,
+        execute: async (args, { postMcp }) => {
+            const a = args;
+            return postMcp("/api/mcp/update_plan_items_lifecycle_status", {
+                entityType: a.entityType,
+                ordinalId: a.ordinalId,
+                status: a.status,
+            });
+        },
+    },
     {
         kebab: "get-eaas-config",
         description: "Return the project's BunnyShell (Environment-as-a-Service) settings. Secrets are never returned.",
@@ -779,10 +826,15 @@ export const TOOL_DEFINITIONS = [
     {
         kebab: "report-agent-action",
         description: "Report a mutating agent action under a stable workflow-execution-id (ULID). " +
-            "First call for an id creates the workflow_executions row; later calls append agent_actions. " +
-            "Identity: pass `test` (TestLocator: folderPath/fileName/testSuite/testName) for SmartTests, " +
-            "or `entityIdentity` as a project-scoped ordinal id for stories/scenarios/issues " +
-            "(or an execution/batch id only when the prompt explicitly provided it). Do not use platform UUIDs.",
+            "First call for an id creates the workflow_executions row; later calls append Activity " +
+            "timeline rows (AGENT_WORKFLOW_ACTIVITY). " +
+            "Actions land on the entity's Activity timeline (plans, issues, SmartTest file). " +
+            "entityType: USER_STORY | SCENARIO | SMART_TEST | POLICY | ISSUE | TEST_EXECUTION | " +
+            "TEST_INVOCATION_BATCH | EXPLORATION | EVENT | WORKFLOW. " +
+            "actionType: CREATED | UPDATED | DELETED | ANALYZED | IMPLEMENTED | ACTION_COMPLETED | ACTION_FAILED. " +
+            "Identity: SMART_TEST uses `test` (TestLocator: folderPath/fileName/testSuite/testName); " +
+            "other artifact types use `entityIdentity` (ordinal / filename / opaque id). Do not use platform UUIDs. " +
+            "Completion (ACTION_COMPLETED / ACTION_FAILED): entityType WORKFLOW and entityIdentity = catalog workflow_id.",
         inputSchema: S.reportAgentActionInput,
         execute: async (args, { postMcp }) => {
             const a = args;
@@ -801,29 +853,48 @@ export const TOOL_DEFINITIONS = [
                 workflowExecutionId: a.workflowExecutionId,
                 actionType,
                 actorType,
+                entityType: a.entityType,
             };
             if (a.policyFile)
                 body.policyFile = a.policyFile;
             if (a.policyVersion)
                 body.policyVersion = a.policyVersion;
-            if (a.gitSha)
-                body.gitSha = a.gitSha;
+            const gitSha = resolveGitHeadSha(a.gitSha);
+            if (gitSha)
+                body.gitSha = gitSha;
             if (a.userId)
                 body.userId = a.userId;
             else if (process.env.TESTCHIMP_USER_ID)
                 body.userId = process.env.TESTCHIMP_USER_ID;
             if (a.branchName)
                 body.branchName = a.branchName;
-            if (a.entityType)
-                body.entityType = a.entityType;
+            // Nested traceability wins for agentModel; only fill from flat/env when nested omits it.
+            if (a.traceability && typeof a.traceability === "object") {
+                const nested = { ...a.traceability };
+                const nestedModel = nested.agentModel != null && String(nested.agentModel).trim() !== ""
+                    ? String(nested.agentModel).trim()
+                    : undefined;
+                const flatModel = a.agentModel?.trim() || process.env.TESTCHIMP_AGENT_MODEL?.trim();
+                if (nestedModel) {
+                    nested.agentModel = nestedModel;
+                }
+                else if (flatModel) {
+                    nested.agentModel = flatModel;
+                }
+                body.traceability = nested;
+            }
+            else {
+                const model = a.agentModel?.trim() || process.env.TESTCHIMP_AGENT_MODEL?.trim();
+                if (model) {
+                    body.traceability = { agentModel: model };
+                }
+            }
             if (a.test) {
                 body.test = a.test;
             }
             else if (a.entityIdentity) {
                 body.entityIdentity = a.entityIdentity;
             }
-            if (a.detailJson)
-                body.detailJson = a.detailJson;
             return postMcp("/api/mcp/report_agent_action", body);
         },
     },

package/package.json

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