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

package/dist/core/classification-gate.js

@@ -0,0 +1,250 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The classification gate runs inside `addItem` before anything is written.
+ * For the types the registry requires, the category must resolve to a node and
+ * the caller must present the receipt of that node's leaf. Every refusal carries
+ * what the caller needs next: the nodes and their questions, the nearest names,
+ * or the current leaf with its receipt.
+ *
+ * @see STORY-421 TASK-835
+ */
+import { countOpenByCategory, getCategoryLeaf } from './classification-leaf.js';
+import { loadClassificationRegistry, UNCLASSIFIED, } from './classification-registry.js';
+import { addRegistryNode } from './classification-registry-ops.js';
+import { resolveNode } from './classification-resolve.js';
+import { bodyText, headText, roleFromStory, scoreNodes, } from './classification-score.js';
+export class ClassificationGateError extends Error {
+    gate;
+    constructor(message, gate) {
+        super(message);
+        this.name = 'ClassificationGateError';
+        this.gate = gate;
+    }
+}
+const CONCERN_PREFIX = 'concern:';
+const SUGGESTION_COUNT = 3;
+/** Concern candidates when none was passed, and a missing role on a story. */
+export function suggestFacets(registry, args, tags) {
+    const item = {
+        id: 'NEW',
+        type: args.type,
+        title: args.title ?? '',
+        tags,
+        category: args.category ?? UNCLASSIFIED,
+        affected_paths: [],
+    };
+    const out = {};
+    if (!tags.some((t) => t.startsWith(CONCERN_PREFIX))) {
+        const concern = scoreNodes(registry.concern, headText(item), bodyText(args.description ?? ''));
+        if (concern.length > 0)
+            out.concern = concern.slice(0, SUGGESTION_COUNT);
+    }
+    if (args.type === 'story' && args.title) {
+        if (roleFromStory(args.title, args.description ?? '', registry.role) === null)
+            out.role_missing = true;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function retryArguments(args, category, tags, receipt) {
+    return {
+        type: args.type,
+        ...(args.title ? { title: args.title } : {}),
+        category,
+        leaf_receipt: receipt,
+        ...(tags.length > 0 ? { tags } : {}),
+    };
+}
+function nodeList(registry, counts) {
+    return Object.entries(registry.category)
+        .filter(([, spec]) => spec.status !== 'deprecated')
+        .map(([name, spec]) => ({
+        name,
+        q: spec.q,
+        status: spec.status,
+        open_count: counts[name] ?? 0,
+    }))
+        .sort((a, b) => b.open_count - a.open_count || a.name.localeCompare(b.name));
+}
+/** `concern:` tags are resolved to canonical nodes; other tags pass untouched. */
+export function resolveConcernTags(tags, registry, notes) {
+    return tags.map((tag) => {
+        if (!tag.startsWith(CONCERN_PREFIX))
+            return tag;
+        const value = tag.slice(CONCERN_PREFIX.length);
+        const resolution = resolveNode(registry.concern, value);
+        if (resolution.kind === 'unknown') {
+            notes.push(`concern "${value}" is not a registry node and was kept as written`);
+            return tag;
+        }
+        if (resolution.via !== 'exact') {
+            notes.push(`concern "${value}" resolved to "${resolution.node}" (${resolution.via})`);
+        }
+        return `${CONCERN_PREFIX}${resolution.node}`;
+    });
+}
+/**
+ * Require the current receipt of a category's leaf. `nextFor` builds the retry step from the
+ * leaf's receipt; it defaults to the add retry, and update passes its own (BUG-236).
+ */
+export async function requireLeaf(devstepsDir, registry, args, category, tags, nextFor) {
+    const leaf = await getCategoryLeaf(devstepsDir, category, registry.digest);
+    const next = nextFor?.(leaf.leaf_receipt) ?? {
+        tool: 'add',
+        arguments: retryArguments(args, category, tags, leaf.leaf_receipt),
+    };
+    const facet_suggestions = suggestFacets(registry, args, tags);
+    if (!args.leaf_receipt) {
+        throw new ClassificationGateError(`Category "${category}" has ${leaf.open_count} open item(s); pass leaf_receipt to create here`, {
+            kind: 'missing_receipt',
+            category,
+            leaf,
+            next,
+            facet_suggestions,
+            hint: 'Read the open items listed; open one to extend it, or send `next.arguments` to create a new item at this leaf.',
+        });
+    }
+    if (args.leaf_receipt !== leaf.leaf_receipt) {
+        throw new ClassificationGateError(`The leaf of "${category}" changed since it was read; review it and pass the new leaf_receipt`, {
+            kind: 'stale_receipt',
+            category,
+            leaf,
+            next,
+            facet_suggestions,
+            hint: `The receipt no longer matches the definition or open goal item IDs of category "${category}". Receipts are opaque, so the previous changed field cannot be reconstructed. Review this leaf and its category definition, then send \`next.arguments\`.`,
+        });
+    }
+    return leaf;
+}
+/**
+ * Create the node `new_node` declares, beside a near node a fuzzy match found (BUG-234). The
+ * first declared node creates the project registry, which turns the gate on (BUG-231, BUG-232).
+ */
+function declareNode(devstepsDir, ctx, newNode, near) {
+    const { registry, args, given, tags, notes } = ctx;
+    const node = addRegistryNode(devstepsDir, 'category', given, newNode);
+    if (registry.source !== 'project') {
+        const types = (registry.required.category ?? []).join(', ');
+        notes.push(`created .devsteps/classification.json; from now on ${types} need a category`);
+    }
+    notes.push(near
+        ? `category "${node}" created as proposed beside the near node "${near}"`
+        : `category "${node}" created as proposed`);
+    return {
+        category: node,
+        tags,
+        resolutions: notes,
+        created_nodes: [node],
+        leaf: { open_count: 0, delivered_count: 0, retired_count: 0 },
+        facet_suggestions: suggestFacets(registry, args, tags),
+    };
+}
+/** Note how a category resolved, and that `new_node` gave way to an existing node. */
+function noteResolution(ctx, node, via) {
+    if (via !== 'exact')
+        ctx.notes.push(`category "${ctx.given}" resolved to "${node}" (${via})`);
+    if (ctx.args.new_node)
+        ctx.notes.push(`new_node not used: category "${node}" already exists`);
+}
+/** A type the registry does not require: resolve what was given, or declare it with new_node. */
+function openGate(devstepsDir, ctx) {
+    const { registry, args, given, tags, notes } = ctx;
+    if (!given || given === UNCLASSIFIED) {
+        if (args.new_node) {
+            throw new ClassificationGateError('new_node declares the category named in category', {
+                kind: 'missing_category',
+                next: { tool: 'add', supply: 'category: the name of the node new_node declares' },
+                hint: 'Pass category with the new node name together with new_node.',
+            });
+        }
+        return { category: UNCLASSIFIED, tags, resolutions: notes, created_nodes: [] };
+    }
+    const resolution = resolveNode(registry.category, given);
+    if (resolution.kind === 'resolved' && !(args.new_node && resolution.via === 'fuzzy')) {
+        noteResolution(ctx, resolution.node, resolution.via);
+        return { category: resolution.node, tags, resolutions: notes, created_nodes: [] };
+    }
+    if (args.new_node) {
+        const near = resolution.kind === 'resolved' ? resolution.node : undefined;
+        return declareNode(devstepsDir, ctx, args.new_node, near);
+    }
+    return { category: given, tags, resolutions: notes, created_nodes: [] };
+}
+/** Resolve category and tags for a new item; throws ClassificationGateError with the next step. */
+export async function applyClassificationGate(devstepsDir, args) {
+    const registry = loadClassificationRegistry(devstepsDir);
+    const notes = [];
+    const created = [];
+    const tags = resolveConcernTags(args.tags ?? [], registry, notes);
+    // Without a project registry there are no nodes to require; the gate stays open.
+    const required = registry.source === 'project' && (registry.required.category ?? []).includes(args.type);
+    const given = args.category?.trim() ?? '';
+    const ctx = { registry, args, given, tags, notes };
+    if (!required)
+        return openGate(devstepsDir, ctx);
+    if (!given || given === UNCLASSIFIED) {
+        const counts = await countOpenByCategory(devstepsDir);
+        throw new ClassificationGateError(`A ${args.type} needs a category from .devsteps/classification.json`, {
+            kind: 'missing_category',
+            nodes: nodeList(registry, counts),
+            next: {
+                tool: 'add',
+                supply: 'category: one of nodes[].name, or new_node { q, aliases } for a missing one',
+            },
+            facet_suggestions: suggestFacets(registry, args, tags),
+            hint: 'Pass category with the node whose question you answer with yes; pass new_node (q, aliases) to declare one that is missing.',
+        });
+    }
+    const resolution = resolveNode(registry.category, given);
+    // A declared node beats a fuzzy match; exact and alias matches keep their node (BUG-234).
+    if (args.new_node && (resolution.kind === 'unknown' || resolution.via === 'fuzzy')) {
+        const near = resolution.kind === 'resolved' ? resolution.node : undefined;
+        return declareNode(devstepsDir, ctx, args.new_node, near);
+    }
+    if (resolution.kind === 'unknown') {
+        const counts = await countOpenByCategory(devstepsDir);
+        const candidates = resolution.candidates.map((c) => ({
+            name: c.node,
+            q: registry.category[c.node]?.q,
+            status: registry.category[c.node]?.status,
+            open_count: counts[c.node] ?? 0,
+        }));
+        throw new ClassificationGateError(`Unknown category "${given}"`, {
+            kind: 'unknown_category',
+            category: given,
+            candidates,
+            nodes: candidates.length === 0 ? nodeList(registry, counts) : undefined,
+            next: {
+                tool: 'add',
+                supply: `category: one of candidates[].name, or new_node { q, aliases } to declare "${given}"`,
+            },
+            hint: 'Use one of the candidates, or pass new_node with a question and at least two aliases to declare the category.',
+        });
+    }
+    const spec = registry.category[resolution.node];
+    if (spec.status === 'deprecated') {
+        throw new ClassificationGateError(`Category "${resolution.node}" is deprecated`, {
+            kind: 'deprecated_category',
+            category: resolution.node,
+            successors: spec.superseded_by ?? [],
+            next: { tool: 'add', supply: 'category: one of successors' },
+            hint: 'Choose one of the successors.',
+        });
+    }
+    noteResolution(ctx, resolution.node, resolution.via);
+    const leaf = await requireLeaf(devstepsDir, registry, args, resolution.node, tags);
+    return {
+        category: resolution.node,
+        tags,
+        resolutions: notes,
+        created_nodes: created,
+        leaf: {
+            open_count: leaf.open_count,
+            delivered_count: leaf.delivered_count,
+            retired_count: leaf.retired_count,
+        },
+        facet_suggestions: suggestFacets(registry, args, tags),
+    };
+}
+//# sourceMappingURL=classification-gate.js.map

package/dist/core/classification-gate.js.map

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

package/dist/core/classification-leaf.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The leaf of a category: every open item that carries it, the closed counts,
+ * and a receipt bound to its own category definition and open goal IDs. Changes
+ * elsewhere in the registry never invalidate it (STORY-522).
+ *
+ * @see STORY-421 TASK-834
+ */
+import type { ItemStatus, ItemType } from '../schemas/index.js';
+export interface LeafItem {
+    id: string;
+    type: ItemType;
+    status: ItemStatus;
+    title: string;
+    tags: string[];
+    /** First sentence of the description, so overlap is judged without a `get` per item. */
+    summary?: string;
+}
+/** The first sentence of a description without its heading, markup or template comment. */
+export declare function summarize(description: string): string;
+/**
+ * The summary without the part that repeats the title (TASK-1015): a user story opens its
+ * description with its own title, so only the rest ("so that …") is new. Empty when nothing is.
+ */
+export declare function leafSummary(title: string, description: string): string;
+export interface CategoryLeaf {
+    category: string;
+    open: LeafItem[];
+    open_count: number;
+    delivered_count: number;
+    retired_count: number;
+    leaf_receipt: string;
+}
+/** The first input is a category-local definition digest, never the whole registry's digest. */
+export declare function leafReceipt(nodeDigest: string, category: string, openIds: string[]): string;
+/**
+ * The goal-level items of a category (the types the gate requires), split into
+ * the open list and the closed counts. Tasks and bugs inherit their category
+ * and would only churn the receipt.
+ *
+ * `_registryDigest` remains for source compatibility; the current own node is read from disk.
+ */
+export declare function getCategoryLeaf(devstepsDir: string, category: string, _registryDigest: string, types?: readonly string[]): Promise<CategoryLeaf>;
+/** Current own-node/membership receipt; the legacy registry digest argument is ignored. */
+export declare function currentLeafReceipt(devstepsDir: string, category: string, _registryDigest: string, types?: readonly string[]): Promise<string>;
+/** Open item counts per category, for the node lists a refusal carries. */
+export declare function countOpenByCategory(devstepsDir: string): Promise<Record<string, number>>;
+//# sourceMappingURL=classification-leaf.d.ts.map

package/dist/core/classification-leaf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classification-leaf.d.ts","sourceRoot":"","sources":["../../src/core/classification-leaf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAWhE,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,2FAA2F;AAC3F,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAarD;AASD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAOtE;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAQ3F;AAgBD;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,KAAK,GAAE,SAAS,MAAM,EAA8B,GACnD,OAAO,CAAC,YAAY,CAAC,CAqCvB;AAED,2FAA2F;AAC3F,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,EACvB,KAAK,GAAE,SAAS,MAAM,EAA8B,GACnD,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED,2EAA2E;AAC3E,wBAAsB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAQ9F"}

package/dist/core/classification-leaf.js

@@ -0,0 +1,134 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The leaf of a category: every open item that carries it, the closed counts,
+ * and a receipt bound to its own category definition and open goal IDs. Changes
+ * elsewhere in the registry never invalidate it (STORY-522).
+ *
+ * @see STORY-421 TASK-834
+ */
+import { createHash } from 'node:crypto';
+import { DEFAULT_REQUIRED } from './classification-defaults.js';
+import { canonicalJson, loadClassificationRegistry } from './classification-registry.js';
+import { getItem } from './get.js';
+import { listItems } from './list.js';
+const OPEN = new Set(['draft', 'planned', 'in-progress', 'review', 'blocked']);
+const DELIVERED = new Set(['done']);
+const RECEIPT_LENGTH = 16;
+const SUMMARY_CHARS = 160;
+/** The first sentence of a description without its heading, markup or template comment. */
+export function summarize(description) {
+    const text = description
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .replace(/^#[^\n]*\n/, '')
+        .replace(/^\s*#{1,6}[^\n]*\n/gm, '')
+        .replace(/[*`>]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (text.length === 0)
+        return '';
+    const end = text.search(/[.!?](\s|$)/);
+    const sentence = end > 0 && end < SUMMARY_CHARS ? text.slice(0, end + 1) : text.slice(0, SUMMARY_CHARS);
+    return sentence.trim();
+}
+const LEADING_PUNCTUATION = /^[\s.,;:!?–—-]+/;
+const EDGE_PUNCTUATION = /^[\s.,;:!?–—-]+|[\s.,;:!?–—-]+$/g;
+function plain(text) {
+    return text.replace(/[*`>]/g, '').replace(/\s+/g, ' ').replace(EDGE_PUNCTUATION, '');
+}
+/**
+ * The summary without the part that repeats the title (TASK-1015): a user story opens its
+ * description with its own title, so only the rest ("so that …") is new. Empty when nothing is.
+ */
+export function leafSummary(title, description) {
+    const summary = summarize(description);
+    const head = plain(title).toLowerCase();
+    const lower = summary.toLowerCase();
+    if (head.length === 0)
+        return summary;
+    if (lower.startsWith(head))
+        return summary.slice(head.length).replace(LEADING_PUNCTUATION, '');
+    return head.startsWith(plain(summary).toLowerCase()) ? '' : summary;
+}
+/** The first input is a category-local definition digest, never the whole registry's digest. */
+export function leafReceipt(nodeDigest, category, openIds) {
+    const material = canonicalJson({
+        version: 2,
+        category,
+        node: nodeDigest,
+        open_ids: [...new Set(openIds)].sort(),
+    });
+    return createHash('sha256').update(material).digest('hex').slice(0, RECEIPT_LENGTH);
+}
+/** Canonical semantic node fields; ordering and creation timestamps carry no leaf meaning. */
+function categoryNodeDigest(devstepsDir, category) {
+    const node = loadClassificationRegistry(devstepsDir).category[category];
+    const definition = node
+        ? {
+            q: node.q,
+            aliases: [...new Set(node.aliases)].sort(),
+            status: node.status ?? 'confirmed',
+            superseded_by: [...new Set(node.superseded_by ?? [])].sort(),
+        }
+        : null;
+    return createHash('sha256').update(canonicalJson(definition)).digest('hex');
+}
+/**
+ * The goal-level items of a category (the types the gate requires), split into
+ * the open list and the closed counts. Tasks and bugs inherit their category
+ * and would only churn the receipt.
+ *
+ * `_registryDigest` remains for source compatibility; the current own node is read from disk.
+ */
+export async function getCategoryLeaf(devstepsDir, category, _registryDigest, types = DEFAULT_REQUIRED.category) {
+    const all = await listItems(devstepsDir, { category });
+    const items = all.items.filter((i) => types.includes(i.type));
+    const open = await Promise.all(items
+        .filter((i) => OPEN.has(i.status))
+        .sort((a, b) => a.id.localeCompare(b.id, undefined, { numeric: true }))
+        .map(async (i) => {
+        const base = {
+            id: i.id,
+            type: i.type,
+            status: i.status,
+            title: i.title,
+            tags: i.tags ?? [],
+        };
+        try {
+            const summary = leafSummary(i.title, (await getItem(devstepsDir, i.id)).description);
+            return summary ? { ...base, summary } : base;
+        }
+        catch {
+            return base;
+        }
+    }));
+    const delivered = items.filter((i) => DELIVERED.has(i.status)).length;
+    const retired = items.length - open.length - delivered;
+    return {
+        category,
+        open,
+        open_count: open.length,
+        delivered_count: delivered,
+        retired_count: retired,
+        leaf_receipt: leafReceipt(categoryNodeDigest(devstepsDir, category), category, open.map((i) => i.id)),
+    };
+}
+/** Current own-node/membership receipt; the legacy registry digest argument is ignored. */
+export async function currentLeafReceipt(devstepsDir, category, _registryDigest, types = DEFAULT_REQUIRED.category) {
+    const { items } = await listItems(devstepsDir, { category });
+    const open = items.filter((i) => types.includes(i.type) && OPEN.has(i.status));
+    return leafReceipt(categoryNodeDigest(devstepsDir, category), category, open.map((i) => i.id));
+}
+/** Open item counts per category, for the node lists a refusal carries. */
+export async function countOpenByCategory(devstepsDir) {
+    const { items } = await listItems(devstepsDir, {});
+    const counts = {};
+    for (const item of items) {
+        if (!OPEN.has(item.status) || !item.category)
+            continue;
+        counts[item.category] = (counts[item.category] ?? 0) + 1;
+    }
+    return counts;
+}
+//# sourceMappingURL=classification-leaf.js.map

package/dist/core/classification-leaf.js.map

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

package/dist/core/classification-registry-action.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * One entry point over the registry node operations, shared by the MCP `classification` tool and
+ * the CLI `classification` command: validates the input of one action, runs it and states what
+ * changed.
+ *
+ * @see BUG-233
+ */
+import { type MutableFacet } from './classification-registry-ops.js';
+export declare const REGISTRY_ACTIONS: readonly ['add', 'confirm', 'rename', 'deprecate'];
+export type RegistryAction = (typeof REGISTRY_ACTIONS)[number];
+export declare const REGISTRY_FACETS: readonly ['category', 'concern', 'activity'];
+export interface RegistryActionInput {
+    action: RegistryAction;
+    facet?: MutableFacet;
+    name: string;
+    q?: string;
+    aliases?: string[];
+    to?: string;
+    successors?: string[];
+}
+export interface RegistryActionResult {
+    action: RegistryAction;
+    facet: MutableFacet;
+    node: string;
+    status?: string;
+    /** Rename only: the items whose category was rewritten. */
+    rewritten?: string[];
+    message: string;
+}
+export declare function runRegistryAction(devstepsDir: string, input: RegistryActionInput): Promise<RegistryActionResult>;
+//# sourceMappingURL=classification-registry-action.d.ts.map

package/dist/core/classification-registry-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classification-registry-action.d.ts","sourceRoot":"","sources":["../../src/core/classification-registry-action.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAIL,KAAK,YAAY,EAElB,MAAM,kCAAkC,CAAC;AAE1C,eAAO,MAAM,gBAAgB,YAAI,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAU,CAAC;AACnF,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC/D,eAAO,MAAM,eAAe,YAAI,UAAU,EAAE,SAAS,EAAE,UAAU,CAAU,CAAC;AAE5E,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AASD,wBAAsB,iBAAiB,CACrC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAsD/B"}

package/dist/core/classification-registry-action.js

@@ -0,0 +1,71 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * One entry point over the registry node operations, shared by the MCP `classification` tool and
+ * the CLI `classification` command: validates the input of one action, runs it and states what
+ * changed.
+ *
+ * @see BUG-233
+ */
+import { ClassificationRegistryError } from './classification-registry.js';
+import { addRegistryNode, confirmRegistryNode, deprecateRegistryNode, renameRegistryNode, } from './classification-registry-ops.js';
+export const REGISTRY_ACTIONS = ['add', 'confirm', 'rename', 'deprecate'];
+export const REGISTRY_FACETS = ['category', 'concern', 'activity'];
+function need(value, label, action) {
+    if (!value || value.trim().length === 0) {
+        throw new ClassificationRegistryError(`Action "${action}" needs ${label}`);
+    }
+    return value;
+}
+export async function runRegistryAction(devstepsDir, input) {
+    const facet = input.facet ?? 'category';
+    const { action, name } = input;
+    need(name, 'name', action);
+    switch (action) {
+        case 'add': {
+            const node = addRegistryNode(devstepsDir, facet, name, {
+                q: need(input.q, 'q (the node question)', action),
+                aliases: input.aliases ?? [],
+            });
+            return {
+                action,
+                facet,
+                node,
+                status: 'proposed',
+                message: `Added ${facet} node "${node}" as proposed`,
+            };
+        }
+        case 'confirm':
+            confirmRegistryNode(devstepsDir, facet, name);
+            return {
+                action,
+                facet,
+                node: name,
+                status: 'confirmed',
+                message: `Confirmed ${facet} node "${name}"`,
+            };
+        case 'deprecate':
+            deprecateRegistryNode(devstepsDir, facet, name, input.successors ?? []);
+            return {
+                action,
+                facet,
+                node: name,
+                status: 'deprecated',
+                message: `Deprecated ${facet} node "${name}"`,
+            };
+        case 'rename': {
+            const { node, rewritten } = await renameRegistryNode(devstepsDir, facet, name, need(input.to, 'to (the new name)', action));
+            return {
+                action,
+                facet,
+                node,
+                rewritten,
+                message: `Renamed ${facet} node "${name}" to "${node}"; rewrote ${rewritten.length} item(s)`,
+            };
+        }
+        default:
+            throw new ClassificationRegistryError(`Unknown action "${String(action)}"`);
+    }
+}
+//# sourceMappingURL=classification-registry-action.js.map

package/dist/core/classification-registry-action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"classification-registry-action.js","sourceRoot":"","sources":["../../src/core/classification-registry-action.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,qBAAqB,EAErB,kBAAkB,GACnB,MAAM,kCAAkC,CAAC;AAE1C,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAU,CAAC;AAEnF,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,UAAU,EAAE,SAAS,EAAE,UAAU,CAAU,CAAC;AAsB5E,SAAS,IAAI,CAAC,KAAyB,EAAE,KAAa,EAAE,MAAc;IACpE,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,2BAA2B,CAAC,WAAW,MAAM,WAAW,KAAK,EAAE,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,WAAmB,EACnB,KAA0B;IAE1B,MAAM,KAAK,GAAiB,KAAK,CAAC,KAAK,IAAI,UAAU,CAAC;IACtD,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IAC/B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,GAAG,eAAe,CAAC,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE;gBACrD,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,uBAAuB,EAAE,MAAM,CAAC;gBACjD,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;aAC7B,CAAC,CAAC;YACH,OAAO;gBACL,MAAM;gBACN,KAAK;gBACL,IAAI;gBACJ,MAAM,EAAE,UAAU;gBAClB,OAAO,EAAE,SAAS,KAAK,UAAU,IAAI,eAAe;aACrD,CAAC;QACJ,CAAC;QACD,KAAK,SAAS;YACZ,mBAAmB,CAAC,WAAW,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;YAC9C,OAAO;gBACL,MAAM;gBACN,KAAK;gBACL,IAAI,EAAE,IAAI;gBACV,MAAM,EAAE,WAAW;gBACnB,OAAO,EAAE,aAAa,KAAK,UAAU,IAAI,GAAG;aAC7C,CAAC;QACJ,KAAK,WAAW;YACd,qBAAqB,CAAC,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;YACxE,OAAO;gBACL,MAAM;gBACN,KAAK;gBACL,IAAI,EAAE,IAAI;gBACV,MAAM,EAAE,YAAY;gBACpB,OAAO,EAAE,cAAc,KAAK,UAAU,IAAI,GAAG;aAC9C,CAAC;QACJ,KAAK,QAAQ,EAAE,CAAC;YACd,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,MAAM,kBAAkB,CAClD,WAAW,EACX,KAAK,EACL,IAAI,EACJ,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,mBAAmB,EAAE,MAAM,CAAC,CAC5C,CAAC;YACF,OAAO;gBACL,MAAM;gBACN,KAAK;gBACL,IAAI;gBACJ,SAAS;gBACT,OAAO,EAAE,WAAW,KAAK,UAAU,IAAI,SAAS,IAAI,cAAc,SAAS,CAAC,MAAM,UAAU;aAC7F,CAAC;QACJ,CAAC;QACD;YACE,MAAM,IAAI,2BAA2B,CAAC,mBAAmB,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChF,CAAC;AACH,CAAC"}

package/dist/core/classification-registry-ops.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Registry node operations and node resolution. Growth is never refused: a
+ * session adds a node as `proposed`, a person confirms, renames, merges or
+ * deprecates it, and every change rewrites the file atomically. A category
+ * rename also rewrites the `category` field of every item that carried it.
+ *
+ * @see STORY-421 TASK-834
+ */
+export type MutableFacet = 'category' | 'concern' | 'activity';
+export interface NewNode {
+    q: string;
+    aliases: string[];
+}
+/** Add a node as `proposed`; a name or an alias that exists in the facet is refused. */
+export declare function addRegistryNode(devstepsDir: string, facet: MutableFacet, name: string, spec: NewNode): string;
+export declare function confirmRegistryNode(devstepsDir: string, facet: MutableFacet, name: string): void;
+/** Mark a node deprecated with its successors; existing items keep it, new ones may not use it. */
+export declare function deprecateRegistryNode(devstepsDir: string, facet: MutableFacet, name: string, successors: string[]): void;
+/**
+ * Rename `from` to `to`; when `to` exists the two merge. The old name stays as
+ * an alias, and for categories every item carrying `from` is rewritten.
+ */
+export declare function renameRegistryNode(devstepsDir: string, facet: MutableFacet, from: string, to: string): Promise<{
+    node: string;
+    rewritten: string[];
+}>;
+//# sourceMappingURL=classification-registry-ops.d.ts.map

package/dist/core/classification-registry-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classification-registry-ops.d.ts","sourceRoot":"","sources":["../../src/core/classification-registry-ops.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAaH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAC;AAa/D,MAAM,WAAW,OAAO;IACtB,CAAC,EAAE,MAAM,CAAC;IACV,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAmBD,wFAAwF;AACxF,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,MAAM,CA8BR;AAED,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAOhG;AAED,mGAAmG;AACnG,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAAE,GACnB,IAAI,CAaN;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAwBhD"}