@schnick371/devsteps-shared 1.1.0-next.4 → 2.0.0-next.1

package/dist/core/add-batch.js

@@ -0,0 +1,219 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Whole-request preparation, actual folder claims and honest partial publication (STORY-530).
+ */
+import { existsSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { writeFileAtomic, writeJsonAtomic } from '../utils/atomic-write.js';
+import { TYPE_TO_DIRECTORY } from '../utils/index.js';
+import { parseBatchInput, resolveBatchDescription } from './add-batch-input.js';
+import { addItemWarnings, prepareAddItem, renderAddContent } from './add-preparation.js';
+import { checkMigrationNeeded, needsItemsDirectoryMigration } from './auto-migrate-detect.js';
+import { getCategoryLeaf } from './classification-leaf.js';
+import { loadClassificationRegistry } from './classification-registry.js';
+import { getConfig } from './config.js';
+import { ItemReservationError, loadCounters, reserveItemFolders } from './counters.js';
+import { invalidateItem } from './item-store.js';
+export class AddBatchPartialError extends Error {
+    partial;
+    constructor(cause, partial) {
+        super(`Batch creation failed during ${partial.phase}${partial.failedKey ? ` for "${partial.failedKey}"` : ''}: ${cause instanceof Error ? cause.message : String(cause)}. Allocated IDs remain reserved; inspect partial state before any retry.`, { cause });
+        this.name = 'AddBatchPartialError';
+        this.partial = partial;
+    }
+}
+/** Old root directories stay invisible to current claims, even beside a modern items/ tree. */
+function legacyTypePaths(devstepsDir) {
+    const paths = [];
+    for (const root of ['', 'archive']) {
+        for (const directory of Object.values(TYPE_TO_DIRECTORY)) {
+            const relative = join(root, basename(directory));
+            if (existsSync(join(devstepsDir, relative)))
+                paths.push(relative);
+        }
+    }
+    return paths;
+}
+async function preflightBatch(devstepsDir, input) {
+    const entries = parseBatchInput(input);
+    if (!existsSync(devstepsDir))
+        throw new Error('Project not initialized. Run devsteps-init first.');
+    const config = await getConfig(devstepsDir);
+    const migration = checkMigrationNeeded(devstepsDir);
+    const normalRootMigration = needsItemsDirectoryMigration(devstepsDir);
+    const residualLegacy = legacyTypePaths(devstepsDir).filter((relative) => 
+    // Normal startup moves the original eight live type roots only, before items/ exists.
+    !normalRootMigration ||
+        relative !== basename(relative) ||
+        ['docs', 'decisions', 'questions'].includes(relative));
+    if (residualLegacy.length > 0) {
+        throw new Error(`Batch creation cannot safely migrate mixed or residual legacy type roots. Residual legacy type paths: ${residualLegacy.map((relative) => `"${relative}"`).join(', ')}. Inspect and migrate these paths separately before retrying; normal startup migration may leave them unchanged.`);
+    }
+    if (migration.needed || normalRootMigration) {
+        throw new Error('Batch creation requires the current item-folder layout. Run devsteps status for the normal startup migration, inspect the changes, then retry the batch.');
+    }
+    // Malformed counters are a preflight refusal too, before a folder can be claimed.
+    loadCounters(devstepsDir);
+    const prepared = [];
+    for (const entry of entries) {
+        try {
+            prepared.push(await prepareAddItem(devstepsDir, entry.args, config));
+        }
+        catch (error) {
+            // Preserve domain error classes and structured fields used by all adapters.
+            if (error instanceof Error)
+                error.message = `Batch key "${entry.key}": ${error.message}`;
+            throw error;
+        }
+    }
+    return { entries, config, prepared };
+}
+function reserveBatchEntries(devstepsDir, entries) {
+    let reservation;
+    try {
+        reservation = reserveItemFolders(devstepsDir, entries.map((entry) => ({ key: entry.key, type: entry.args.type })));
+    }
+    catch (error) {
+        if (error instanceof ItemReservationError) {
+            const detail = error.reservation;
+            throw new AddBatchPartialError(error, {
+                phase: detail.phase === 'claim' ? 'claim' : 'counters',
+                keyToId: detail.keyToId,
+                completedKeys: [],
+                reservedKeys: detail.reservedKeys,
+                ...(detail.failedKey !== undefined ? { failedKey: detail.failedKey } : {}),
+                countersPersisted: detail.countersPersisted,
+                ...(detail.lock !== undefined ? { lock: detail.lock } : {}),
+            });
+        }
+        throw error;
+    }
+    return reservation;
+}
+function renderBatchItems(entries, prepared, ids, onKey) {
+    return entries.map((entry, index) => {
+        onKey(entry.key);
+        const itemId = ids.get(entry.key);
+        if (itemId === undefined)
+            throw new Error(`Missing claim for batch key "${entry.key}".`);
+        const args = { ...entry.args, description: resolveBatchDescription(entry, ids) };
+        const metadata = { id: itemId, ...prepared[index].metadata };
+        return { args, metadata, ...renderAddContent(args, itemId, metadata.created) };
+    });
+}
+function createdBatchResult(key, prepared, args, metadata, hint, config, countersRaised, warnings) {
+    const { gate, diagnostics } = prepared;
+    return {
+        key,
+        itemId: metadata.id,
+        metadata,
+        config,
+        classification: gate,
+        countersRaised,
+        ...(warnings.length > 0 ? { warnings: [...warnings] } : {}),
+        ...(args.process_definition !== undefined || diagnostics.length > 0 ? { diagnostics } : {}),
+        ...(hint !== undefined ? { hint } : {}),
+    };
+}
+function publishBatchItems(devstepsDir, entries, prepared, config, reservation, ids) {
+    const completed = new Set();
+    let phase = 'claim';
+    let failedKey;
+    const claims = reservation.claims;
+    const countersRaised = reservation.countersRaised;
+    const results = [];
+    try {
+        phase = 'render';
+        const rendered = renderBatchItems(entries, prepared, ids, (key) => {
+            failedKey = key;
+        });
+        for (const [index, entry] of entries.entries()) {
+            failedKey = entry.key;
+            const claim = claims.get(entry.key);
+            if (claim === undefined)
+                throw new Error(`Missing claim for batch key "${entry.key}".`);
+            const { args, metadata, description, hint } = rendered[index];
+            phase = 'description';
+            writeFileAtomic(claim.paths.description, description);
+            phase = 'metadata';
+            writeJsonAtomic(claim.paths.metadata, metadata);
+            completed.add(entry.key);
+            results.push(createdBatchResult(entry.key, prepared[index], args, metadata, hint, config, countersRaised, reservation.warnings));
+            // A follow-up failure must never hide an item that was fully published.
+            try {
+                invalidateItem(devstepsDir, metadata.id);
+            }
+            catch (error) {
+                results[index].warnings = [`Item cache invalidation failed: ${String(error)}`];
+            }
+        }
+    }
+    catch (error) {
+        throw new AddBatchPartialError(error, {
+            phase,
+            keyToId: Object.fromEntries(ids),
+            completedKeys: [...completed],
+            reservedKeys: [...ids.keys()].filter((key) => !completed.has(key)),
+            ...(failedKey !== undefined ? { failedKey } : {}),
+            countersPersisted: true,
+        });
+    }
+    return results;
+}
+/** Read the final state once per category, after every metadata file is visible. */
+async function completeBatchResults(devstepsDir, entries, ids, results) {
+    const finalLeaves = new Map();
+    for (const [index, result] of results.entries()) {
+        const warnings = [...(result.warnings ?? [])];
+        try {
+            const args = {
+                ...entries[index].args,
+                description: resolveBatchDescription(entries[index], ids),
+            };
+            const description = renderAddContent(args, result.itemId, result.metadata.created).description;
+            warnings.push(...addItemWarnings(devstepsDir, result.metadata, args, description));
+        }
+        catch (error) {
+            warnings.push(`Post-creation diagnostics failed: ${String(error)}`);
+        }
+        if (result.classification.leaf) {
+            try {
+                const category = result.classification.category;
+                let leaf = finalLeaves.get(category);
+                if (!leaf) {
+                    leaf = await getCategoryLeaf(devstepsDir, category, loadClassificationRegistry(devstepsDir).digest);
+                    finalLeaves.set(category, leaf);
+                }
+                result.classification = {
+                    ...result.classification,
+                    leaf: {
+                        open_count: leaf.open_count,
+                        delivered_count: leaf.delivered_count,
+                        retired_count: leaf.retired_count,
+                    },
+                    leaf_receipt: leaf.leaf_receipt,
+                };
+            }
+            catch (error) {
+                warnings.push(`Created ${result.itemId}; final category receipt unavailable: ${String(error)}`);
+            }
+        }
+        if (warnings.length > 0)
+            result.warnings = warnings;
+    }
+}
+/**
+ * No writes until every entry and reference passes. Runtime failure retains all claims;
+ * atomic publication of each file does not make this a multi-file transaction.
+ */
+export async function addBatch(devstepsDir, input) {
+    const { entries, config, prepared } = await preflightBatch(devstepsDir, input);
+    const reservation = reserveBatchEntries(devstepsDir, entries);
+    const ids = new Map(Object.entries(reservation.keyToId));
+    const results = publishBatchItems(devstepsDir, entries, prepared, config, reservation, ids);
+    await completeBatchResults(devstepsDir, entries, ids, results);
+    return { items: results, keyToId: Object.fromEntries(ids) };
+}
+//# sourceMappingURL=add-batch.js.map

package/dist/core/add-batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-batch.js","sourceRoot":"","sources":["../../src/core/add-batch.ts"],"names":[],"mappings":"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"}

package/dist/core/add-preparation.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Shared add preparation, defaults and content rendering.
+ */
+import type { DevStepsConfig, ItemMetadata, ItemType } from '../schemas/index.js';
+import type { AddItemArgs } from './add.js';
+import { type GateResult } from './classification-gate.js';
+import { type WorkflowAuthoringDiagnostic } from './workflow-v2-authoring.js';
+/**
+ * BUG-112: fail fast on a malformed v1 `process_definition` at authoring time instead of
+ * only surfacing it later at `workflow_run_start`. A `'2.0'` definition is validated by its own
+ * compiler, not here; any other `schema_version` is refused (TASK-962).
+ */
+export declare function validateProcessDefinitionShape(type: ItemType, processDefinition: unknown): void;
+export interface PreparedAddItem {
+    args: AddItemArgs;
+    metadata: Omit<ItemMetadata, 'id'>;
+    gate: GateResult;
+    diagnostics: WorkflowAuthoringDiagnostic[];
+}
+/** Validate authoring values without allocating an ID or publishing an item. */
+export declare function prepareAddItem(devstepsDir: string, args: AddItemArgs, config: DevStepsConfig): Promise<PreparedAddItem>;
+/** Render from the actual allocated ID; batch descriptions are resolved before this call. */
+export declare function renderAddContent(args: AddItemArgs, itemId: string, now: string, options?: {
+    preserveDescription?: boolean;
+}): {
+    description: string;
+    hint?: string;
+};
+export declare function addItemWarnings(devstepsDir: string, metadata: ItemMetadata, args: AddItemArgs, description: string): string[];
+type DocTemplate = 'none' | 'MADR 4.0' | `Diataxis ${string}`;
+/**
+ * Doc guidance, returned when a doc item is created instead of carried in every request's
+ * tool schema (TASK-897): which skeleton was generated, or what generates one.
+ */
+export declare function docAddHint(template: DocTemplate, hadDescription: boolean): string;
+export {};
+//# sourceMappingURL=add-preparation.d.ts.map

package/dist/core/add-preparation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-preparation.d.ts","sourceRoot":"","sources":["../../src/core/add-preparation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAWlF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,EAA2B,KAAK,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAgBpF,OAAO,EAEL,KAAK,2BAA2B,EACjC,MAAM,4BAA4B,CAAC;AAGpC;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,QAAQ,EAAE,iBAAiB,EAAE,OAAO,GAAG,IAAI,CAsB/F;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACnC,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,EAAE,2BAA2B,EAAE,CAAC;CAC5C;AA4CD,gFAAgF;AAChF,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,eAAe,CAAC,CA4C1B;AAED,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC9C;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CA+CxC;AAED,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,WAAW,EACjB,WAAW,EAAE,MAAM,GAClB,MAAM,EAAE,CAcV;AAED,KAAK,WAAW,GAAG,MAAM,GAAG,UAAU,GAAG,YAAY,MAAM,EAAE,CAAC;AAE9D;;;GAGG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,OAAO,GAAG,MAAM,CAWjF"}

package/dist/core/add-preparation.js

@@ -0,0 +1,208 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Shared add preparation, defaults and content rendering.
+ */
+import { ItemMetadata as ItemMetadataSchema } from '../schemas/index.js';
+import { TaskWorkflowDefinition } from '../schemas/task-workflow.js';
+import { TestProfile as TestProfileSchema } from '../schemas/test-profile.js';
+import { TestWorkflowDefinition } from '../schemas/test-workflow.js';
+import { detectDiataxisType, generateDiataxisSkeleton } from '../templates/diataxis.js';
+import { generateEpicTemplate } from '../templates/epic.js';
+import { generateMadrTemplate, isMadrCandidate } from '../templates/madr.js';
+import { generateStoryTemplate } from '../templates/story.js';
+import { generateTestWorkflowTemplate } from '../templates/test-workflow.js';
+import { getCurrentTimestamp, normalizeMarkdown } from '../utils/index.js';
+import { applyClassificationGate } from './classification-gate.js';
+import { coordinationTextWarning, detectCoordinationText, handoverTagWarning, isWorkItemType, projectSlugFromDevstepsDir, } from './coordination-text.js';
+import { bodySkeleton, isDecisionOrQuestion } from './decision-question.js';
+import { decisionQuestionAddHint, initialStatus } from './decision-question-status.js';
+import { withGuideStepList } from './guide-step-list.js';
+import { assertItemTypeOffered } from './item-type-availability.js';
+import { describeZodIssues, ItemValidationError } from './item-validation.js';
+import { ProcessDefinitionVersionError } from './process-definition-hint.js';
+import { TaskWorkflowLoadError } from './task-workflow-loader.js';
+import { TestWorkflowLoadError } from './test-workflow-loader.js';
+import { assertAuthoredWorkflowV2, } from './workflow-v2-authoring.js';
+import { diagnosticMessages, writeDiagnostics } from './write-diagnostics.js';
+/**
+ * BUG-112: fail fast on a malformed v1 `process_definition` at authoring time instead of
+ * only surfacing it later at `workflow_run_start`. A `'2.0'` definition is validated by its own
+ * compiler, not here; any other `schema_version` is refused (TASK-962).
+ */
+export function validateProcessDefinitionShape(type, processDefinition) {
+    const version = processDefinition && typeof processDefinition === 'object'
+        ? processDefinition.schema_version
+        : undefined;
+    // TASK-962: an unversioned definition used to be stored and fail only at run start.
+    if (version !== '1.0' && version !== '2.0')
+        throw new ProcessDefinitionVersionError(version);
+    if (version !== '1.0')
+        return;
+    if (type === 'task') {
+        const parsed = TaskWorkflowDefinition.safeParse(processDefinition);
+        if (!parsed.success) {
+            throw new TaskWorkflowLoadError('INVALID_DEFINITION', parsed.error.message);
+        }
+    }
+    else if (type === 'test') {
+        const parsed = TestWorkflowDefinition.safeParse(processDefinition);
+        if (!parsed.success) {
+            throw new TestWorkflowLoadError('INVALID_DEFINITION', `Invalid TEST workflow definition: ${parsed.error.message}`);
+        }
+    }
+}
+function createAddMetadata(args, config, gate, now) {
+    return {
+        type: args.type,
+        category: gate.category,
+        title: args.title,
+        status: initialStatus(args.type),
+        eisenhower: args.eisenhower || 'not-urgent-important',
+        created: now,
+        updated: now,
+        author: args.assignee || config.settings.default_author,
+        assignee: args.assignee,
+        affected_paths: args.affected_paths || [],
+        linked_items: {
+            implements: [],
+            'implemented-by': [],
+            'tested-by': [],
+            tests: [],
+            blocks: [],
+            'blocked-by': [],
+            'relates-to': [],
+            'depends-on': [],
+            'required-by': [],
+            supersedes: [],
+            'superseded-by': [],
+            'canonical-for': [],
+            'derived-from': [],
+            'documented-by': [],
+            documents: [],
+        },
+        tags: gate.tags,
+        commits: [],
+        test_profile: args.test_profile,
+        process_definition: args.process_definition,
+        metadata: {},
+    };
+}
+/** Validate authoring values without allocating an ID or publishing an item. */
+export async function prepareAddItem(devstepsDir, args, config) {
+    assertItemTypeOffered(config, args.type);
+    if (args.test_profile !== undefined) {
+        if (args.type !== 'test') {
+            throw new Error('--test-profile is only valid when creating a test item.');
+        }
+        TestProfileSchema.parse(args.test_profile);
+    }
+    let diagnostics = [];
+    if (args.process_definition !== undefined) {
+        validateProcessDefinitionShape(args.type, args.process_definition);
+        diagnostics = await assertAuthoredWorkflowV2(devstepsDir, args.process_definition, `${args.type.toUpperCase()} "${args.title}"`);
+    }
+    // STORY-421: required types need a registry category and the receipt of its leaf.
+    const gate = await applyClassificationGate(devstepsDir, {
+        type: args.type,
+        title: args.title,
+        description: args.description,
+        category: args.category,
+        tags: args.tags,
+        leaf_receipt: args.leaf_receipt,
+        new_node: args.new_node,
+    });
+    const now = getCurrentTimestamp();
+    const metadata = createAddMetadata(args, config, gate, now);
+    const parsed = ItemMetadataSchema.omit({ id: true }).safeParse(metadata);
+    if (!parsed.success) {
+        const origins = args.assignee === undefined && config.settings.default_author !== undefined
+            ? { author: 'config.json settings.default_author' }
+            : {};
+        const issues = describeZodIssues(parsed.error.issues, metadata, origins);
+        throw new ItemValidationError(`Cannot write item: ${issues.join('; ')}`, issues);
+    }
+    return { args, metadata, gate, diagnostics };
+}
+/** Render from the actual allocated ID; batch descriptions are resolved before this call. */
+export function renderAddContent(args, itemId, now, options = {}) {
+    let defaultDescription = `# ${args.title}\n\n<!-- Add detailed description here -->\n`;
+    let template = 'none';
+    // TASK-413: Auto-populate MADR 4.0 template for ADR-type DOC items
+    if (args.type === 'doc' && !args.description && isMadrCandidate(args.tags || [], args.title)) {
+        defaultDescription = generateMadrTemplate(itemId, args.title, now.split('T')[0]);
+        template = 'MADR 4.0';
+    }
+    // STORY-268: Auto-populate Diataxis skeleton for DOC items (when no MADR match)
+    if (args.type === 'doc' &&
+        !args.description &&
+        defaultDescription.includes('<!-- Add detailed')) {
+        const diataxisType = detectDiataxisType(args.tags || [], args.title);
+        if (diataxisType) {
+            defaultDescription = generateDiataxisSkeleton(args.title, diataxisType);
+            template = `Diataxis ${diataxisType}`;
+        }
+    }
+    if (args.type === 'test' && args.test_profile && !args.description) {
+        defaultDescription = generateTestWorkflowTemplate(args.title, args.test_profile);
+    }
+    // EPIC-059 (design v6.1 §2): an epic starts from the epic template, and (STORY-487) a story
+    // from the story template; the gate is the type and the empty description, never a tag.
+    if (args.type === 'epic' && !args.description)
+        defaultDescription = generateEpicTemplate();
+    if (args.type === 'story' && !args.description)
+        defaultDescription = generateStoryTemplate();
+    defaultDescription = bodySkeleton(args.type, args.title) ?? defaultDescription;
+    const rawDescription = options.preserveDescription && args.description !== undefined
+        ? args.description
+        : args.description || defaultDescription;
+    const description = withGuideStepList(options.preserveDescription ? rawDescription : normalizeMarkdown(rawDescription), args.process_definition);
+    return {
+        description,
+        ...(args.type === 'doc' ? { hint: docAddHint(template, Boolean(args.description)) } : {}),
+        ...(isDecisionOrQuestion(args.type)
+            ? { hint: decisionQuestionAddHint(args.type, itemId, description, Boolean(args.description)) }
+            : {}),
+    };
+}
+export function addItemWarnings(devstepsDir, metadata, args, description) {
+    const itemId = metadata.id;
+    return [
+        ...addCoordinationWarnings(devstepsDir, metadata, args.description ? description : ''),
+        ...diagnosticMessages(writeDiagnostics({
+            operation: 'add',
+            item: { id: itemId, type: metadata.type, status: metadata.status, title: metadata.title },
+            titleChanged: true,
+            description,
+            descriptionChanged: true,
+        })),
+    ];
+}
+/**
+ * Doc guidance, returned when a doc item is created instead of carried in every request's
+ * tool schema (TASK-897): which skeleton was generated, or what generates one.
+ */
+export function docAddHint(template, hadDescription) {
+    const frontmatter = 'Frontmatter in the description (diataxis, related_items, status, author, tags) is read at read time.';
+    if (template !== 'none') {
+        return `Generated a ${template} skeleton; fill it in through update. ${frontmatter}`;
+    }
+    const how = 'A Diataxis tag (tutorial, how-to, reference, explanation, architecture, research) or a ' +
+        "title starting with 'Tutorial:', 'How to', 'Reference:', 'ADR:' or 'Research:' generates " +
+        "a skeleton when no description is sent; an adr tag or a title starting 'ADR-' or 'ADR ' gets MADR 4.0.";
+    return `${hadDescription ? 'Your description was kept.' : 'No skeleton matched.'} ${how} ${frontmatter}`;
+}
+/** BUG-153 P1/P2: a new work item tagged `handover`, or one created with coordination text. */
+function addCoordinationWarnings(devstepsDir, metadata, description) {
+    if (!isWorkItemType(metadata.type))
+        return [];
+    const findings = description
+        ? detectCoordinationText(description, { projectSlug: projectSlugFromDevstepsDir(devstepsDir) })
+        : [];
+    return [
+        handoverTagWarning(metadata.id, metadata.type, metadata.tags),
+        coordinationTextWarning(metadata.id, findings),
+    ].filter((warning) => warning !== null);
+}
+//# sourceMappingURL=add-preparation.js.map

package/dist/core/add-preparation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-preparation.js","sourceRoot":"","sources":["../../src/core/add-preparation.ts"],"names":[],"mappings":"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"}

package/dist/core/add.d.ts

@@ -5,7 +5,12 @@
  * Core add-item operation
  * Creates metadata JSON, description Markdown, and updates distributed index.
  */
-import type { DevStepsConfig, EisenhowerQuadrant, ItemMetadata, ItemType } from '../schemas/index.js';
+import type { ProcessDefinition } from '../runtime/index.js';
+import type { DevStepsConfig, EisenhowerQuadrant, ItemMetadata, ItemType, TestProfile } from '../schemas/index.js';
+import type { GateResult } from './classification-gate.js';
+import type { NewNode } from './classification-registry-ops.js';
+import type { WorkflowAuthoringDiagnostic } from './workflow-v2-authoring.js';
+export { docAddHint, validateProcessDefinitionShape } from './add-preparation.js';
 export interface AddItemArgs {
     type: ItemType;
     title: string;
@@ -15,15 +20,33 @@ export interface AddItemArgs {
     tags?: string[];
     affected_paths?: string[];
     assignee?: string;
+    test_profile?: TestProfile;
+    process_definition?: ProcessDefinition;
+    /** Receipt of the category leaf, from `list` with category or a refused add (STORY-421). */
+    leaf_receipt?: string;
+    /** Declare the category when it is missing from the registry; created as `proposed`. */
+    new_node?: NewNode;
 }
 export interface AddItemResult {
     itemId: string;
     metadata: ItemMetadata;
     config: DevStepsConfig;
+    /** Category and tags after resolution against the registry, with the notes. */
+    classification: GateResult;
+    /** Authoring warnings of a v2 process_definition; errors reject the add. */
+    diagnostics?: WorkflowAuthoringDiagnostic[];
+    /** Doc items: which template was generated (TASK-897); decision and question: their template. */
+    hint?: string;
+    /**
+     * In-band hints that never block the add: coordination state in a work item (BUG-153), and the
+     * write-time reminders such as the sections an epic lacks (EPIC-059).
+     */
+    warnings?: string[];
+    /** This add raised the type's ID counter, so `index/counters.json` changed (TASK-891). */
+    countersRaised: boolean;
 }
-/**
- * Core business logic for adding a new item to devsteps
- * Pure function that handles all file I/O and validation
- */
-export declare function addItem(devstepsDir: string, args: AddItemArgs): Promise<AddItemResult>;
+/** Create one item using the same preparation and templates as batch creation. */
+export declare function addItem(devstepsDir: string, args: AddItemArgs, options?: {
+    preserveDescription?: boolean;
+}): Promise<AddItemResult>;
 //# sourceMappingURL=add.d.ts.map

package/dist/core/add.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/core/add.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,QAAQ,EACT,MAAM,qBAAqB,CAAC;AAW7B,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,YAAY,CAAC;IACvB,MAAM,EAAE,cAAc,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CA6E5F"}
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../src/core/add.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,QAAQ,EACR,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAG3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAIhE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAE9E,OAAO,EAAE,UAAU,EAAE,8BAA8B,EAAE,MAAM,sBAAsB,CAAC;AAElF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,WAAW,CAAC;IAC3B,kBAAkB,CAAC,EAAE,iBAAiB,CAAC;IACvC,4FAA4F;IAC5F,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wFAAwF;IACxF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,YAAY,CAAC;IACvB,MAAM,EAAE,cAAc,CAAC;IACvB,+EAA+E;IAC/E,cAAc,EAAE,UAAU,CAAC;IAC3B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,2BAA2B,EAAE,CAAC;IAC5C,iGAAiG;IACjG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,0FAA0F;IAC1F,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,kFAAkF;AAClF,wBAAsB,OAAO,CAC3B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,WAAW,EACjB,OAAO,GAAE;IAAE,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC9C,OAAO,CAAC,aAAa,CAAC,CAwDxB"}