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

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

@@ -0,0 +1,122 @@
+/**
+ * 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
+ */
+import { ClassificationRegistryError, readClassificationFile, writeClassificationFile, } from './classification-registry.js';
+import { resolveNode, slugify } from './classification-resolve.js';
+import { listItems } from './list.js';
+import { updateItem } from './update.js';
+function loadFile(devstepsDir) {
+    return readClassificationFile(devstepsDir) ?? { version: 1, category: {}, component: {} };
+}
+function facetOf(file, facet) {
+    if (facet === 'category')
+        return file.category;
+    const nodes = file[facet] ?? {};
+    file[facet] = nodes;
+    return nodes;
+}
+/** The first alias that equals a node name or an alias already in the facet (BUG-235). */
+function aliasClash(nodes, aliases) {
+    const owners = new Map();
+    for (const [name, spec] of Object.entries(nodes)) {
+        owners.set(name, name);
+        for (const alias of spec.aliases)
+            owners.set(slugify(alias), name);
+    }
+    for (const alias of aliases) {
+        const owner = owners.get(slugify(alias));
+        if (owner)
+            return { alias, owner };
+    }
+    return undefined;
+}
+/** Add a node as `proposed`; a name or an alias that exists in the facet is refused. */
+export function addRegistryNode(devstepsDir, facet, name, spec) {
+    const node = slugify(name);
+    if (node.length === 0)
+        throw new ClassificationRegistryError(`Node name "${name}" is empty`);
+    if (spec.q.trim().length === 0 || spec.aliases.length < 2) {
+        throw new ClassificationRegistryError(`Node "${node}" needs a question and at least two aliases`);
+    }
+    const file = loadFile(devstepsDir);
+    const nodes = facetOf(file, facet);
+    const existing = resolveNode(nodes, node);
+    if (existing.kind === 'resolved' && existing.via !== 'fuzzy') {
+        throw new ClassificationRegistryError(`Node "${node}" already exists in ${facet} as "${existing.node}"`);
+    }
+    const clash = aliasClash(nodes, spec.aliases);
+    if (clash) {
+        throw new ClassificationRegistryError(`Alias "${clash.alias}" of "${node}" is already used in ${facet} by "${clash.owner}"`);
+    }
+    nodes[node] = {
+        q: spec.q.trim(),
+        aliases: spec.aliases.map((a) => a.trim()).filter(Boolean),
+        status: 'proposed',
+        created: new Date().toISOString(),
+    };
+    writeClassificationFile(devstepsDir, file);
+    return node;
+}
+export function confirmRegistryNode(devstepsDir, facet, name) {
+    const file = loadFile(devstepsDir);
+    const nodes = facetOf(file, facet);
+    const node = nodes[slugify(name)];
+    if (!node)
+        throw new ClassificationRegistryError(`Node "${name}" not found in ${facet}`);
+    node.status = 'confirmed';
+    writeClassificationFile(devstepsDir, file);
+}
+/** Mark a node deprecated with its successors; existing items keep it, new ones may not use it. */
+export function deprecateRegistryNode(devstepsDir, facet, name, successors) {
+    const file = loadFile(devstepsDir);
+    const nodes = facetOf(file, facet);
+    const key = slugify(name);
+    const node = nodes[key];
+    if (!node)
+        throw new ClassificationRegistryError(`Node "${name}" not found in ${facet}`);
+    const unknown = successors.map(slugify).filter((s) => !(s in nodes));
+    if (unknown.length > 0) {
+        throw new ClassificationRegistryError(`Unknown successor(s): ${unknown.join(', ')}`);
+    }
+    node.status = 'deprecated';
+    node.superseded_by = successors.map(slugify);
+    writeClassificationFile(devstepsDir, file);
+}
+/**
+ * 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 async function renameRegistryNode(devstepsDir, facet, from, to) {
+    const file = loadFile(devstepsDir);
+    const nodes = facetOf(file, facet);
+    const source = slugify(from);
+    const target = slugify(to);
+    const old = nodes[source];
+    if (!old)
+        throw new ClassificationRegistryError(`Node "${from}" not found in ${facet}`);
+    if (source === target)
+        return { node: target, rewritten: [] };
+    const merged = nodes[target] ?? { q: old.q, aliases: [], status: old.status };
+    merged.aliases = [...new Set([...merged.aliases, ...old.aliases, source])];
+    nodes[target] = merged;
+    delete nodes[source];
+    writeClassificationFile(devstepsDir, file);
+    const rewritten = [];
+    if (facet === 'category') {
+        const { items } = await listItems(devstepsDir, { category: source });
+        for (const item of items) {
+            await updateItem(devstepsDir, { id: item.id, category: target }, { skipLeafReceipt: true });
+            rewritten.push(item.id);
+        }
+    }
+    return { node: target, rewritten };
+}
+//# sourceMappingURL=classification-registry-ops.js.map

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

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

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

@@ -0,0 +1,132 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Classification registry: the five facet questions and their nodes.
+ *
+ * `category` and `component` are project-specific and come from
+ * `.devsteps/classification.json`. `concern`, `activity` and `role` ship as
+ * built-in defaults (ISO/IEC 25010:2023, a reduced SWEBOK list, the user-story
+ * role vocabulary) and a project file may extend or override them.
+ *
+ * @see STORY-420 TASK-828
+ */
+import { z } from 'zod';
+import { DEFAULT_ACTIVITIES, DEFAULT_CONCERNS, DEFAULT_REQUIRED, DEFAULT_ROLES } from './classification-defaults.js';
+export { DEFAULT_ACTIVITIES, DEFAULT_CONCERNS, DEFAULT_REQUIRED, DEFAULT_ROLES };
+export declare const CLASSIFICATION_FILE = "classification.json";
+/** The item field `category` is the classification key; `general` means unclassified. */
+export declare const UNCLASSIFIED = "general";
+export declare const FACET_QUESTIONS: {
+    readonly category: 'Which product area is this about?';
+    readonly component: 'Where in the system does the change land?';
+    readonly concern: 'Which cross-cutting quality or operational property is at stake?';
+    readonly activity: 'What kind of engineering work is it?';
+    readonly role: 'Who benefits?';
+};
+export type FacetKey = keyof typeof FACET_QUESTIONS;
+export declare const NodeStatus: z.ZodEnum<{
+    confirmed: "confirmed";
+    deprecated: "deprecated";
+    proposed: "proposed";
+}>;
+export type NodeStatus = z.infer<typeof NodeStatus>;
+declare const FacetNodeSchema: z.ZodObject<{
+    q: z.ZodOptional<z.ZodString>;
+    aliases: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        confirmed: "confirmed";
+        deprecated: "deprecated";
+        proposed: "proposed";
+    }>>;
+    superseded_by: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    created: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const ActivityNodeSchema: z.ZodObject<{
+    q: z.ZodOptional<z.ZodString>;
+    aliases: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        confirmed: "confirmed";
+        deprecated: "deprecated";
+        proposed: "proposed";
+    }>>;
+    superseded_by: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    created: z.ZodOptional<z.ZodString>;
+    types: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    default_for: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const ClassificationFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    category: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        q: z.ZodOptional<z.ZodString>;
+        aliases: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        status: z.ZodOptional<z.ZodEnum<{
+            confirmed: "confirmed";
+            deprecated: "deprecated";
+            proposed: "proposed";
+        }>>;
+        superseded_by: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        created: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    component: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    concern: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        q: z.ZodOptional<z.ZodString>;
+        aliases: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        status: z.ZodOptional<z.ZodEnum<{
+            confirmed: "confirmed";
+            deprecated: "deprecated";
+            proposed: "proposed";
+        }>>;
+        superseded_by: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        created: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    activity: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        q: z.ZodOptional<z.ZodString>;
+        aliases: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        status: z.ZodOptional<z.ZodEnum<{
+            confirmed: "confirmed";
+            deprecated: "deprecated";
+            proposed: "proposed";
+        }>>;
+        superseded_by: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        created: z.ZodOptional<z.ZodString>;
+        types: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        default_for: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    role: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    required: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+}, z.core.$strict>;
+export type FacetNode = z.infer<typeof FacetNodeSchema>;
+export type ActivityNode = z.infer<typeof ActivityNodeSchema>;
+export type ClassificationFile = z.infer<typeof ClassificationFileSchema>;
+export interface ClassificationRegistry {
+    /** `project` when `.devsteps/classification.json` exists, else `defaults`. */
+    source: 'defaults' | 'project';
+    path: string;
+    /** SHA-256 over the canonical registry; leaf receipts independently hash their own node. */
+    digest: string;
+    /** facet → item types that must carry a registry node. */
+    required: Record<string, string[]>;
+    category: Record<string, FacetNode>;
+    component: Record<string, string[]>;
+    concern: Record<string, FacetNode>;
+    activity: Record<string, ActivityNode>;
+    role: Record<string, string[]>;
+}
+export declare class ClassificationRegistryError extends Error {
+    readonly issues: readonly string[];
+    constructor(message: string, issues?: readonly string[]);
+}
+/** Stable serialisation: keys sorted at every level, so digests survive re-ordering. */
+export declare function canonicalJson(value: unknown): string;
+/** Read and validate the project file; null when it does not exist. */
+export declare function readClassificationFile(devstepsDir: string): ClassificationFile | null;
+/** Write the project file atomically; every registry mutation goes through here. */
+export declare function writeClassificationFile(devstepsDir: string, file: ClassificationFile): void;
+/**
+ * Load the registry for a workspace. Without a project file the built-in
+ * facets apply and `category`/`component` stay empty; an invalid file is an
+ * error that names the offending fields, never a silent fallback.
+ */
+export declare function loadClassificationRegistry(devstepsDir: string): ClassificationRegistry;
+//# sourceMappingURL=classification-registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"classification-registry.d.ts","sourceRoot":"","sources":["../../src/core/classification-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACd,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,aAAa,EAAE,CAAC;AAEjF,eAAO,MAAM,mBAAmB,wBAAwB,CAAC;AAEzD,yFAAyF;AACzF,eAAO,MAAM,YAAY,YAAY,CAAC;AAEtC,eAAO,MAAM,eAAe;aAC1B,QAAQ,EAAE,mCAAmC;aAC7C,SAAS,EAAE,2CAA2C;aACtD,OAAO,EAAE,kEAAkE;aAC3E,QAAQ,EAAE,sCAAsC;aAChD,IAAI,EAAE,eAAe;CACb,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,eAAe,CAAC;AAEpD,eAAO,MAAM,UAAU;;;;EAAkD,CAAC;AAC1E,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,QAAA,MAAM,eAAe;;;;;;;;;;iBASnB,CAAC;AAEH,QAAA,MAAM,kBAAkB;;;;;;;;;;;;iBAKtB,CAAC;AAEH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAY1B,CAAC;AAEZ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AACxD,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC9D,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,4FAA4F;IAC5F,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACvC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAChC;AAED,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAEnC,YAAY,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,SAAS,MAAM,EAAO,EAI1D;CACF;AAED,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAUpD;AAyBD,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAqBrF;AAED,oFAAoF;AACpF,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,GAAG,IAAI,CAE3F;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,sBAAsB,CAatF"}

package/dist/core/classification-registry.js

@@ -0,0 +1,141 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Classification registry: the five facet questions and their nodes.
+ *
+ * `category` and `component` are project-specific and come from
+ * `.devsteps/classification.json`. `concern`, `activity` and `role` ship as
+ * built-in defaults (ISO/IEC 25010:2023, a reduced SWEBOK list, the user-story
+ * role vocabulary) and a project file may extend or override them.
+ *
+ * @see STORY-420 TASK-828
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { writeJsonAtomic } from '../utils/atomic-write.js';
+import { DEFAULT_ACTIVITIES, DEFAULT_CONCERNS, DEFAULT_REQUIRED, DEFAULT_ROLES, } from './classification-defaults.js';
+export { DEFAULT_ACTIVITIES, DEFAULT_CONCERNS, DEFAULT_REQUIRED, DEFAULT_ROLES };
+export const CLASSIFICATION_FILE = 'classification.json';
+/** The item field `category` is the classification key; `general` means unclassified. */
+export const UNCLASSIFIED = 'general';
+export const FACET_QUESTIONS = {
+    category: 'Which product area is this about?',
+    component: 'Where in the system does the change land?',
+    concern: 'Which cross-cutting quality or operational property is at stake?',
+    activity: 'What kind of engineering work is it?',
+    role: 'Who benefits?',
+};
+export const NodeStatus = z.enum(['proposed', 'confirmed', 'deprecated']);
+const FacetNodeSchema = z.object({
+    /** The question an author answers with "yes" before choosing this node. */
+    q: z.string().optional(),
+    aliases: z.array(z.string()).default([]),
+    /** Absent means confirmed: a node written by hand into the file is a decision. */
+    status: NodeStatus.optional(),
+    /** Successors of a deprecated node. */
+    superseded_by: z.array(z.string()).optional(),
+    created: z.string().optional(),
+});
+const ActivityNodeSchema = FacetNodeSchema.extend({
+    /** Item types that decide this activity outright (spike → research). */
+    types: z.array(z.string()).optional(),
+    /** Item types that fall back to this activity when no alias matches. */
+    default_for: z.array(z.string()).optional(),
+});
+export const ClassificationFileSchema = z
+    .object({
+    version: z.literal(1),
+    category: z.record(z.string(), FacetNodeSchema).default({}),
+    /** node → path prefixes; a path belongs to the node when it starts with one of them */
+    component: z.record(z.string(), z.array(z.string())).default({}),
+    concern: z.record(z.string(), FacetNodeSchema).optional(),
+    activity: z.record(z.string(), ActivityNodeSchema).optional(),
+    role: z.record(z.string(), z.array(z.string())).optional(),
+    /** facet → item types that must carry a registry node; overrides DEFAULT_REQUIRED. */
+    required: z.record(z.string(), z.array(z.string())).optional(),
+})
+    .strict();
+export class ClassificationRegistryError extends Error {
+    issues;
+    constructor(message, issues = []) {
+        super(message);
+        this.name = 'ClassificationRegistryError';
+        this.issues = issues;
+    }
+}
+/** Stable serialisation: keys sorted at every level, so digests survive re-ordering. */
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`);
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function digestOf(parts) {
+    return createHash('sha256').update(canonicalJson(parts)).digest('hex').slice(0, 16);
+}
+function build(source, path, parts) {
+    return { source, path, digest: digestOf(parts), ...parts };
+}
+function defaults(path) {
+    return build('defaults', path, {
+        required: DEFAULT_REQUIRED,
+        category: {},
+        component: {},
+        concern: DEFAULT_CONCERNS,
+        activity: DEFAULT_ACTIVITIES,
+        role: DEFAULT_ROLES,
+    });
+}
+/** Read and validate the project file; null when it does not exist. */
+export function readClassificationFile(devstepsDir) {
+    const path = join(devstepsDir, CLASSIFICATION_FILE);
+    if (!existsSync(path))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new ClassificationRegistryError(`${path} is not valid JSON: ${reason}`);
+    }
+    const parsed = ClassificationFileSchema.safeParse(raw);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`);
+        throw new ClassificationRegistryError(`${path} does not match the classification schema`, issues);
+    }
+    return parsed.data;
+}
+/** Write the project file atomically; every registry mutation goes through here. */
+export function writeClassificationFile(devstepsDir, file) {
+    writeJsonAtomic(join(devstepsDir, CLASSIFICATION_FILE), file);
+}
+/**
+ * Load the registry for a workspace. Without a project file the built-in
+ * facets apply and `category`/`component` stay empty; an invalid file is an
+ * error that names the offending fields, never a silent fallback.
+ */
+export function loadClassificationRegistry(devstepsDir) {
+    const path = join(devstepsDir, CLASSIFICATION_FILE);
+    const file = readClassificationFile(devstepsDir);
+    if (!file)
+        return defaults(path);
+    return build('project', path, {
+        required: { ...DEFAULT_REQUIRED, ...(file.required ?? {}) },
+        category: file.category,
+        component: file.component,
+        concern: { ...DEFAULT_CONCERNS, ...(file.concern ?? {}) },
+        activity: { ...DEFAULT_ACTIVITIES, ...(file.activity ?? {}) },
+        role: { ...DEFAULT_ROLES, ...(file.role ?? {}) },
+    });
+}
+//# sourceMappingURL=classification-registry.js.map

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

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

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

@@ -0,0 +1,31 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Pure node resolution: a typed value becomes a registry node by exact name,
+ * alias or a small edit distance, or the caller gets the nearest names.
+ *
+ * @see STORY-421 TASK-834
+ */
+/** Nodes as the registry exposes them: an alias list, with or without a question. */
+export type ResolvableNodes = Record<string, {
+    aliases: string[];
+    status?: string;
+} | string[]>;
+export type NodeResolution = {
+    kind: 'resolved';
+    node: string;
+    via: 'exact' | 'alias' | 'fuzzy';
+} | {
+    kind: 'unknown';
+    candidates: Array<{
+        node: string;
+        distance: number;
+    }>;
+};
+/** Canonical node name: lower case, words joined by `-`, `/` kept for a second level. */
+export declare function slugify(value: string): string;
+export declare function levenshtein(a: string, b: string): number;
+/** Exact after slugifying, then an alias, then a fuzzy match; otherwise the nearest names. */
+export declare function resolveNode(nodes: ResolvableNodes, value: string): NodeResolution;
+//# sourceMappingURL=classification-resolve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"classification-resolve.d.ts","sourceRoot":"","sources":["../../src/core/classification-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,qFAAqF;AACrF,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,EAAE,CAAC,CAAC;AAEhG,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC;AAM/E,yFAAyF;AACzF,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ7C;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAcxD;AAMD,8FAA8F;AAC9F,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAwBjF"}

package/dist/core/classification-resolve.js

@@ -0,0 +1,69 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Pure node resolution: a typed value becomes a registry node by exact name,
+ * alias or a small edit distance, or the caller gets the nearest names.
+ *
+ * @see STORY-421 TASK-834
+ */
+/** Edit distance a fuzzy match may have; shorter names get one less. */
+const FUZZY_DISTANCE = 2;
+const CANDIDATE_COUNT = 3;
+/** Canonical node name: lower case, words joined by `-`, `/` kept for a second level. */
+export function slugify(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[\s_]+/g, '-')
+        .replace(/[^a-z0-9/-]+/g, '')
+        .replace(/-{2,}/g, '-')
+        .replace(/^-|-$/g, '');
+}
+export function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const row = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + cost);
+        }
+        prev = row;
+    }
+    return prev[b.length];
+}
+function aliasesOf(spec) {
+    return Array.isArray(spec) ? spec : spec.aliases;
+}
+/** Exact after slugifying, then an alias, then a fuzzy match; otherwise the nearest names. */
+export function resolveNode(nodes, value) {
+    const wanted = slugify(value);
+    if (wanted.length === 0)
+        return { kind: 'unknown', candidates: [] };
+    if (wanted in nodes)
+        return { kind: 'resolved', node: wanted, via: 'exact' };
+    for (const [node, spec] of Object.entries(nodes)) {
+        if (aliasesOf(spec).some((a) => slugify(a) === wanted)) {
+            return { kind: 'resolved', node, via: 'alias' };
+        }
+    }
+    const scored = Object.entries(nodes)
+        .map(([node, spec]) => {
+        const names = [node, ...aliasesOf(spec).map(slugify)];
+        const distance = Math.min(...names.map((n) => levenshtein(n, wanted)));
+        return { node, distance };
+    })
+        .sort((a, b) => a.distance - b.distance || a.node.localeCompare(b.node));
+    const allowed = wanted.length < 5 ? FUZZY_DISTANCE - 1 : FUZZY_DISTANCE;
+    if (scored[0] && scored[0].distance <= allowed) {
+        return { kind: 'resolved', node: scored[0].node, via: 'fuzzy' };
+    }
+    return { kind: 'unknown', candidates: scored.slice(0, CANDIDATE_COUNT) };
+}
+//# sourceMappingURL=classification-resolve.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"classification-resolve.js","sourceRoot":"","sources":["../../src/core/classification-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,wEAAwE;AACxE,MAAM,cAAc,GAAG,CAAC,CAAC;AACzB,MAAM,eAAe,GAAG,CAAC,CAAC;AAE1B,yFAAyF;AACzF,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,OAAO,KAAK;SACT,IAAI,EAAE;SACN,WAAW,EAAE;SACb,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC;SAC5B,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;SACtB,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAS,EAAE,CAAS;IAC9C,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACtB,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACnC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3C,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QACrE,CAAC;QACD,IAAI,GAAG,GAAG,CAAC;IACb,CAAC;IACD,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC;AAED,SAAS,SAAS,CAAC,IAAsC;IACvD,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;AACnD,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,WAAW,CAAC,KAAsB,EAAE,KAAa;IAC/D,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IACpE,IAAI,MAAM,IAAI,KAAK;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;IAE7E,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,EAAE,CAAC;YACvD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;QAClD,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;SACjC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,EAAE;QACpB,MAAM,KAAK,GAAG,CAAC,IAAI,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;QACtD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;QACvE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC5B,CAAC,CAAC;SACD,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAE3E,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC;IACxE,IAAI,MAAM,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,OAAO,EAAE,CAAC;QAC/C,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;IAClE,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC,EAAE,CAAC;AAC3E,CAAC"}

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

@@ -0,0 +1,50 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Deterministic facet scoring. Aliases are matched against the item head
+ * (title, tags, category; weight 3) and the opening of its description
+ * (weight 1). Candidates are sorted by score; the caller decides, the scorer
+ * only suggests. No model, no randomness: same input, same output.
+ *
+ * @see STORY-420 TASK-829
+ */
+import type { ItemMetadata } from '../schemas/index.js';
+import type { ActivityNode, ClassificationRegistry, FacetNode } from './classification-registry.js';
+export interface FacetHit {
+    node: string;
+    score: number;
+    /** The aliases that matched, head hits first, at most four. */
+    terms: string[];
+}
+export interface ItemClassification {
+    /** Suggested categories by alias score; the item field is the confirmed value. */
+    category: FacetHit[];
+    component: string[];
+    concern: FacetHit[];
+    activity: FacetHit[];
+    /** Canonical role, the raw phrase when it is outside the vocabulary, or null. */
+    role: string | null;
+}
+export type ClassifiableItem = Pick<ItemMetadata, 'id' | 'type' | 'title' | 'tags' | 'category' | 'affected_paths'>;
+/** True when `alias` occurs in `text`; short aliases need word boundaries. */
+export declare function aliasHits(alias: string, text: string): boolean;
+/** The searchable head of an item: title, tags and category, lower-cased. */
+export declare function headText(item: ClassifiableItem): string;
+/** The opening of the description, lower-cased and capped. */
+export declare function bodyText(description: string): string;
+/** Score every node of a facet against head and body; nodes without a hit are omitted. */
+export declare function scoreNodes(nodes: Record<string, FacetNode>, head: string, body: string): FacetHit[];
+/** Component nodes whose path prefixes cover at least one affected path. */
+export declare function componentsFromPaths(paths: readonly string[], componentMap: Record<string, string[]>): string[];
+/**
+ * The role a user story names. The title is read first, then the description
+ * opening; a phrase outside the vocabulary is returned as written so the gap
+ * stays visible.
+ */
+export declare function roleFromStory(title: string, description: string, roles: Record<string, string[]>): string | null;
+/** Activity: the item type decides where declared, aliases otherwise, then the type default. */
+export declare function activityFor(item: ClassifiableItem, head: string, body: string, activities: Record<string, ActivityNode>): FacetHit[];
+/** Classify one item against a registry. */
+export declare function classifyItem(item: ClassifiableItem, description: string, registry: ClassificationRegistry): ItemClassification;
+//# sourceMappingURL=classification-score.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"classification-score.d.ts","sourceRoot":"","sources":["../../src/core/classification-score.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,sBAAsB,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAEpG,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,kFAAkF;IAClF,QAAQ,EAAE,QAAQ,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,QAAQ,EAAE,QAAQ,EAAE,CAAC;IACrB,iFAAiF;IACjF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,MAAM,gBAAgB,GAAG,IAAI,CACjC,YAAY,EACZ,IAAI,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,GAAG,gBAAgB,CACjE,CAAC;AAUF,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAQ9D;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAEvD;AAED,8DAA8D;AAC9D,wBAAgB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,0FAA0F;AAC1F,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EAChC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,QAAQ,EAAE,CAaZ;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GACrC,MAAM,EAAE,CASV;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAC9B,MAAM,GAAG,IAAI,CAQf;AAED,gGAAgG;AAChG,wBAAgB,WAAW,CACzB,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GACvC,QAAQ,EAAE,CAUZ;AAED,4CAA4C;AAC5C,wBAAgB,YAAY,CAC1B,IAAI,EAAE,gBAAgB,EACtB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,sBAAsB,GAC/B,kBAAkB,CAUpB"}