@multileaf/ai-workflow 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to this project are documented in this file. The format foll
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-10-13
+
+### Added
+
+- Ticket-driven task entry point: `aiw task start --ticket=TEAM-123 [--title=text]` starts an SDD session that records the ticket, and `aiw task status` reports the ticket, stage statuses, and the next pending step with ticket-aware guidance. `aiw spec --ticket=TEAM-123` links the specification scaffold to the ticket. A new `ticket` skill (recommended as the `ticket-driven-development` capability) drives the flow in the host agent, keeping the brainstorming skip an explicit human decision.
+- `aiw telemetry show` summarizes buffered events by command and outcome (fill level against the retention cap, per-command success/failure counts); `--verbose` adds each event verbatim. `telemetry status` keeps reporting configuration only.
+- Per-model token usage: `usage.yml` records carry model attribution (`stage|budget|used|model`; legacy three-column rows still parse) and `aiw token-usage` summarizes total consumption by model. The OpenAI-compatible provider reports the response usage block, so interpreter usage is measured (marked `(measured)`) when the endpoint provides it and estimated otherwise; `scan.embedding`, `scan.interpreter`, and `recommend.decision` all record their model.
+
+## [0.6.1] - 2026-10-13
+
+### Added
+
+- Root context rendering: syncing a non-empty resource selection now writes the generated project context to the active target's root file (`AGENTS.md` for Codex/Cursor, `CLAUDE.md` for Claude Code, `GEMINI.md` for Gemini CLI), and `aiw target` migrates it between targets. The file is owned by AI Workflow, listed in the sync preview, and an existing hand-written root context is reported as a conflict instead of being overwritten.
+- Decision-model usage in `aiw recommend` is now recorded in `.aiw/usage.yml` (`recommend.decision`) alongside the scan stages.
+
+### Changed
+
+- Release workflows require a single protected-environment approval: the `github-release` job no longer declares the `npm` environment it did not need.
+
+### Added
+
+- Root context rendering: syncing a non-empty resource selection now writes the generated project context to the active target's root file (`AGENTS.md` for Codex/Cursor, `CLAUDE.md` for Claude Code, `GEMINI.md` for Gemini CLI), and `aiw target` migrates it between targets. The file is owned by AI Workflow, listed in the sync preview, and an existing hand-written root context is reported as a conflict instead of being overwritten.
+
 ## [0.6.0] - 2026-10-13
 
 ### Added
@@ -17,6 +40,7 @@ All notable changes to this project are documented in this file. The format foll
 
 - Interactive onboarding messages shortened to single-line prompts.
 - Embedding-model classification during onboarding now requires positive evidence (model name contains "embed" or Ollama family "embedding"); the previous heuristic misclassified `gpt-oss:20b` as an embedding model.
+
 ## [0.5.0] - 2026-10-08
 
 ### Added
@@ -33,6 +57,7 @@ All notable changes to this project are documented in this file. The format foll
 ### Changed
 
 - GitHub Actions now use Node 24-native `actions/checkout@v5` and `actions/setup-node@v5`, and CI runs on Node 24.
+
 ## [0.4.1] - 2026-10-08
 
 ### Fixed

package/README.md

@@ -63,7 +63,7 @@ For a Codex installation, the base layout is:
 
 `.aiw/` stores the provider-neutral manifest, profile, lockfile, checkpoints, bootstrap skill, selected resources, and generated working artifacts. ADRs are stored under `.context/adrs/`. The installer intentionally adds only `ai-init` and the base project state.
 
-Run `/ai-init` in the selected coding agent to scan the project and review evidence-based recommendations for skills, rules, agents, hooks, and templates. AI Workflow installs only the resources the user selects, then generates project-specific quality guidance from the detected stack and tools. Existing user files are preserved; conflicts are reported instead of overwritten. Hook resources are rendered according to each adapter's native or compatibility support.
+Run `/ai-init` in the selected coding agent to scan the project and review evidence-based recommendations for skills, rules, agents, hooks, and templates. AI Workflow installs only the resources the user selects, then generates project-specific quality guidance from the detected stack and tools. Syncing a non-empty selection also renders a root context file for the active target — `AGENTS.md` (Codex/Cursor), `CLAUDE.md` (Claude Code), `GEMINI.md` (Gemini CLI) — with the confirmed profile, quality commands, and pointers to `.aiw/` state; `aiw target` migrates it between targets. An existing hand-written root context file is reported as a conflict and never overwritten. Existing user files are preserved; conflicts are reported instead of overwritten. Hook resources are rendered according to each adapter's native or compatibility support.
 
 The installer does not modify `.gitignore`. Add `.aiw/generated/` yourself if generated specifications, plans, and artifacts should remain local. Versioned files under `.aiw/checkpoints/` are designed to remain reviewable project history.
 
@@ -204,6 +204,13 @@ npx @multileaf/ai-workflow recommend --select=typescript-quality,verification
 
 # Track a feature from its first artifact through final human approval.
 npx @multileaf/ai-workflow workflow start
+
+# Or start directly from a ticket / already-clear requirement (no brainstorm needed).
+npx @multileaf/ai-workflow task start --ticket=PROJ-142 --title="Add export endpoint"
+npx @multileaf/ai-workflow task status
+# Record an accepted brainstorm skip, then link the specification to the ticket:
+npx @multileaf/ai-workflow skip brainstorming --reason="Requirement provided by ticket PROJ-142"
+npx @multileaf/ai-workflow spec --ticket=PROJ-142 --title="Add export endpoint"
 npx @multileaf/ai-workflow brainstorm --title="Feature name"
 npx @multileaf/ai-workflow gate brainstorming
 # Present evidence and wait for a human reply before each approve command.
@@ -343,7 +350,8 @@ The typed SDK is available from `@multileaf/ai-workflow/plugin-sdk`. It exports
 Telemetry is disabled by default and requires explicit consent — offered once during interactive installation with an explicit default of No. Each event contains only the command name and its outcome; never arguments, file paths, or file contents. When telemetry is enabled but no host transport is configured, events accumulate in a rotated local buffer (`.aiw/telemetry-buffer.jsonl`, 200-event cap) that `aiw telemetry status --verbose` can inspect and `aiw telemetry disable` purges.
 
 ```bash
-npx @multileaf/ai-workflow telemetry status --verbose
+npx @multileaf/ai-workflow telemetry show             # summarized by command and outcome
+npx @multileaf/ai-workflow telemetry show --verbose   # events verbatim
 npx @multileaf/ai-workflow telemetry enable
 npx @multileaf/ai-workflow telemetry disable
 ```

package/dist/generator.js

@@ -23,6 +23,7 @@ export function generateProjectResources(profile, selected, write) {
         write(resolveGeneratedPath("agents/project-context.md"), `# Project Context\n\nThis project uses ${profile.frameworks.map((framework) => (framework === "nextjs" ? "Next.js" : framework)).join(", ")}. Follow the detected project structure and existing framework conventions.\n`);
     if (selected.length > 0) {
         write(resolveGeneratedPath("context/project-profile.md"), `# Confirmed Project Profile\n\n- Languages: ${profile.runtime.languages.join(", ") || "none detected"}\n- Frameworks: ${profile.frameworks.join(", ") || "none detected"}\n- Package manager: ${profile.packageManager}\n- All generated content is in English.\n`);
+        write(resolveGeneratedPath("context/root-context.md"), `# AI Workflow Project Context\n\nThis repository is managed by AI Workflow (\`.aiw/\` holds the neutral project state).\n\n- Languages: ${profile.runtime.languages.join(", ") || "none detected"}\n- Frameworks: ${profile.frameworks.join(", ") || "none detected"}\n- Package manager: ${profile.packageManager}${linterCommand ? `\n- Lint: \`${linterCommand}\`` : ""}${formatterCommand ? `\n- Format: \`${formatterCommand}\`` : ""}${uniqueTestCommands.map(({ scope, command }) => `\n- Tests (${scope}): \`${command}\``).join("")}\n\nBefore completing changes, run the project quality commands listed above. Follow installed AI Workflow skills, rules, and agents; the confirmed profile lives in \`.aiw/profile.yml\` and workflow evidence in \`.aiw/checkpoints/\`.\n`);
         write(resolveGeneratedPath("hooks/quality-check.md"), `# Quality Check Hook\n\nRun the available project quality commands before completion.${linterCommand ? `\n\n- Linter: \`${linterCommand}\`` : ""}${formatterCommand ? `\n- Formatter: \`${formatterCommand}\`` : ""}${uniqueTestCommands.map(({ scope, command }) => `\n- ${scope} tests: \`${command}\``).join("")}\n`);
     }
 }

package/dist/human-approval.d.ts

@@ -20,7 +20,10 @@ export type WorkflowSession = {
     status: "active" | "complete";
     startedAt: string;
     updatedAt: string;
+    ticket?: string;
+    title?: string;
 };
+export declare function validateTaskTicket(ticket: string): void;
 export type ApprovalStageDefinition = {
     optional: boolean;
     requiresQualityGate: boolean;
@@ -49,3 +52,4 @@ export declare function skipOptionalStage(ledger: ApprovalLedger, stage: HumanAp
 export declare function invalidateStageAndDescendants(ledger: ApprovalLedger, stage: HumanApprovalStage, updatedAt: string): ApprovalLedger;
 export declare function serializeApprovalLedger(ledger: ApprovalLedger): string;
 export declare function parseApprovalLedger(content: string): ApprovalLedger;
+export declare function assertWorkflowId(value: string): void;

package/dist/human-approval.js

@@ -2,6 +2,10 @@ import { createHash } from "node:crypto";
 import { parseDocument, stringify } from "yaml";
 import { HUMAN_APPROVAL_STAGES } from "./types.js";
 export const APPROVAL_STAGES = HUMAN_APPROVAL_STAGES;
+export function validateTaskTicket(ticket) {
+    if (!/^[A-Z][A-Z0-9_]*-\d+$/.test(ticket))
+        throw new Error("Task ticket must match TEAM-123, for example PROJ-142.");
+}
 const STAGE_DEFINITIONS = {
     brainstorming: { optional: true, requiresQualityGate: true },
     specification: { optional: false, requiresQualityGate: true },
@@ -22,7 +26,15 @@ const APPROVAL_RECORD_KEYS = new Set([
     "updatedAt",
 ]);
 const LEDGER_KEYS = new Set(["schema", "workflowId", "stages"]);
-const SESSION_KEYS = new Set(["schema", "workflowId", "status", "startedAt", "updatedAt"]);
+const SESSION_KEYS = new Set([
+    "schema",
+    "workflowId",
+    "status",
+    "startedAt",
+    "updatedAt",
+    "ticket",
+    "title",
+]);
 export function createApprovalLedger(workflowId) {
     assertWorkflowId(workflowId);
     return { schema: 1, workflowId, stages: {} };
@@ -47,12 +59,20 @@ export function parseWorkflowSession(content) {
         throw new Error("Workflow session status must be active or complete.");
     if (typeof value.startedAt !== "string" || typeof value.updatedAt !== "string")
         throw new Error("Workflow session requires start and update timestamps.");
+    if (value.ticket !== undefined && typeof value.ticket !== "string")
+        throw new Error("Workflow session ticket must be a string.");
+    if (value.title !== undefined && typeof value.title !== "string")
+        throw new Error("Workflow session title must be a string.");
+    if (typeof value.ticket === "string")
+        validateTaskTicket(value.ticket);
     const session = {
         schema: 1,
         workflowId: value.workflowId,
         status: value.status,
         startedAt: value.startedAt,
         updatedAt: value.updatedAt,
+        ...(value.ticket === undefined ? {} : { ticket: value.ticket }),
+        ...(value.title === undefined ? {} : { title: value.title }),
     };
     validateWorkflowSession(session);
     return session;
@@ -189,7 +209,7 @@ function assertTimestamp(value) {
         !Number.isFinite(Date.parse(value)))
         throw new Error("Approval timestamp must be a valid date-time.");
 }
-function assertWorkflowId(value) {
+export function assertWorkflowId(value) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(value))
         throw new Error("Workflow ID must be 1–64 characters using letters, numbers, dot, underscore, or hyphen.");
 }

package/dist/interpreter.d.ts

@@ -10,11 +10,16 @@ export type InterpretationRequest = {
 export type Interpreter = {
     interpret(request: InterpretationRequest): Promise<EvidenceFact[]>;
 };
+export type AiProviderUsage = {
+    promptTokens: number;
+    completionTokens: number;
+};
 export type AiProviderRequest = {
     system: string;
     prompt: string;
     maxTokens: number;
     responseFormat: "json";
+    onUsage?: (usage: AiProviderUsage) => void;
 };
 export type AiProvider = {
     generate(request: AiProviderRequest): Promise<string>;
@@ -35,5 +40,7 @@ export declare function buildInterpreterQuery(profile: ProjectProfile): string;
 type AiFetchLike = (url: string, init?: RequestInit) => Promise<Response>;
 export declare function loadAiProviderConfig(fs: FileSystem, aiwPath: string): AiProviderConfig | undefined;
 export declare function createOpenAiCompatibleProvider(config: AiProviderConfig, fetchImpl?: AiFetchLike, env?: Readonly<Record<string, string | undefined>>): AiProvider;
-export declare function createProjectInterpreter(root: string, provider: AiProvider, contextReader?: ContextReader): Interpreter;
+export declare function createProjectInterpreter(root: string, provider: AiProvider, contextReader?: ContextReader, options?: {
+    onUsage?: (usage: AiProviderUsage) => void;
+}): Interpreter;
 export {};

package/dist/interpreter.js

@@ -212,6 +212,12 @@ export function createOpenAiCompatibleProvider(config, fetchImpl = (url, init) =
             if (!response.ok)
                 throw new Error(`AI provider request failed for model ${config.model}: ${await response.text()}`);
             const body = (await response.json());
+            if (typeof body.usage?.prompt_tokens === "number" &&
+                typeof body.usage?.completion_tokens === "number")
+                request.onUsage?.({
+                    promptTokens: body.usage.prompt_tokens,
+                    completionTokens: body.usage.completion_tokens,
+                });
             const content = body.choices?.[0]?.message?.content;
             if (typeof content !== "string")
                 throw new Error(`AI provider ${config.model} returned no message content`);
@@ -219,7 +225,7 @@ export function createOpenAiCompatibleProvider(config, fetchImpl = (url, init) =
         },
     };
 }
-export function createProjectInterpreter(root, provider, contextReader = async (path) => new TextDecoder("utf-8", { fatal: true }).decode(await readFile(path))) {
+export function createProjectInterpreter(root, provider, contextReader = async (path) => new TextDecoder("utf-8", { fatal: true }).decode(await readFile(path)), options = {}) {
     const projectRoot = resolve(root);
     return {
         async interpret(request) {
@@ -261,6 +267,7 @@ export function createProjectInterpreter(root, provider, contextReader = async (
                 prompt: `Detected profile:\n${safeProfile}\n\nScoped project context:\n${sections.join("\n\n")}`,
                 maxTokens: scoped.maxTokens,
                 responseFormat: "json",
+                ...(options.onUsage ? { onUsage: options.onUsage } : {}),
             });
             return parseFacts(output, new Set(scoped.files));
         },

package/dist/migration.d.ts

@@ -3,7 +3,7 @@ import type { Target } from "./types.js";
 export type ResourceMigration = {
     source: string;
     destination: string;
-    type: ResourceType;
+    type: ResourceType | "context";
     id: string;
     neutralSource: boolean;
 };

package/dist/migration.js

@@ -2,6 +2,7 @@ import { parseDocument } from "yaml";
 import { isAbsolute, join } from "node:path";
 import { renderResourcePath } from "./adapter.js";
 import { RESOURCE_TYPES } from "./package-contract.js";
+const MIGRATABLE_TYPES = [...RESOURCE_TYPES, "context"];
 export function planNeutralResourceMigration(neutralRoot, relativeFiles, target) {
     const migrations = [];
     const diagnostics = [];
@@ -14,9 +15,7 @@ export function planNeutralResourceMigration(neutralRoot, relativeFiles, target)
             diagnostics.push({ path: relative, reason: "path is not normalized and project-relative" });
             continue;
         }
-        if (extra ||
-            parts.length !== 3 ||
-            !RESOURCE_TYPES.includes(candidateType)) {
+        if (extra || parts.length !== 3 || !MIGRATABLE_TYPES.includes(candidateType)) {
             diagnostics.push({ path: relative, reason: "unsupported neutral resource path" });
             continue;
         }
@@ -39,7 +38,9 @@ export function planNeutralResourceMigration(neutralRoot, relativeFiles, target)
         }
         migrations.push({
             source: join(neutralRoot, relative),
-            destination: renderResourcePath(target, type, id),
+            destination: type === "context"
+                ? renderResourcePath(target, type, id)
+                : renderResourcePath(target, type, id),
             type,
             id,
             neutralSource: target === "universal",

package/dist/ownership.d.ts

@@ -5,7 +5,7 @@ export type OwnedFile = {
     checksum: string;
     kind?: "neutral-resource" | "target-resource" | "ai-init" | "supporting-file";
     target?: Target;
-    resourceType?: ResourceType;
+    resourceType?: ResourceType | "context";
     resourceId?: string;
 };
 export type OwnershipMetadata = Omit<OwnedFile, "path" | "checksum">;

package/dist/ownership.js

@@ -49,7 +49,7 @@ export function parseOwnership(content) {
         if (file.target !== undefined && !TARGETS.includes(file.target))
             throw new Error(`Ownership inventory target is invalid: ${file.path}`);
         if (file.resourceType !== undefined &&
-            !RESOURCE_TYPES.includes(String(file.resourceType)))
+            ![...RESOURCE_TYPES, "context"].includes(String(file.resourceType)))
             throw new Error(`Ownership inventory resource type is invalid: ${file.path}`);
         if (file.resourceId !== undefined &&
             (typeof file.resourceId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(file.resourceId)))

package/dist/recommendations.js

@@ -14,6 +14,19 @@ const CATALOG = [
             ? { evidence: projectEvidence(profile), confidence: 0.92 }
             : undefined,
     },
+    {
+        id: "ticket-driven-development",
+        provider: "multileaf",
+        rationale: "Work often arrives as a ticket or an already-clear requirement; this entry point starts the SDD flow from the ticket without a brainstorming phase.",
+        permissions: [],
+        resources: local([
+            { type: "skills", id: "ticket" },
+            { type: "templates", id: "task" },
+        ]),
+        matches: (profile) => hasProjectSignals(profile)
+            ? { evidence: projectEvidence(profile), confidence: 0.9 }
+            : undefined,
+    },
     {
         id: "requirements-specification",
         provider: "multileaf",

package/dist/token-usage.d.ts

@@ -2,8 +2,14 @@ export type TokenUsage = {
     stage: string;
     budget: number;
     used: number;
+    model?: string;
 };
 export declare function validateTokenUsage(usage: TokenUsage): TokenUsage;
 export declare function parseTokenUsage(content: string): TokenUsage[];
 export declare function serializeTokenUsage(entries: TokenUsage[]): string;
 export declare function recordTokenUsage(entries: TokenUsage[], usage: TokenUsage): TokenUsage[];
+export declare function summarizeUsageByModel(entries: TokenUsage[]): {
+    model: string;
+    tokens: number;
+    stages: string[];
+}[];

package/dist/token-usage.js

@@ -10,6 +10,8 @@ export function validateTokenUsage(usage) {
     }
     if (usage.used > usage.budget)
         throw new Error(`Token budget exceeded for stage: ${usage.stage}`);
+    if (usage.model !== undefined && (typeof usage.model !== "string" || !usage.model.trim()))
+        throw new Error("Token usage model must be a non-empty string when present.");
     return usage;
 }
 export function parseTokenUsage(content) {
@@ -20,19 +22,44 @@ export function parseTokenUsage(content) {
         .slice(1)
         .filter(Boolean)
         .map((line) => {
-        const [stage, budget, used] = line.split("|");
-        return validateTokenUsage({ stage, budget: Number(budget), used: Number(used) });
+        const [stage, budget, used, model] = line.split("|");
+        return validateTokenUsage({
+            stage,
+            budget: Number(budget),
+            used: Number(used),
+            ...(model ? { model } : {}),
+        });
     });
 }
 export function serializeTokenUsage(entries) {
     return ([
         "schema: 1",
         ...entries
-            .sort((a, b) => a.stage.localeCompare(b.stage))
-            .map((entry) => `${entry.stage}|${entry.budget}|${entry.used}`),
+            .sort((a, b) => a.stage < b.stage
+            ? -1
+            : a.stage > b.stage
+                ? 1
+                : (a.model ?? "").localeCompare(b.model ?? ""))
+            .map((entry) => `${entry.stage}|${entry.budget}|${entry.used}${entry.model ? `|${entry.model}` : ""}`),
     ].join("\n") + "\n");
 }
 export function recordTokenUsage(entries, usage) {
     validateTokenUsage(usage);
-    return [...entries.filter((entry) => entry.stage !== usage.stage), usage];
+    return [
+        ...entries.filter((entry) => entry.stage !== usage.stage || entry.model !== usage.model),
+        usage,
+    ];
+}
+export function summarizeUsageByModel(entries) {
+    const byModel = new Map();
+    for (const entry of entries) {
+        const model = entry.model ?? "unattributed";
+        const bucket = byModel.get(model) ?? { tokens: 0, stages: new Set() };
+        bucket.tokens += entry.used;
+        bucket.stages.add(entry.stage);
+        byModel.set(model, bucket);
+    }
+    return [...byModel]
+        .map(([model, { tokens, stages }]) => ({ model, tokens, stages: [...stages].sort() }))
+        .sort((a, b) => b.tokens - a.tokens || a.model.localeCompare(b.model));
 }

package/dist/workflow.js

@@ -1,7 +1,7 @@
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { randomUUID } from "node:crypto";
 import { BASE_DIRECTORIES, WORKFLOW_DIRECTORY } from "./constants.js";
-import { detectTarget, isTarget, renderAiInit, renderAiInitPath, renderResourcePath, } from "./adapter.js";
+import { detectTarget, isTarget, renderAiInit, describeResource, renderAiInitPath, renderResourcePath, } from "./adapter.js";
 import { loadBundledResources } from "./bundled-resources.js";
 import { assertSafeProjectPath, withSafeProjectWrites, writeProjectFilesAtomically, } from "./files.js";
 import { parseProjectProfile, profileProject } from "./profile.js";
@@ -34,8 +34,8 @@ import { enforceOrganizationPolicy, parseOrganizationPolicy, serializeOrganizati
 import { composeContext, CONTEXT_LAYERS, readContextStore, writeContextLayer, } from "./context-store.js";
 import { loadContextDelta, retrieveTaskContext } from "./context-retrieval.js";
 import { createSummaryCache, isSummaryFresh, parseSummaryCache, serializeSummaryCache, } from "./context-cache.js";
-import { parseTokenUsage, recordTokenUsage, serializeTokenUsage } from "./token-usage.js";
-import { APPROVAL_STAGES, approveStage, beginStageApproval, createApprovalLedger, getUnresolvedPrerequisites, invalidateStageAndDescendants, parseApprovalLedger, parseWorkflowSession, rejectStage, serializeApprovalLedger, serializeWorkflowSession, skipOptionalStage, stageDefinition, stageFingerprint, } from "./human-approval.js";
+import { parseTokenUsage, recordTokenUsage, serializeTokenUsage, summarizeUsageByModel, } from "./token-usage.js";
+import { APPROVAL_STAGES, assertWorkflowId, validateTaskTicket, approveStage, beginStageApproval, createApprovalLedger, getUnresolvedPrerequisites, invalidateStageAndDescendants, parseApprovalLedger, parseWorkflowSession, rejectStage, serializeApprovalLedger, serializeWorkflowSession, skipOptionalStage, stageDefinition, stageFingerprint, } from "./human-approval.js";
 import { measureContextQuality, serializeContextQuality } from "./context-quality.js";
 import { serializeAdapterCapabilities } from "./adapter-contract.js";
 import { buildTraceabilityGraph, serializeTraceabilityGraph } from "./traceability.js";
@@ -46,61 +46,122 @@ import { enforcePolicyGate, gitPolicyTracking } from "./policy-gate.js";
 import { DEFAULT_TELEMETRY_CONFIG, loadTelemetryConfig, offerTelemetryConsent, parseTelemetryConfig, purgeTelemetryBuffer, readTelemetryBuffer, serializeTelemetryMapping, TELEMETRY_BUFFER_CAP, TELEMETRY_BUFFER_FILE, } from "./telemetry.js";
 import { createPluginScaffold, validatePluginDirectory, writePluginScaffold, } from "./plugin-sdk.js";
 import { executeOrchestrationPlan, parseOrchestrationPlan, serializeOrchestrationPreview, serializeOrchestrationResults, validateOrchestrationParallelism, } from "./orchestration.js";
+function beginWorkflowSession(fs, aiw, options) {
+    const sessionPath = join(aiw, "workflow.yml");
+    const ledgerPath = join(aiw, "approvals.yml");
+    if (fs.exists(sessionPath)) {
+        const previous = parseWorkflowSession(fs.read(sessionPath));
+        if (previous.status === "active")
+            return {
+                exitCode: 1,
+                error: `Workflow ${previous.workflowId} is still active. Complete it before starting another.`,
+            };
+        if (!fs.exists(ledgerPath))
+            return { exitCode: 1, error: "Completed workflow is missing its approval ledger." };
+        const archive = join(aiw, `checkpoints/workflow-${previous.workflowId}-approvals.yml`);
+        if (fs.exists(archive))
+            return { exitCode: 1, error: `Workflow approval archive already exists: ${archive}` };
+        fs.mkdir(join(aiw, "checkpoints"));
+        fs.write(archive, fs.read(ledgerPath));
+    }
+    else if (fs.exists(ledgerPath)) {
+        return {
+            exitCode: 1,
+            error: "Approval ledger exists without a workflow session; run doctor.",
+        };
+    }
+    const workflowId = options.id ?? randomUUID();
+    const priorRun = join(aiw, `checkpoints/workflow-${workflowId}-approvals.yml`);
+    if (fs.exists(priorRun))
+        return {
+            exitCode: 1,
+            error: `Workflow ID has already been used: ${workflowId}. Choose a new ID.`,
+        };
+    const now = new Date().toISOString();
+    const session = {
+        schema: 1,
+        workflowId,
+        status: "active",
+        startedAt: now,
+        updatedAt: now,
+        ...(options.ticket ? { ticket: options.ticket } : {}),
+        ...(options.title ? { title: options.title } : {}),
+    };
+    const ledger = createApprovalLedger(workflowId);
+    fs.write(ledgerPath, serializeApprovalLedger(ledger));
+    fs.write(sessionPath, serializeWorkflowSession(session));
+    return { exitCode: 0, output: `Workflow started: ${workflowId}.` };
+}
 export async function runCommand(args, root, fs, services = {}) {
     const aiw = join(root, WORKFLOW_DIRECTORY);
     try {
         fs = withSafeProjectWrites(fs, root);
         const command = args[0] ?? "help";
+        if (command === "task") {
+            if (!fs.exists(join(aiw, "manifest.yml")))
+                return { exitCode: 1, error: "Run `aiw install` first." };
+            const usage = "Usage: aiw task start --ticket=TEAM-123 [--title=text] [--id=workflow-id] | aiw task status";
+            const action = args[1];
+            const sessionPath = join(aiw, "workflow.yml");
+            if (action === "start") {
+                const options = parseNamedOptions(args.slice(2), ["ticket", "title", "id"]);
+                if (!options?.ticket)
+                    return { exitCode: 1, error: usage };
+                validateTaskTicket(options.ticket);
+                if (options.id !== undefined) {
+                    try {
+                        assertWorkflowId(options.id);
+                    }
+                    catch {
+                        return { exitCode: 1, error: "Workflow ID must be a UUID." };
+                    }
+                }
+                const result = beginWorkflowSession(fs, aiw, {
+                    ...(options.id ? { id: options.id } : {}),
+                    ticket: options.ticket,
+                    ...(options.title ? { title: options.title } : {}),
+                });
+                if (result.exitCode !== 0)
+                    return result;
+                const title = options.title ? ` titled "${options.title}"` : "";
+                return {
+                    exitCode: 0,
+                    output: `Task started for ticket ${options.ticket}${title}: ${result.output}\n` +
+                        `Next steps: ask the user whether the requirement is clear enough to skip brainstorming (record an accepted skip with \`aiw skip brainstorming --reason="Requirement provided by ticket ${options.ticket}"\`), then create the specification with \`aiw spec --ticket=${options.ticket} --title=...\`.`,
+                };
+            }
+            if (action === "status") {
+                if (!fs.exists(sessionPath))
+                    return {
+                        exitCode: 0,
+                        output: "No SDD workflow is active. Start one with `aiw task start --ticket=TEAM-123`.",
+                    };
+                const { session, ledger } = readWorkflowState(aiw, fs, false);
+                const lines = [
+                    ...(session.ticket
+                        ? [`Ticket: ${session.ticket}${session.title ? ` — ${session.title}` : ""}`]
+                        : []),
+                    `Workflow: ${session.workflowId} (${session.status})`,
+                    "Stages:",
+                    ...APPROVAL_STAGES.map((stage) => `- ${stage}: ${ledger.stages[stage]?.status ?? "not-started"}`),
+                ];
+                const next = APPROVAL_STAGES.find((stage) => (ledger.stages[stage]?.status ?? "not-started") === "not-started");
+                if (session.status === "active" && next)
+                    lines.push(`Next: ${next === "brainstorming" && session.ticket ? `decide brainstorm or record an accepted skip (ticket ${session.ticket} already provides the requirement)` : `advance ${next} (gate, approval)`}.`);
+                return { exitCode: 0, output: lines.join("\n") };
+            }
+            return { exitCode: 1, error: usage };
+        }
         if (command === "workflow") {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return { exitCode: 1, error: "Run `aiw install` first." };
             const action = args[1];
             const sessionPath = join(aiw, "workflow.yml");
-            const ledgerPath = join(aiw, "approvals.yml");
             if (action === "start") {
                 const options = parseNamedOptions(args.slice(2), ["id"]);
                 if (!options)
                     return { exitCode: 1, error: "Usage: aiw workflow start [--id=workflow-id]" };
-                if (fs.exists(sessionPath)) {
-                    const previous = parseWorkflowSession(fs.read(sessionPath));
-                    if (previous.status === "active")
-                        return {
-                            exitCode: 1,
-                            error: `Workflow ${previous.workflowId} is still active. Complete it before starting another.`,
-                        };
-                    if (!fs.exists(ledgerPath))
-                        return { exitCode: 1, error: "Completed workflow is missing its approval ledger." };
-                    const archive = join(aiw, `checkpoints/workflow-${previous.workflowId}-approvals.yml`);
-                    if (fs.exists(archive))
-                        return { exitCode: 1, error: `Workflow approval archive already exists: ${archive}` };
-                    fs.mkdir(join(aiw, "checkpoints"));
-                    fs.write(archive, fs.read(ledgerPath));
-                }
-                else if (fs.exists(ledgerPath)) {
-                    return {
-                        exitCode: 1,
-                        error: "Approval ledger exists without a workflow session; run doctor.",
-                    };
-                }
-                const workflowId = options.id ?? randomUUID();
-                const priorRun = join(aiw, `checkpoints/workflow-${workflowId}-approvals.yml`);
-                if (fs.exists(priorRun))
-                    return {
-                        exitCode: 1,
-                        error: `Workflow ID has already been used: ${workflowId}. Choose a new ID.`,
-                    };
-                const now = new Date().toISOString();
-                const session = {
-                    schema: 1,
-                    workflowId,
-                    status: "active",
-                    startedAt: now,
-                    updatedAt: now,
-                };
-                const ledger = createApprovalLedger(workflowId);
-                fs.write(ledgerPath, serializeApprovalLedger(ledger));
-                fs.write(sessionPath, serializeWorkflowSession(session));
-                return { exitCode: 0, output: `Workflow started: ${workflowId}.` };
+                return beginWorkflowSession(fs, aiw, { id: options.id });
             }
             if (action === "status") {
                 if (!fs.exists(sessionPath))
@@ -359,13 +420,44 @@ export async function runCommand(args, root, fs, services = {}) {
         if (command === "telemetry") {
             if (!fs.exists(join(aiw, "manifest.yml")))
                 return { exitCode: 1, error: "Run `aiw install` first." };
-            const usage = "Usage: aiw telemetry <status|enable|disable> [--verbose] [--commands=include|exclude] [--outcomes=include|exclude]";
+            const usage = "Usage: aiw telemetry <status|show|enable|disable> [--verbose] [--commands=include|exclude] [--outcomes=include|exclude]";
             const action = args[1];
             if (!action)
                 return { exitCode: 1, error: usage };
             const telemetryConfig = loadTelemetryConfig(fs, aiw);
             const actionArgs = args.slice(2).filter((arg) => arg !== "--verbose");
             const verbose = args.includes("--verbose");
+            if (action === "show") {
+                if (actionArgs.length !== 0)
+                    return { exitCode: 1, error: usage };
+                const buffered = readTelemetryBuffer(fs, aiw);
+                const byCommand = new Map();
+                for (const event of buffered) {
+                    const key = event.command ?? "unknown";
+                    const entry = byCommand.get(key) ?? { success: 0, failure: 0 };
+                    if (event.outcome === "failure")
+                        entry.failure += 1;
+                    else
+                        entry.success += 1;
+                    byCommand.set(key, entry);
+                }
+                const lines = [
+                    `Telemetry is ${telemetryConfig.enabled ? "enabled" : "disabled"}.`,
+                    `Buffered events: ${buffered.length}/${TELEMETRY_BUFFER_CAP} (.aiw/${TELEMETRY_BUFFER_FILE}).`,
+                ];
+                if (buffered.length > 0) {
+                    lines.push("By command:");
+                    for (const [command, { success, failure }] of [...byCommand].sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+                        lines.push(`- ${command}: ${success} success, ${failure} failure`);
+                }
+                if (verbose && buffered.length > 0) {
+                    lines.push("Events:");
+                    lines.push(...buffered.map((event) => `- ${JSON.stringify(event)}`));
+                }
+                if (!telemetryConfig.enabled)
+                    lines.push("Note: telemetry is disabled, so no new events are recorded; the buffer keeps previously collected events until purged.");
+                return { exitCode: 0, output: lines.join("\n") };
+            }
             if (action === "status") {
                 if (actionArgs.length !== 0)
                     return { exitCode: 1, error: usage };
@@ -444,10 +536,15 @@ export async function runCommand(args, root, fs, services = {}) {
             const profile = await (services.profiler?.profile(root) ?? profileProject(root));
             let interpreter = services.interpreter;
             let interpreterModel;
+            let interpreterUsage;
             if (!interpreter) {
                 const aiConfig = loadAiProviderConfig(fs, aiw);
                 if (aiConfig?.enabled) {
-                    interpreter = createProjectInterpreter(root, services.aiProvider ?? createOpenAiCompatibleProvider(aiConfig));
+                    interpreter = createProjectInterpreter(root, services.aiProvider ?? createOpenAiCompatibleProvider(aiConfig), undefined, {
+                        onUsage: (usage) => {
+                            interpreterUsage = usage;
+                        },
+                    });
                     interpreterModel = aiConfig.model;
                 }
             }
@@ -477,6 +574,7 @@ export async function runCommand(args, root, fs, services = {}) {
                                     label: "embedding",
                                     tokens: Math.ceil(buildInterpreterQuery(profile).length / 4),
                                     detail: `${contextConfig.model} — scoped interpreter context to ${matches.length} semantic matches`,
+                                    model: contextConfig.model,
                                 });
                             }
                         }
@@ -488,10 +586,14 @@ export async function runCommand(args, root, fs, services = {}) {
                 const interpretationRequest = createInterpretationRequest(profile, scopedFiles, 4000, priorityFiles);
                 const inferred = await interpreter.interpret(interpretationRequest);
                 profile.facts = mergeFacts(profile.facts, inferred);
+                const actualTokens = interpreterUsage
+                    ? interpreterUsage.promptTokens + interpreterUsage.completionTokens
+                    : undefined;
                 modelUsage.push({
                     label: "interpreter",
-                    tokens: interpretationRequest.estimatedTokens,
-                    detail: `${interpreterModel} — ${inferred.length} facts from ${interpretationRequest.files.length} files`,
+                    tokens: actualTokens ?? interpretationRequest.estimatedTokens,
+                    detail: `${interpreterModel} — ${inferred.length} facts from ${interpretationRequest.files.length} files${actualTokens !== undefined ? " (measured)" : ""}`,
+                    model: interpreterModel ?? "unknown",
                 });
             }
             const overrides = readFactOverrides(fs, aiw);
@@ -530,6 +632,7 @@ export async function runCommand(args, root, fs, services = {}) {
                     label: "embedding",
                     tokens: Math.ceil(indexedChars / 4),
                     detail: `${semanticConfig.model} — indexed ${index.chunks.length} chunks in ${Math.ceil(index.chunks.length / 64)} batch requests`,
+                    model: semanticConfig.model,
                 });
             }
             if (modelUsage.length > 0) {
@@ -541,6 +644,7 @@ export async function runCommand(args, root, fs, services = {}) {
                         stage: `scan.${usage.label}`,
                         budget: usage.tokens,
                         used: usage.tokens,
+                        model: usage.model,
                     });
                 fs.write(usagePath, serializeTokenUsage(next));
             }
@@ -1050,8 +1154,13 @@ export async function runCommand(args, root, fs, services = {}) {
                         exitCode: 1,
                         error: `Decision model ${rankingConfig.model} is not available at ${rankingConfig.baseUrl}.`,
                     };
+                let decisionTokens = 0;
                 ranked = await rankRecommendations(recommendations, profile, async (scoped, recs) => {
-                    const response = await decisionProvider.decide(buildRecommendationRankingRequest(profileSummaryForRanking(scoped), recs));
+                    const request = buildRecommendationRankingRequest(profileSummaryForRanking(scoped), recs);
+                    decisionTokens += Math.ceil((request.state.length +
+                        Object.values(request.questions).reduce((total, question) => total + question.instructions.length, 0)) /
+                        4);
+                    const response = await decisionProvider.decide(request);
                     const answers = {};
                     for (const [id, answer] of Object.entries(response.answers))
                         answers[id] =
@@ -1065,6 +1174,14 @@ export async function runCommand(args, root, fs, services = {}) {
                                 : {};
                     return answers;
                 });
+                const usagePath = join(aiw, "usage.yml");
+                const entries = fs.exists(usagePath) ? parseTokenUsage(fs.read(usagePath)) : [];
+                fs.write(usagePath, serializeTokenUsage(recordTokenUsage(entries, {
+                    stage: "recommend.decision",
+                    budget: decisionTokens,
+                    used: decisionTokens,
+                    model: rankingConfig.model,
+                })));
                 ordered = ranked.items;
             }
             const selectedOption = args.find((arg) => arg.startsWith("--select="));
@@ -1397,8 +1514,11 @@ export async function runCommand(args, root, fs, services = {}) {
                 return { exitCode: 1, error: "Run `aiw install` first." };
             assertStageReady(aiw, fs, "specification");
             const title = args.find((arg) => arg.startsWith("--title="))?.slice(8) || "Untitled Specification";
+            const ticket = args.find((arg) => arg.startsWith("--ticket="))?.slice(9);
+            if (ticket !== undefined)
+                validateTaskTicket(ticket);
             const path = join(aiw, "generated/specs/specification.md");
-            fs.write(path, `# ${title}\n\n## Context\n\n## Requirements\n\n### REQ-001: Requirement title\n\n- **Description:**\n- **Acceptance criteria:**\n  - Given\n  - When\n  - Then\n\n## Non-functional Requirements\n\n## Constraints\n\n## Open Questions\n\n`);
+            fs.write(path, `# ${title}\n${ticket ? `\n> Ticket: ${ticket}\n` : ""}\n## Context\n\n## Requirements\n\n### REQ-001: Requirement title\n\n- **Description:**\n- **Acceptance criteria:**\n  - Given\n  - When\n  - Then\n\n## Non-functional Requirements\n\n## Constraints\n\n## Open Questions\n\n`);
             return { exitCode: 0, output: `Specification artifact created: ${path}` };
         }
         if (command === "adr") {
@@ -1822,7 +1942,15 @@ export async function runCommand(args, root, fs, services = {}) {
                 fs.write(usagePath, serializeTokenUsage(next));
                 return { exitCode: 0, output: `Token usage recorded: ${stage} (${used}/${budget})` };
             }
-            return { exitCode: 0, output: serializeTokenUsage(entries) };
+            if (entries.length === 0)
+                return { exitCode: 0, output: "No token usage recorded yet." };
+            const summary = summarizeUsageByModel(entries);
+            return {
+                exitCode: 0,
+                output: `Token usage by model:\n${summary
+                    .map((entry) => `- ${entry.model}: ${entry.tokens.toLocaleString("en-US")} tokens (${entry.stages.join(", ")})`)
+                    .join("\n")}\n\nRaw records:\n${serializeTokenUsage(entries)}`,
+            };
         }
         if (command === "context-quality") {
             const metrics = measureContextQuality(readContextStore(root, fs));
@@ -1868,7 +1996,7 @@ export async function runCommand(args, root, fs, services = {}) {
         }
         return {
             exitCode: 0,
-            output: "aiw install [--target target] | workflow <start|status|complete> [--id=id] | approve <stage> | reject <stage> --reason=text | skip <optional-stage> --reason=text | ui [--port=number] | orchestrate --plan=path [--execute] [--max-parallel=number] | telemetry <status|enable|disable> [privacy options] | plugin <create|validate> [options] | scan | semantic <status|query> | decision <status|triage> | self-validate --ticket=TYPE-000 | organization-policy --file=path [--replace] | policy-check --package=path [--package=path] | preset --file=path [--replace] | context | context-summary | context-quality | capabilities [--target=target] | token-usage [--stage=name --budget=number --used=number] | registry [--search=query] [--private=name] | registry configure --file=path [--replace] | skills <search|inspect|install|check|update> [options] | audit-package --package=path | verify-package --package=path --checksum=sha256 | brainstorm [--title=title] | spec [--title=title] | adr [--id=id --title=title] | plan [--title=title] | verify | trace | gate <stage> | recommend [--select=id,id] | status | doctor | repair | uninstall [--dry-run] | target <target> | rollback | confirm | resolve --package=path | update --package=path --target=target | validate [--package=path]",
+            output: "aiw install [--target target] | workflow <start|status|complete> [--id=id] | task <start|status> --ticket=TEAM-123 [--title=text] | approve <stage> | reject <stage> --reason=text | skip <optional-stage> --reason=text | ui [--port=number] | orchestrate --plan=path [--execute] [--max-parallel=number] | telemetry <status|show|enable|disable> [privacy options] | plugin <create|validate> [options] | scan | semantic <status|query> | decision <status|triage> | self-validate --ticket=TYPE-000 | organization-policy --file=path [--replace] | policy-check --package=path [--package=path] | preset --file=path [--replace] | context | context-summary | context-quality | capabilities [--target=target] | token-usage [--stage=name --budget=number --used=number] | registry [--search=query] [--private=name] | registry configure --file=path [--replace] | skills <search|inspect|install|check|update> [options] | audit-package --package=path | verify-package --package=path --checksum=sha256 | brainstorm [--title=title] | spec [--title=title] | adr [--id=id --title=title] | plan [--title=title] | verify | trace | gate <stage> | recommend [--select=id,id] | status | doctor | repair | uninstall [--dry-run] | target <target> | rollback | confirm | resolve --package=path | update --package=path --target=target | validate [--package=path]",
         };
     }
     catch (error) {
@@ -2134,6 +2262,25 @@ function syncSelectedResources(fs, root, aiw, profile, selected, apply = false,
         const rule = path.match(/^generated\/rules\/(project-quality|tdd-project-policy)\.md$/);
         if (rule)
             addResource("rules", rule[1], content);
+        const rootContext = path === "generated/context/root-context.md";
+        if (rootContext) {
+            const neutralContextPath = join(root, describeResource("universal", "context", "project").path);
+            addOwned(neutralContextPath, content, {
+                kind: "neutral-resource",
+                target: "universal",
+                resourceType: "context",
+                resourceId: "project",
+            });
+            const targetContextPath = describeResource(target, "context", "project").path;
+            if (targetContextPath !== renderAiInitPath(target)) {
+                addOwned(join(root, targetContextPath), content, {
+                    kind: "target-resource",
+                    target,
+                    resourceType: "context",
+                    resourceId: "project",
+                });
+            }
+        }
     });
     const ownershipPath = join(aiw, "ownership.yml");
     if (fs.pathType?.(ownershipPath) !== "file")

package/docs/telemetry.md

@@ -9,7 +9,9 @@ During an interactive `aiw install`, after the optional model questions, the ins
 ## Controls
 
 ```bash
-aiw telemetry status
+aiw telemetry show            # buffered events summarized by command and outcome
+aiw telemetry show --verbose  # ...plus each event verbatim
+aiw telemetry status          # configuration only
 aiw telemetry enable --commands=include --outcomes=include
 aiw telemetry enable --commands=exclude --outcomes=include
 aiw telemetry disable

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multileaf/ai-workflow",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Portable spec-driven development workflow for AI coding agents",
   "license": "MIT",
   "repository": {

package/resources/package.yaml

@@ -31,6 +31,7 @@ resources:
     - { id: nestjs-development, version: 0.1.0, path: skills/nestjs-development.md }
     - { id: prisma-data-access, version: 0.1.0, path: skills/prisma-data-access.md }
     - { id: vite-frontend, version: 0.1.0, path: skills/vite-frontend.md }
+    - { id: ticket, version: 0.1.0, path: skills/ticket.md }
   rules:
     - { id: language-policy, version: 0.1.0, path: rules/language-policy.md }
     - { id: tdd-policy, version: 0.1.0, path: rules/tdd-policy.md }

package/resources/skills/ticket.md

@@ -0,0 +1,18 @@
+---
+name: ticket
+description: Start a feature directly from a ticket or specific requirement without a brainstorming phase.
+---
+
+# Ticket-Driven Task
+
+For every approval or optional skip, use the host's native blocking question widget, not a prose-only prompt when the widget is available. Leave choices unselected and offer "Accept skip" / "Do not skip" (or "Approve and continue" / "Request changes" / "Reject/stop" at gates). Wait for an actual submission before running any `aiw` approval or skip command. The CLI records the decision but cannot verify that a widget was used.
+
+Use this skill when the user provides a ticket ID (for example `PROJ-142`) or an already-clear requirement and wants to start work immediately.
+
+1. Extract the ticket ID and a short title from the user's request. Start the task with `npx --yes --package=@multileaf/ai-workflow -- aiw task start --ticket=<TICKET> --title="<short title>"` (add `--id=<uuid>` only if the user provides one). If a session is already active, report it with `aiw task status` and stop.
+2. Brainstorming decision: the ticket already provides the requirement, but skipping is still a human decision. Ask with the blocking widget whether to skip brainstorming ("Accept skip" / "Do not skip"). Only after an explicit acceptance, record it with `npx --yes --package=@multileaf/ai-workflow -- aiw skip brainstorming --reason="Requirement provided by ticket <TICKET>"`. If the user prefers to brainstorm after all, run the brainstorming skill instead.
+3. Create the specification linked to the ticket with `npx --yes --package=@multileaf/ai-workflow -- aiw spec --ticket=<TICKET> --title="<title>"`, fill in requirements with stable IDs and Given/When/Then acceptance criteria derived from the ticket, then pass `aiw gate specification`, present the artifact, wait, and record the human reply with `aiw approve specification` (or `aiw reject specification --reason=<feedback>` and revise).
+4. Continue the standard SDD sequence: technical design when the change has architecture impact (`aiw adr`, gate, approval), implementation plan (`aiw plan`, gate, approval), TDD implementation, verification (`aiw verify`, gate, approval), code review, and traceability (`aiw trace`, gate, approval). Check progress at any point with `npx --yes --package=@multileaf/ai-workflow -- aiw task status`, which reports the ticket and the next pending stage.
+5. Complete with `npx --yes --package=@multileaf/ai-workflow -- aiw workflow complete` only after all stages resolve; the ticket reference stays in the archived session and the specification.
+
+Never invent a ticket ID: if the user did not provide one, ask for it (or offer the plain `aiw workflow start` flow). Never skip brainstorming without an explicit human acceptance recorded through `aiw skip brainstorming`. Use `npx --yes --package=@multileaf/ai-workflow -- aiw <command>` when no global CLI is available.