@workflow-cannon/workspace-kit 0.10.0 → 0.12.0

package/README.md

@@ -65,6 +65,9 @@ This keeps automation adaptive without sacrificing safety, governance, or develo
 
 - **Phases 0–7** are complete through **`v0.9.0`** (see roadmap for slice ids).
 - **Phase 8** ships maintainer/onboarding hardening (`v0.10.0`): policy denial clarity, runbooks, and doc alignment for CLI vs `run` approval.
+- **Phase 9–10** ship agent/onboarding parity (`v0.11.0`): interactive policy opt-in, strict response-template mode, Agent CLI map (`docs/maintainers/AGENT-CLI-MAP.md`), and CLI-first Cursor guidance.
+- **Phase 11** ships architectural review follow-up hardening (`v0.12.0`): policy/session denial edge tests, persistence concurrency semantics, release doc-sweep checklist, and runtime path audit note.
+- **Phase 12** is the active queue: Cursor-native thin-client extension delivery (`T296`–`T310`).
 
 Historical note: this file’s milestone list is not the live queue—always check task state for **`ready`** work.
 

package/dist/cli/interactive-policy.d.ts

@@ -0,0 +1,16 @@
+export type PolicyPromptIo = {
+    writeError: (message: string) => void;
+    readStdinLine?: () => Promise<string | null>;
+};
+/** Enable TTY interactive approval for sensitive `workspace-kit run` when truthy (`on`, `1`, `true`, `yes`). */
+export declare function isInteractiveApprovalEnabled(env: NodeJS.ProcessEnv): boolean;
+export type InteractiveApprovalChoice = {
+    kind: "deny";
+} | {
+    kind: "approve";
+    scope: "once" | "session";
+};
+/**
+ * Prompt for Deny / Allow once / Allow for session. Returns deny if user cancels or input unrecognized.
+ */
+export declare function promptSensitiveRunApproval(io: PolicyPromptIo, operationId: string, commandLabel: string, env: NodeJS.ProcessEnv): Promise<InteractiveApprovalChoice | null>;

package/dist/cli/interactive-policy.js

@@ -0,0 +1,53 @@
+import { createInterface } from "node:readline/promises";
+/** Enable TTY interactive approval for sensitive `workspace-kit run` when truthy (`on`, `1`, `true`, `yes`). */
+export function isInteractiveApprovalEnabled(env) {
+    const v = env.WORKSPACE_KIT_INTERACTIVE_APPROVAL?.trim().toLowerCase();
+    return v === "1" || v === "true" || v === "on" || v === "yes";
+}
+function canUseInteractivePrompt(io) {
+    if (io.readStdinLine) {
+        return true;
+    }
+    return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+async function readOneLine(io) {
+    if (io.readStdinLine) {
+        return io.readStdinLine();
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const line = await rl.question("");
+        return line;
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * Prompt for Deny / Allow once / Allow for session. Returns deny if user cancels or input unrecognized.
+ */
+export async function promptSensitiveRunApproval(io, operationId, commandLabel, env) {
+    if (!isInteractiveApprovalEnabled(env) || !canUseInteractivePrompt(io)) {
+        return null;
+    }
+    const session = env.WORKSPACE_KIT_SESSION_ID?.trim() || "default";
+    io.writeError(`workspace-kit: sensitive command '${commandLabel}' requires approval (${operationId}).\n` +
+        `  [d] Deny   [o] Allow once   [s] Allow for this session (WORKSPACE_KIT_SESSION_ID=${session})\n` +
+        `Choice (d/o/s): `);
+    const raw = await readOneLine(io);
+    if (raw === null) {
+        return { kind: "deny" };
+    }
+    const c = raw.trim().toLowerCase();
+    if (c === "d" || c === "deny" || c === "n" || c === "no") {
+        return { kind: "deny" };
+    }
+    if (c === "o" || c === "once" || c === "1" || c === "y" || c === "yes" || c === "a") {
+        return { kind: "approve", scope: "once" };
+    }
+    if (c === "s" || c === "session" || c === "2") {
+        return { kind: "approve", scope: "session" };
+    }
+    io.writeError(`Unrecognized choice '${raw.trim()}'; treating as deny.\n`);
+    return { kind: "deny" };
+}

package/dist/cli/run-command.d.ts

@@ -1,6 +1,8 @@
 export type RunCommandIo = {
     writeLine: (message: string) => void;
     writeError: (message: string) => void;
+    /** Test hook: return one line of simulated stdin for interactive policy approval */
+    readStdinLine?: () => Promise<string | null>;
 };
 export type RunCommandExitCodes = {
     success: number;

package/dist/cli/run-command.js

@@ -1,6 +1,6 @@
 import { ModuleRegistry } from "../core/module-registry.js";
 import { ModuleCommandRouter } from "../core/module-command-router.js";
-import { appendPolicyTrace, isSensitiveModuleCommandForEffective, parsePolicyApproval, POLICY_APPROVAL_HUMAN_DOC, resolveActorWithFallback, resolvePolicyOperationIdForCommand } from "../core/policy.js";
+import { appendPolicyTrace, isSensitiveModuleCommandForEffective, parsePolicyApproval, AGENT_CLI_MAP_HUMAN_DOC, POLICY_APPROVAL_HUMAN_DOC, resolveActorWithFallback, resolvePolicyOperationIdForCommand } from "../core/policy.js";
 import { getSessionGrant, recordSessionGrant, resolveSessionId } from "../core/session-policy.js";
 import { applyResponseTemplateApplication } from "../core/response-template-shaping.js";
 import { resolveWorkspaceConfigWithLayers } from "../core/workspace-kit-config.js";
@@ -10,6 +10,7 @@ import { approvalsModule } from "../modules/approvals/index.js";
 import { planningModule } from "../modules/planning/index.js";
 import { improvementModule } from "../modules/improvement/index.js";
 import { workspaceConfigModule } from "../modules/workspace-config/index.js";
+import { promptSensitiveRunApproval } from "./interactive-policy.js";
 export async function handleRunCommand(cwd, args, io, codes) {
     const { writeLine, writeError } = io;
     const allModules = [
@@ -31,7 +32,9 @@ export async function handleRunCommand(cwd, args, io, codes) {
             writeLine(`  ${cmd.name} (${cmd.moduleId})${desc}`);
         }
         writeLine("");
-        writeLine("Usage: workspace-kit run <command> [json-args]");
+        writeLine(`Usage: workspace-kit run <command> [json-args]`);
+        writeLine(`Instruction files: src/modules/<module>/instructions/<command>.md — policy-sensitive runs need JSON policyApproval (${POLICY_APPROVAL_HUMAN_DOC}).`);
+        writeLine(`Agent-oriented tier table + copy-paste patterns: ${AGENT_CLI_MAP_HUMAN_DOC}.`);
         return codes.success;
     }
     let commandArgs = {};
@@ -75,7 +78,9 @@ export async function handleRunCommand(cwd, args, io, codes) {
     const sessionId = resolveSessionId(process.env);
     const policyOp = resolvePolicyOperationIdForCommand(subcommand, effective);
     const explicitPolicyApproval = parsePolicyApproval(commandArgs);
+    const hasPolicyApprovalField = Object.hasOwn(commandArgs, "policyApproval");
     let resolvedSensitiveApproval = explicitPolicyApproval;
+    let interactiveSessionFollowup = false;
     if (sensitive) {
         if (!resolvedSensitiveApproval && policyOp) {
             const grant = await getSessionGrant(cwd, policyOp, sessionId);
@@ -83,6 +88,37 @@ export async function handleRunCommand(cwd, args, io, codes) {
                 resolvedSensitiveApproval = { confirmed: true, rationale: grant.rationale };
             }
         }
+        if (!resolvedSensitiveApproval && policyOp) {
+            const interactive = await promptSensitiveRunApproval({ writeError, readStdinLine: io.readStdinLine }, policyOp, `run ${subcommand}`, process.env);
+            if (interactive?.kind === "deny") {
+                await appendPolicyTrace(cwd, {
+                    timestamp: new Date().toISOString(),
+                    operationId: policyOp,
+                    command: `run ${subcommand}`,
+                    actor,
+                    allowed: false,
+                    message: "interactive policy approval denied"
+                });
+                writeLine(JSON.stringify({
+                    ok: false,
+                    code: "policy-denied",
+                    operationId: policyOp,
+                    remediationDoc: POLICY_APPROVAL_HUMAN_DOC,
+                    message: "Sensitive command denied at interactive policy prompt.",
+                    hint: `Set WORKSPACE_KIT_INTERACTIVE_APPROVAL=off or pass policyApproval in JSON. See ${POLICY_APPROVAL_HUMAN_DOC}.`
+                }, null, 2));
+                return codes.validationFailure;
+            }
+            if (interactive?.kind === "approve") {
+                const rationale = interactive.scope === "session" ? "interactive-approval-session" : "interactive-approval-once";
+                resolvedSensitiveApproval = {
+                    confirmed: true,
+                    rationale,
+                    ...(interactive.scope === "session" ? { scope: "session" } : {})
+                };
+                interactiveSessionFollowup = interactive.scope === "session";
+            }
+        }
         if (!resolvedSensitiveApproval) {
             if (policyOp) {
                 await appendPolicyTrace(cwd, {
@@ -91,7 +127,9 @@ export async function handleRunCommand(cwd, args, io, codes) {
                     command: `run ${subcommand}`,
                     actor,
                     allowed: false,
-                    message: "missing policyApproval in JSON args"
+                    message: hasPolicyApprovalField
+                        ? "invalid policyApproval in JSON args"
+                        : "missing policyApproval in JSON args"
                 });
             }
             writeLine(JSON.stringify({
@@ -99,9 +137,11 @@ export async function handleRunCommand(cwd, args, io, codes) {
                 code: "policy-denied",
                 operationId: policyOp ?? null,
                 remediationDoc: POLICY_APPROVAL_HUMAN_DOC,
-                message: 'Sensitive command requires policyApproval in JSON args (or an existing session grant for this operation). Example: {"policyApproval":{"confirmed":true,"rationale":"why","scope":"session"}}. See remediationDoc for env vs JSON approval surfaces.',
+                message: hasPolicyApprovalField
+                    ? 'Sensitive command received an invalid policyApproval object. Use {"policyApproval":{"confirmed":true,"rationale":"why","scope":"session"}} (scope optional) or use an existing session grant for this operation.'
+                    : 'Sensitive command requires policyApproval in JSON args (or an existing session grant for this operation). Example: {"policyApproval":{"confirmed":true,"rationale":"why","scope":"session"}}. See remediationDoc for env vs JSON approval surfaces.',
                 hint: policyOp != null
-                    ? `Operation ${policyOp} requires explicit approval; WORKSPACE_KIT_POLICY_APPROVAL is not read for workspace-kit run.`
+                    ? `Operation ${policyOp} requires explicit approval; WORKSPACE_KIT_POLICY_APPROVAL is not read for workspace-kit run. Optional: set WORKSPACE_KIT_INTERACTIVE_APPROVAL=on in a TTY for a prompt (see ${POLICY_APPROVAL_HUMAN_DOC}).`
                     : "Operation could not be mapped to policyOperationId; check policy.extraSensitiveModuleCommands and pass policyApproval in JSON args."
             }, null, 2));
             return codes.validationFailure;
@@ -127,8 +167,10 @@ export async function handleRunCommand(cwd, args, io, codes) {
                 commandOk: rawResult.ok,
                 message: rawResult.message
             });
-            if (explicitPolicyApproval?.scope === "session" && rawResult.ok) {
-                await recordSessionGrant(cwd, policyOp, sessionId, explicitPolicyApproval.rationale);
+            const recordSession = rawResult.ok &&
+                (explicitPolicyApproval?.scope === "session" || interactiveSessionFollowup);
+            if (recordSession) {
+                await recordSessionGrant(cwd, policyOp, sessionId, resolvedSensitiveApproval.rationale);
             }
         }
         const result = applyResponseTemplateApplication(subcommand, commandArgs, rawResult, effective);

package/dist/cli.d.ts

@@ -9,6 +9,8 @@ export type WorkspaceKitCliOptions = {
     cwd?: string;
     writeLine?: (message: string) => void;
     writeError?: (message: string) => void;
+    /** Test hook: simulated stdin lines for interactive sensitive-command approval */
+    readStdinLine?: () => Promise<string | null>;
 };
 export declare function parseJsonFile(filePath: string): Promise<unknown>;
 export declare function runCli(args: string[], options?: WorkspaceKitCliOptions): Promise<number>;

package/dist/cli.js

@@ -2,7 +2,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { appendPolicyTrace, parsePolicyApprovalFromEnv, resolveActorWithFallback } from "./core/policy.js";
+import { AGENT_CLI_MAP_HUMAN_DOC, appendPolicyTrace, parsePolicyApprovalFromEnv, resolveActorWithFallback } from "./core/policy.js";
 import { runWorkspaceConfigCli } from "./core/config-cli.js";
 import { handleRunCommand } from "./cli/run-command.js";
 const EXIT_SUCCESS = 0;
@@ -335,6 +335,7 @@ export async function runCli(args, options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const writeLine = options.writeLine ?? console.log;
     const writeError = options.writeError ?? console.error;
+    const readStdinLine = options.readStdinLine;
     const [command] = args;
     if (!command) {
         writeError("Usage: workspace-kit <init|doctor|check|upgrade|drift-check|run|config>");
@@ -571,7 +572,7 @@ export async function runCli(args, options = {}) {
         return EXIT_SUCCESS;
     }
     if (command === "run") {
-        return handleRunCommand(cwd, args, { writeLine, writeError }, {
+        return handleRunCommand(cwd, args, { writeLine, writeError, readStdinLine }, {
             success: EXIT_SUCCESS,
             validationFailure: EXIT_VALIDATION_FAILURE,
             usageError: EXIT_USAGE_ERROR,
@@ -614,6 +615,7 @@ export async function runCli(args, options = {}) {
     }
     writeLine("workspace-kit doctor passed.");
     writeLine("All canonical workspace-kit contract files are present and parseable JSON.");
+    writeLine(`Next: workspace-kit run — list module commands; see ${AGENT_CLI_MAP_HUMAN_DOC} for tier/policy copy-paste.`);
     return EXIT_SUCCESS;
 }
 async function main() {

package/dist/core/config-metadata.js

@@ -163,7 +163,7 @@ const REGISTRY = {
     "responseTemplates.enforcementMode": {
         key: "responseTemplates.enforcementMode",
         type: "string",
-        description: "Whether unknown/mismatched response templates fail commands (`strict`) or only emit warnings (`advisory`).",
+        description: "`advisory`: unknown template ids, invalid default/override ids, and explicit-vs-directive template conflicts emit warnings only. `strict`: same conditions fail the command (`response-template-invalid` or `response-template-conflict`) after the module runs; use for CI governance.",
         default: "advisory",
         allowedValues: ["advisory", "strict"],
         domainScope: "project",

package/dist/core/module-registry.d.ts

@@ -3,7 +3,7 @@ export declare class ModuleRegistryError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
 }
-export declare function validateModuleSet(modules: WorkflowModule[]): void;
+export declare function validateModuleSet(modules: WorkflowModule[], workspacePath?: string): void;
 export type ModuleRegistryOptions = {
     enabledModules?: string[];
     disabledModules?: string[];

package/dist/core/module-registry.js

@@ -142,10 +142,10 @@ function validateInstructionContracts(moduleMap, workspacePath) {
         }
     }
 }
-export function validateModuleSet(modules) {
+export function validateModuleSet(modules, workspacePath) {
     const moduleMap = buildModuleMap(modules);
     validateDependencies(moduleMap);
-    validateInstructionContracts(moduleMap, process.cwd());
+    validateInstructionContracts(moduleMap, workspacePath ?? process.cwd());
     topologicalSort(moduleMap);
 }
 export class ModuleRegistry {

package/dist/core/policy.d.ts

@@ -1,6 +1,8 @@
 export declare const POLICY_TRACE_SCHEMA_VERSION: 1;
 /** Maintainer doc (repo-relative) linked from policy denial output for `workspace-kit run`. */
 export declare const POLICY_APPROVAL_HUMAN_DOC = "docs/maintainers/POLICY-APPROVAL.md";
+/** Maintainer doc: tier table + copy-paste patterns for agents (Tier A/B `run` vs CLI env approval). */
+export declare const AGENT_CLI_MAP_HUMAN_DOC = "docs/maintainers/AGENT-CLI-MAP.md";
 export type PolicyOperationId = "cli.upgrade" | "cli.init" | "cli.config-mutate" | "policy.dynamic-sensitive" | "doc.document-project" | "doc.generate-document" | "tasks.run-transition" | "approvals.review-item" | "improvement.generate-recommendations" | "improvement.ingest-transcripts";
 export declare function getOperationIdForCommand(commandName: string): PolicyOperationId | undefined;
 export declare function getExtraSensitiveModuleCommandsFromEffective(effective: Record<string, unknown>): string[];

package/dist/core/policy.js

@@ -4,6 +4,8 @@ import { execFile } from "node:child_process";
 export const POLICY_TRACE_SCHEMA_VERSION = 1;
 /** Maintainer doc (repo-relative) linked from policy denial output for `workspace-kit run`. */
 export const POLICY_APPROVAL_HUMAN_DOC = "docs/maintainers/POLICY-APPROVAL.md";
+/** Maintainer doc: tier table + copy-paste patterns for agents (Tier A/B `run` vs CLI env approval). */
+export const AGENT_CLI_MAP_HUMAN_DOC = "docs/maintainers/AGENT-CLI-MAP.md";
 const COMMAND_TO_OPERATION = {
     "document-project": "doc.document-project",
     "generate-document": "doc.generate-document",

package/dist/core/response-template-shaping.d.ts

@@ -1,6 +1,7 @@
 import type { ModuleCommandResult } from "../contracts/module-contract.js";
 /**
  * Apply response template metadata and optional presentation hints (T262, T265).
- * Advisory mode never flips `ok`. Strict mode fails closed on unknown template ids when a template was explicitly requested or command override is set.
+ * Advisory mode never flips `ok` for template issues. Strict mode fails closed on unknown resolved template ids
+ * (explicit, override, or default) and on explicit-vs-directive conflicts (`response-template-conflict`).
  */
 export declare function applyResponseTemplateApplication(commandName: string, args: Record<string, unknown>, result: ModuleCommandResult, effective: Record<string, unknown>): ModuleCommandResult;

package/dist/core/response-template-shaping.js

@@ -24,6 +24,7 @@ function readResponseTemplatesConfig(effective) {
 }
 function resolveRequestedTemplateId(commandName, args) {
     const parseWarnings = [];
+    const strictViolations = [];
     const explicit = typeof args.responseTemplateId === "string" && args.responseTemplateId.trim()
         ? args.responseTemplateId.trim()
         : null;
@@ -43,12 +44,13 @@ function resolveRequestedTemplateId(commandName, args) {
     }
     if (explicit && fromText && explicit !== fromText) {
         parseWarnings.push(truncateTemplateWarning(`responseTemplateId '${explicit}' disagrees with instruction directive '${fromText}'; using explicit id.`));
+        strictViolations.push(truncateTemplateWarning(`In strict mode, responseTemplateId '${explicit}' conflicts with instruction directive '${fromText}'.`));
     }
     if (explicit)
-        return { templateId: explicit, parseWarnings };
+        return { templateId: explicit, parseWarnings, strictViolations };
     if (fromText)
-        return { templateId: fromText, parseWarnings };
-    return { templateId: null, parseWarnings };
+        return { templateId: fromText, parseWarnings, strictViolations };
+    return { templateId: null, parseWarnings, strictViolations };
 }
 function attachPresentation(templateId, result) {
     const def = getResponseTemplateDefinition(templateId);
@@ -74,27 +76,42 @@ function buildMeta(partial, startNs) {
 }
 /**
  * Apply response template metadata and optional presentation hints (T262, T265).
- * Advisory mode never flips `ok`. Strict mode fails closed on unknown template ids when a template was explicitly requested or command override is set.
+ * Advisory mode never flips `ok` for template issues. Strict mode fails closed on unknown resolved template ids
+ * (explicit, override, or default) and on explicit-vs-directive conflicts (`response-template-conflict`).
  */
 export function applyResponseTemplateApplication(commandName, args, result, effective) {
     const startNs = process.hrtime.bigint();
     const cfg = readResponseTemplatesConfig(effective);
-    const { templateId: requestedRaw, parseWarnings } = resolveRequestedTemplateId(commandName, args);
+    const { templateId: requestedRaw, parseWarnings, strictViolations } = resolveRequestedTemplateId(commandName, args);
+    if (cfg.enforcementMode === "strict" && strictViolations.length > 0) {
+        const warnings = [...parseWarnings, ...strictViolations];
+        return {
+            ...result,
+            ok: false,
+            code: "response-template-conflict",
+            message: strictViolations[0],
+            responseTemplate: buildMeta({
+                requestedTemplateId: requestedRaw,
+                appliedTemplateId: null,
+                enforcementMode: cfg.enforcementMode,
+                warnings
+            }, startNs)
+        };
+    }
     const override = cfg.commandOverrides[commandName];
     const chosenId = requestedRaw ?? override ?? cfg.defaultTemplateId ?? "default";
     const warnings = [...parseWarnings];
     const def = getResponseTemplateDefinition(chosenId);
     if (!def) {
         warnings.push(truncateTemplateWarning(`Unknown response template '${chosenId}'.`));
-        const explicitRequest = Boolean(requestedRaw || override);
-        if (cfg.enforcementMode === "strict" && explicitRequest) {
+        if (cfg.enforcementMode === "strict") {
             return {
                 ...result,
                 ok: false,
                 code: "response-template-invalid",
                 message: truncateTemplateWarning(`Unknown response template '${chosenId}'.`),
                 responseTemplate: buildMeta({
-                    requestedTemplateId: requestedRaw ?? override,
+                    requestedTemplateId: requestedRaw ?? override ?? cfg.defaultTemplateId,
                     appliedTemplateId: null,
                     enforcementMode: cfg.enforcementMode,
                     warnings

package/dist/modules/task-engine/dashboard-status.d.ts

@@ -0,0 +1,7 @@
+/** Best-effort parse of maintainer status YAML for dashboard UIs (no full YAML dependency). */
+export type WorkspaceStatusSnapshot = {
+    currentKitPhase: string | null;
+    activeFocus: string | null;
+    lastUpdated: string | null;
+};
+export declare function readWorkspaceStatusSnapshot(workspacePath: string): Promise<WorkspaceStatusSnapshot | null>;

package/dist/modules/task-engine/dashboard-status.js

@@ -0,0 +1,19 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export async function readWorkspaceStatusSnapshot(workspacePath) {
+    const filePath = path.join(workspacePath, "docs/maintainers/data/workspace-kit-status.yaml");
+    try {
+        const raw = await fs.readFile(filePath, "utf8");
+        const phaseMatch = raw.match(/^\s*current_kit_phase:\s*["']?([^"'\n#]+?)["']?\s*$/m);
+        const focusMatch = raw.match(/^\s*active_focus:\s*"([^"]*)"\s*$/m);
+        const updatedMatch = raw.match(/^\s*last_updated:\s*["']?([^"'\n#]+?)["']?\s*$/m);
+        return {
+            currentKitPhase: phaseMatch?.[1]?.trim() ?? null,
+            activeFocus: focusMatch?.[1] ?? null,
+            lastUpdated: updatedMatch?.[1]?.trim() ?? null
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/modules/task-engine/index.d.ts

@@ -4,4 +4,5 @@ export { TaskStore } from "./store.js";
 export { TransitionService } from "./service.js";
 export { TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard } from "./transitions.js";
 export { getNextActions } from "./suggestions.js";
+export { readWorkspaceStatusSnapshot } from "./dashboard-status.js";
 export declare const taskEngineModule: WorkflowModule;

package/dist/modules/task-engine/index.js

@@ -1,12 +1,14 @@
 import { maybeSpawnTranscriptHookAfterCompletion } from "../../core/transcript-completion-hook.js";
 import { TaskStore } from "./store.js";
 import { TransitionService } from "./service.js";
-import { TaskEngineError } from "./transitions.js";
+import { TaskEngineError, getAllowedTransitionsFrom } from "./transitions.js";
 import { getNextActions } from "./suggestions.js";
+import { readWorkspaceStatusSnapshot } from "./dashboard-status.js";
 export { TaskStore } from "./store.js";
 export { TransitionService } from "./service.js";
 export { TaskEngineError, TransitionValidator, isTransitionAllowed, getTransitionAction, resolveTargetState, getAllowedTransitionsFrom, stateValidityGuard, dependencyCheckGuard } from "./transitions.js";
 export { getNextActions } from "./suggestions.js";
+export { readWorkspaceStatusSnapshot } from "./dashboard-status.js";
 function taskStorePath(ctx) {
     const tasks = ctx.effectiveConfig?.tasks;
     if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) {
@@ -60,6 +62,11 @@ export const taskEngineModule = {
                     name: "get-next-actions",
                     file: "get-next-actions.md",
                     description: "Get prioritized next-action suggestions with blocking analysis."
+                },
+                {
+                    name: "dashboard-summary",
+                    file: "dashboard-summary.md",
+                    description: "Stable JSON cockpit summary for UI clients (tasks + maintainer status snapshot)."
                 }
             ]
         }
@@ -139,10 +146,63 @@ export const taskEngineModule = {
                     message: `Task '${taskId}' not found`
                 };
             }
+            const historyLimitRaw = args.historyLimit;
+            const historyLimit = typeof historyLimitRaw === "number" && Number.isFinite(historyLimitRaw) && historyLimitRaw > 0
+                ? Math.min(Math.floor(historyLimitRaw), 200)
+                : 50;
+            const log = store.getTransitionLog();
+            const recentTransitions = log
+                .filter((e) => e.taskId === taskId)
+                .sort((a, b) => (a.timestamp < b.timestamp ? 1 : -1))
+                .slice(0, historyLimit);
+            const allowedActions = getAllowedTransitionsFrom(task.status).map(({ to, action }) => ({
+                action,
+                targetStatus: to
+            }));
             return {
                 ok: true,
                 code: "task-retrieved",
-                data: { task }
+                data: { task, recentTransitions, allowedActions }
+            };
+        }
+        if (command.name === "dashboard-summary") {
+            const tasks = store.getAllTasks();
+            const suggestion = getNextActions(tasks);
+            const workspaceStatus = await readWorkspaceStatusSnapshot(ctx.workspacePath);
+            const readyTop = suggestion.readyQueue.slice(0, 15).map((t) => ({
+                id: t.id,
+                title: t.title,
+                priority: t.priority ?? null,
+                phase: t.phase ?? null
+            }));
+            const blockedTop = suggestion.blockingAnalysis.slice(0, 15);
+            const data = {
+                schemaVersion: 1,
+                taskStoreLastUpdated: store.getLastUpdated(),
+                workspaceStatus,
+                stateSummary: suggestion.stateSummary,
+                readyQueueTop: readyTop,
+                readyQueueCount: suggestion.readyQueue.length,
+                blockedSummary: {
+                    count: suggestion.blockingAnalysis.length,
+                    top: blockedTop
+                },
+                suggestedNext: suggestion.suggestedNext
+                    ? {
+                        id: suggestion.suggestedNext.id,
+                        title: suggestion.suggestedNext.title,
+                        status: suggestion.suggestedNext.status,
+                        priority: suggestion.suggestedNext.priority ?? null,
+                        phase: suggestion.suggestedNext.phase ?? null
+                    }
+                    : null,
+                blockingAnalysis: suggestion.blockingAnalysis
+            };
+            return {
+                ok: true,
+                code: "dashboard-summary",
+                message: "Dashboard summary built from task store and maintainer status snapshot",
+                data
             };
         }
         if (command.name === "list-tasks") {

package/dist/modules/task-engine/store.d.ts

@@ -13,4 +13,5 @@ export declare class TaskStore {
     getTransitionLog(): TransitionEvidence[];
     replaceAllTasks(tasks: TaskEntity[]): void;
     getFilePath(): string;
+    getLastUpdated(): string;
 }

package/dist/modules/task-engine/store.js

@@ -85,4 +85,7 @@ export class TaskStore {
     getFilePath() {
         return this.filePath;
     }
+    getLastUpdated() {
+        return this.document.lastUpdated;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workflow-cannon/workspace-kit",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "private": false,
   "packageManager": "pnpm@10.0.0",
   "license": "MIT",
@@ -32,9 +32,11 @@
     "prune-evidence": "node scripts/prune-evidence.mjs",
     "phase4-gates": "pnpm run check-compatibility && pnpm run check-planning-consistency && pnpm run check-release-channel",
     "phase5-gates": "pnpm run phase4-gates && pnpm run test",
+    "advisory:task-state-hand-edit": "node scripts/advisory-task-engine-state-hand-edit.mjs",
     "pre-release-transcript-hook": "pnpm run build && node scripts/pre-release-transcript-hook.mjs",
     "transcript:sync": "node scripts/run-transcript-cli.mjs sync-transcripts",
-    "transcript:ingest": "node scripts/run-transcript-cli.mjs ingest-transcripts"
+    "transcript:ingest": "node scripts/run-transcript-cli.mjs ingest-transcripts",
+    "ext:compile": "cd extensions/cursor-workflow-cannon && npm run compile"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",