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

package/dist/core/path-guard.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Shared path-traversal guard — OWASP A01 defence-in-depth utility.
+ * Extracted from devsteps_docs_import.ts scanner.
+ *
+ * Containment is decided by `path.relative`, not by a string prefix, so the
+ * guard works with either separator: a prefix test against `${root}/` refused
+ * every Windows path, because `path.resolve` returns backslashes there
+ * (BUG-129). Where the path exists on disk, symbolic links are resolved too, so
+ * a link inside the workspace cannot carry a read or write outside it.
+ *
+ * @see TASK-494 EPIC-043 BUG-129 TASK-911
+ */
+import path from 'node:path';
+/** `path.posix` or `path.win32`, so either flavour can be checked on any host. */
+type PlatformPath = typeof path.posix;
+/**
+ * The lexical half of the guard for one path flavour: the resolved path when it
+ * lies inside the resolved root (or is the root), otherwise null. A name that
+ * merely starts with two dots, such as `..foo`, stays inside.
+ */
+export declare function resolveContainedPath(api: PlatformPath, input: string, workspaceRoot: string): string | null;
+/**
+ * True when `candidate` lies inside `root` or is the root itself. `pathApi` is
+ * injectable so Windows semantics (drive letters, case, UNC) can be tested on
+ * any host.
+ */
+export declare function isInsideRoot(root: string, candidate: string, pathApi?: PlatformPath): boolean;
+/**
+ * Validate that `input` (workspace-relative or absolute) resolves to a path
+ * that is contained within `workspaceRoot`.
+ *
+ * Returns the resolved absolute path on success, or `null` if the path
+ * escapes the workspace root (path-traversal attempt detected), lexically or
+ * through a symbolic link.
+ *
+ * @example
+ * validateWorkspacePath('docs/guide.md', '/project')
+ * // → '/project/docs/guide.md'
+ *
+ * validateWorkspacePath('../etc/passwd', '/project')
+ * // → null  (escapes workspace root)
+ */
+export declare function validateWorkspacePath(input: string, workspaceRoot: string): string | null;
+export {};
+//# sourceMappingURL=path-guard.d.ts.map

package/dist/core/path-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-guard.d.ts","sourceRoot":"","sources":["../../src/core/path-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,kFAAkF;AAClF,KAAK,YAAY,GAAG,OAAO,IAAI,CAAC,KAAK,CAAC;AAEtC;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,YAAY,EACjB,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,MAAM,GAAG,IAAI,CAQf;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,YAAmB,GAC3B,OAAO,CAET;AAyDD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIzF"}

package/dist/core/path-guard.js

@@ -0,0 +1,120 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Shared path-traversal guard — OWASP A01 defence-in-depth utility.
+ * Extracted from devsteps_docs_import.ts scanner.
+ *
+ * Containment is decided by `path.relative`, not by a string prefix, so the
+ * guard works with either separator: a prefix test against `${root}/` refused
+ * every Windows path, because `path.resolve` returns backslashes there
+ * (BUG-129). Where the path exists on disk, symbolic links are resolved too, so
+ * a link inside the workspace cannot carry a read or write outside it.
+ *
+ * @see TASK-494 EPIC-043 BUG-129 TASK-911
+ */
+import { lstatSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+/**
+ * The lexical half of the guard for one path flavour: the resolved path when it
+ * lies inside the resolved root (or is the root), otherwise null. A name that
+ * merely starts with two dots, such as `..foo`, stays inside.
+ */
+export function resolveContainedPath(api, input, workspaceRoot) {
+    const resolvedRoot = api.resolve(workspaceRoot);
+    const resolvedInput = api.resolve(workspaceRoot, input);
+    const relativePath = api.relative(resolvedRoot, resolvedInput);
+    if (relativePath === '')
+        return resolvedInput;
+    if (api.isAbsolute(relativePath))
+        return null;
+    if (relativePath === '..' || relativePath.startsWith(`..${api.sep}`))
+        return null;
+    return resolvedInput;
+}
+/**
+ * True when `candidate` lies inside `root` or is the root itself. `pathApi` is
+ * injectable so Windows semantics (drive letters, case, UNC) can be tested on
+ * any host.
+ */
+export function isInsideRoot(root, candidate, pathApi = path) {
+    return resolveContainedPath(pathApi, candidate, root) !== null;
+}
+/** True when `target` exists as a directory entry, such as a dangling link. */
+function existsAsLink(target) {
+    try {
+        lstatSync(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** True when `error` is a missing-path error from the file system. */
+function isMissing(error) {
+    return error?.code === 'ENOENT';
+}
+/**
+ * The symbolic-link half: the nearest part of `resolvedInput` that exists must
+ * resolve into the real root. A path that does not exist yet (an output file)
+ * is judged by its deepest existing ancestor. A dangling link is refused,
+ * because writing through it would create its target wherever it points. A
+ * file-system error other than a missing path refuses rather than throws.
+ */
+function staysInsideAfterLinks(resolvedInput, workspaceRoot) {
+    let realRoot;
+    try {
+        realRoot = realpathSync.native(path.resolve(workspaceRoot));
+    }
+    catch (error) {
+        // A root that does not exist holds no links to follow. A root that is itself
+        // a dangling link would let a later mkdir create its target, so it refuses,
+        // as does any other error.
+        return isMissing(error) && !existsAsLink(path.resolve(workspaceRoot));
+    }
+    let probe = resolvedInput;
+    for (;;) {
+        try {
+            lstatSync(probe);
+            break;
+        }
+        catch (error) {
+            if (!isMissing(error))
+                return false;
+            const parent = path.dirname(probe);
+            if (parent === probe)
+                return true;
+            probe = parent;
+        }
+    }
+    let realProbe;
+    try {
+        realProbe = realpathSync.native(probe);
+    }
+    catch {
+        return false;
+    }
+    return resolveContainedPath(path, realProbe, realRoot) !== null;
+}
+/**
+ * Validate that `input` (workspace-relative or absolute) resolves to a path
+ * that is contained within `workspaceRoot`.
+ *
+ * Returns the resolved absolute path on success, or `null` if the path
+ * escapes the workspace root (path-traversal attempt detected), lexically or
+ * through a symbolic link.
+ *
+ * @example
+ * validateWorkspacePath('docs/guide.md', '/project')
+ * // → '/project/docs/guide.md'
+ *
+ * validateWorkspacePath('../etc/passwd', '/project')
+ * // → null  (escapes workspace root)
+ */
+export function validateWorkspacePath(input, workspaceRoot) {
+    const resolvedInput = resolveContainedPath(path, input, workspaceRoot);
+    if (resolvedInput === null)
+        return null;
+    return staysInsideAfterLinks(resolvedInput, workspaceRoot) ? resolvedInput : null;
+}
+//# sourceMappingURL=path-guard.js.map

package/dist/core/path-guard.js.map

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

package/dist/core/process-definition-hint.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The process_definition shape, sent when a definition is refused instead of in every request's
+ * add and update schema (TASK-962, SPIKE-074).
+ */
+export declare const PROCESS_DEFINITION_HINT: string;
+/** A definition whose schema_version is neither "1.0" nor "2.0". */
+export declare class ProcessDefinitionVersionError extends Error {
+    readonly code = "INVALID_SCHEMA_VERSION";
+    constructor(version: unknown);
+}
+/** True for a refusal of the definition's shape, which the caller fixes with the hint. */
+export declare function isProcessDefinitionRejection(error: unknown): boolean;
+//# sourceMappingURL=process-definition-hint.d.ts.map

package/dist/core/process-definition-hint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-definition-hint.d.ts","sourceRoot":"","sources":["../../src/core/process-definition-hint.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,eAAO,MAAM,uBAAuB,QAYK,CAAC;AAE1C,oEAAoE;AACpE,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,QAAQ,CAAC,IAAI,4BAA4B;IACzC,YAAY,OAAO,EAAE,OAAO,EAK3B;CACF;AAED,0FAA0F;AAC1F,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAMpE"}

package/dist/core/process-definition-hint.js

@@ -0,0 +1,37 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * The process_definition shape, sent when a definition is refused instead of in every request's
+ * add and update schema (TASK-962, SPIKE-074).
+ */
+import { TaskWorkflowLoadError } from './task-workflow-loader.js';
+import { TestWorkflowLoadError } from './test-workflow-loader.js';
+export const PROCESS_DEFINITION_HINT = 'v1 (schema_version "1.0", state machine): { schema_version: "1.0", process_type: <label, ' +
+    'also the run directory>, profile (TEST: "human-guided-guide" | "autonomous-guide"), states: ' +
+    '{ [name]: { terminal?, resumable?, retryable?, requires_human? } }, initial, transitions: ' +
+    '[{ event, from: [states], to, guards?: [] }], terminal: [{ outcome: "succeeded" | "failed" | ' +
+    '"cancelled", state }], human_steps?: [{ id, instruction, expected_observation, ' +
+    'accepted_answers, cleanup_required? }], strict_checkpoints?, evidence?, cleanup?, ' +
+    'max_attempts? }. Initial, from, to and terminal states must be declared, terminal states ' +
+    'have terminal: true, every state is reachable, and every non-terminal state has an outgoing ' +
+    'transition. v2 (schema_version "2.0", steps bound to host tools): the full shape and the ' +
+    'five Ws of a step (who?, when: its number in run order, why?, how: instruction? and ' +
+    'expected_observation?, where: section?) are in the workflow_manifest_get description. A ' +
+    'TEST run needs a direct `tests` link.';
+/** A definition whose schema_version is neither "1.0" nor "2.0". */
+export class ProcessDefinitionVersionError extends Error {
+    code = 'INVALID_SCHEMA_VERSION';
+    constructor(version) {
+        super(`process_definition needs schema_version "1.0" or "2.0", got ${JSON.stringify(version) ?? 'none'}`);
+        this.name = 'ProcessDefinitionVersionError';
+    }
+}
+/** True for a refusal of the definition's shape, which the caller fixes with the hint. */
+export function isProcessDefinitionRejection(error) {
+    if (error instanceof ProcessDefinitionVersionError)
+        return true;
+    return ((error instanceof TaskWorkflowLoadError || error instanceof TestWorkflowLoadError) &&
+        error.code === 'INVALID_DEFINITION');
+}
+//# sourceMappingURL=process-definition-hint.js.map

package/dist/core/process-definition-hint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-definition-hint.js","sourceRoot":"","sources":["../../src/core/process-definition-hint.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAElE,MAAM,CAAC,MAAM,uBAAuB,GAClC,2FAA2F;IAC3F,8FAA8F;IAC9F,4FAA4F;IAC5F,+FAA+F;IAC/F,iFAAiF;IACjF,oFAAoF;IACpF,2FAA2F;IAC3F,8FAA8F;IAC9F,2FAA2F;IAC3F,sFAAsF;IACtF,0FAA0F;IAC1F,uCAAuC,CAAC;AAE1C,oEAAoE;AACpE,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IAC7C,IAAI,GAAG,wBAAwB,CAAC;IACzC,YAAY,OAAgB;QAC1B,KAAK,CACH,+DAA+D,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,MAAM,EAAE,CACnG,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAC9C,CAAC;CACF;AAED,0FAA0F;AAC1F,MAAM,UAAU,4BAA4B,CAAC,KAAc;IACzD,IAAI,KAAK,YAAY,6BAA6B;QAAE,OAAO,IAAI,CAAC;IAChE,OAAO,CACL,CAAC,KAAK,YAAY,qBAAqB,IAAI,KAAK,YAAY,qBAAqB,CAAC;QAClF,KAAK,CAAC,IAAI,KAAK,oBAAoB,CACpC,CAAC;AACJ,CAAC"}

package/dist/core/project-status.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Project overview statistics.
+ * STORY-045: the CLI and the MCP server report the same counts, stale items, and samples.
+ */
+import { type ListItemEntry } from './list.js';
+/** Days an in-progress item may go without an update before it counts as stale. */
+export declare const STALE_AFTER_DAYS = 7;
+export interface StatusBreakdown {
+    count: number;
+    recent_ids: string[];
+}
+export interface RecentUpdate {
+    id: string;
+    type: string;
+    status: string;
+    title: string;
+    updated: string;
+}
+export interface StaleItem {
+    id: string;
+    title: string;
+    days_since_update: number;
+}
+export interface ProjectStatusArgs {
+    /** Add per-status samples and the most recent updates. */
+    detailed?: boolean;
+}
+export interface ProjectStatus {
+    project: {
+        name: string;
+        created: string;
+        updated: string;
+        done_by?: 'product-owner' | 'acceptance';
+    };
+    stats: {
+        total: number;
+        /** IDs whose metadata could not be read; `total` counts readable items only (STORY-391). */
+        unreadable?: string[];
+        by_type: Record<string, number>;
+        by_status: Record<string, number>;
+        by_eisenhower: Record<string, number>;
+    };
+    warnings?: {
+        stale_items: StaleItem[];
+        blocked_count?: number;
+    };
+    items_by_status?: Record<string, StatusBreakdown>;
+    recent_updates?: RecentUpdate[];
+}
+/** In-progress items that nobody touched for longer than the stale window. */
+export declare function staleInProgress(items: readonly ListItemEntry[]): StaleItem[];
+export declare function getProjectStatus(devstepsDir: string, args?: ProjectStatusArgs): Promise<ProjectStatus>;
+//# sourceMappingURL=project-status.d.ts.map

package/dist/core/project-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-status.d.ts","sourceRoot":"","sources":["../../src/core/project-status.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,EAAE,KAAK,aAAa,EAAa,MAAM,WAAW,CAAC;AAE1D,mFAAmF;AACnF,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAKlC,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,eAAe,GAAG,YAAY,CAAC;KAC1C,CAAC;IACF,KAAK,EAAE;QACL,KAAK,EAAE,MAAM,CAAC;QACd,4FAA4F;QAC5F,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;QACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAClC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACvC,CAAC;IACF,QAAQ,CAAC,EAAE;QAAE,WAAW,EAAE,SAAS,EAAE,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAClD,cAAc,CAAC,EAAE,YAAY,EAAE,CAAC;CACjC;AAMD,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS,EAAE,CAU5E;AAwBD,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,aAAa,CAAC,CA8CxB"}

package/dist/core/project-status.js

@@ -0,0 +1,94 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Project overview statistics.
+ * STORY-045: the CLI and the MCP server report the same counts, stale items, and samples.
+ */
+import { existsSync } from 'node:fs';
+import { STATUS } from '../constants/index.js';
+import { getConfig } from './config.js';
+import { listItems } from './list.js';
+/** Days an in-progress item may go without an update before it counts as stale. */
+export const STALE_AFTER_DAYS = 7;
+const RECENT_UPDATE_COUNT = 10;
+const SAMPLE_IDS_PER_STATUS = 5;
+const DAY_MS = 1000 * 60 * 60 * 24;
+function daysSince(updated) {
+    return (Date.now() - new Date(updated).getTime()) / DAY_MS;
+}
+/** In-progress items that nobody touched for longer than the stale window. */
+export function staleInProgress(items) {
+    return items
+        .filter((item) => item.status === STATUS.IN_PROGRESS && daysSince(item.updated) > STALE_AFTER_DAYS)
+        .map((item) => ({
+        id: item.id,
+        title: item.title,
+        days_since_update: Math.floor(daysSince(item.updated)),
+    }));
+}
+/**
+ * Per-status counts plus a sample of the most recently updated IDs.
+ * Inlining every item once cost ~163k tokens on this repository; counts plus a few IDs
+ * answer the same question, and `listItems({ status })` serves the rest.
+ */
+function summarizeByStatus(itemsByUpdatedDesc) {
+    const breakdown = {};
+    for (const item of itemsByUpdatedDesc) {
+        const entry = breakdown[item.status] ?? { count: 0, recent_ids: [] };
+        entry.count += 1;
+        if (entry.recent_ids.length < SAMPLE_IDS_PER_STATUS)
+            entry.recent_ids.push(item.id);
+        breakdown[item.status] = entry;
+    }
+    return breakdown;
+}
+function countBy(items, key) {
+    const counts = {};
+    for (const item of items)
+        counts[key(item)] = (counts[key(item)] || 0) + 1;
+    return counts;
+}
+export async function getProjectStatus(devstepsDir, args = {}) {
+    if (!existsSync(devstepsDir)) {
+        throw new Error('Project not initialized. Run devsteps-init first.');
+    }
+    const config = await getConfig(devstepsDir);
+    const { items, unreadable } = await listItems(devstepsDir, {});
+    const status = {
+        project: {
+            name: config.project_name,
+            created: config.created,
+            updated: config.updated,
+            ...(config.settings?.done_by !== undefined ? { done_by: config.settings.done_by } : {}),
+        },
+        stats: {
+            total: items.length,
+            ...(unreadable.length > 0 ? { unreadable } : {}),
+            by_type: countBy(items, (item) => item.type),
+            by_status: countBy(items, (item) => item.status),
+            by_eisenhower: countBy(items, (item) => item.eisenhower ?? 'not-urgent-important'),
+        },
+    };
+    const staleItems = staleInProgress(items);
+    const blockedCount = items.filter((item) => item.status === STATUS.BLOCKED).length;
+    if (staleItems.length > 0 || blockedCount > 0) {
+        status.warnings = {
+            stale_items: staleItems,
+            ...(blockedCount > 0 ? { blocked_count: blockedCount } : {}),
+        };
+    }
+    if (args.detailed) {
+        const byUpdatedDesc = [...items].sort((left, right) => new Date(right.updated).getTime() - new Date(left.updated).getTime());
+        status.items_by_status = summarizeByStatus(byUpdatedDesc);
+        status.recent_updates = byUpdatedDesc.slice(0, RECENT_UPDATE_COUNT).map((item) => ({
+            id: item.id,
+            type: item.type,
+            status: item.status,
+            title: item.title,
+            updated: item.updated,
+        }));
+    }
+    return status;
+}
+//# sourceMappingURL=project-status.js.map

package/dist/core/project-status.js.map

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

package/dist/core/promote.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Promote item between focus tiers with WIP-limit guard.
+ * Pull-Principle Kanban gate: rejects promotion to focus:now when wip_limit reached. The gate
+ * counts every focus:now item, as the board does.
+ *
+ * @see STORY-311 BUG-166
+ */
+export interface PromoteResult {
+    success: boolean;
+    wip_count: number;
+    wip_limit: number;
+    message: string;
+}
+/**
+ * Promote an item to a focus tier (now/next/later).
+ * Enforces WIP-limit guard when promoting to focus:now.
+ * Self-excludes the current item from the WIP count to allow noop re-promotion.
+ */
+export declare function promoteItem(devstepsDir: string, args: {
+    id: string;
+    to: 'now' | 'next' | 'later';
+}): Promise<PromoteResult>;
+//# sourceMappingURL=promote.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"promote.d.ts","sourceRoot":"","sources":["../../src/core/promote.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAA;CAAE,GACjD,OAAO,CAAC,aAAa,CAAC,CA6CxB"}

package/dist/core/promote.js

@@ -0,0 +1,62 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Promote item between focus tiers with WIP-limit guard.
+ * Pull-Principle Kanban gate: rejects promotion to focus:now when wip_limit reached. The gate
+ * counts every focus:now item, as the board does.
+ *
+ * @see STORY-311 BUG-166
+ */
+import { WIP_LIMIT } from './focus-work.js';
+import { getItem } from './get.js';
+import { listItems } from './list.js';
+import { updateItem } from './update.js';
+/**
+ * Promote an item to a focus tier (now/next/later).
+ * Enforces WIP-limit guard when promoting to focus:now.
+ * Self-excludes the current item from the WIP count to allow noop re-promotion.
+ */
+export async function promoteItem(devstepsDir, args) {
+    // 1. Fetch item — returns failure if not found
+    let currentTags;
+    try {
+        const result = await getItem(devstepsDir, args.id);
+        currentTags = result.metadata.tags ?? [];
+    }
+    catch {
+        return {
+            success: false,
+            wip_count: 0,
+            wip_limit: WIP_LIMIT,
+            message: `Item not found: ${args.id}`,
+        };
+    }
+    // 2. WIP guard — only enforced when promoting to 'now'
+    if (args.to === 'now') {
+        const nowResult = await listItems(devstepsDir, { tags: ['focus:now'] });
+        // Self-exclude current item so re-promotion is a noop (not a false block)
+        const wipCount = nowResult.items.filter((i) => i.id !== args.id).length;
+        if (wipCount >= WIP_LIMIT) {
+            return {
+                success: false,
+                wip_count: wipCount,
+                wip_limit: WIP_LIMIT,
+                message: `WIP limit reached: ${wipCount}/${WIP_LIMIT} items already in focus:now`,
+            };
+        }
+    }
+    // 3. Replace all focus:* tags with the new tier
+    const newTags = [...currentTags.filter((t) => !t.startsWith('focus:')), `focus:${args.to}`];
+    // 4. Persist tag change
+    await updateItem(devstepsDir, { id: args.id, tags: newTags });
+    // 5. Recount focus:now for accurate post-update wip_count
+    const postUpdateNow = await listItems(devstepsDir, { tags: ['focus:now'] });
+    return {
+        success: true,
+        wip_count: postUpdateNow.items.length,
+        wip_limit: WIP_LIMIT,
+        message: `Promoted ${args.id} to focus:${args.to}`,
+    };
+}
+//# sourceMappingURL=promote.js.map

package/dist/core/promote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promote.js","sourceRoot":"","sources":["../../src/core/promote.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AASzC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,WAAmB,EACnB,IAAkD;IAElD,+CAA+C;IAC/C,IAAI,WAAqB,CAAC;IAC1B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;QACnD,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL,OAAO,EAAE,KAAK;YACd,SAAS,EAAE,CAAC;YACZ,SAAS,EAAE,SAAS;YACpB,OAAO,EAAE,mBAAmB,IAAI,CAAC,EAAE,EAAE;SACtC,CAAC;IACJ,CAAC;IAED,uDAAuD;IACvD,IAAI,IAAI,CAAC,EAAE,KAAK,KAAK,EAAE,CAAC;QACtB,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QACxE,0EAA0E;QAC1E,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC;QACxE,IAAI,QAAQ,IAAI,SAAS,EAAE,CAAC;YAC1B,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,SAAS,EAAE,QAAQ;gBACnB,SAAS,EAAE,SAAS;gBACpB,OAAO,EAAE,sBAAsB,QAAQ,IAAI,SAAS,6BAA6B;aAClF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,gDAAgD;IAChD,MAAM,OAAO,GAAG,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAE5F,wBAAwB;IACxB,MAAM,UAAU,CAAC,WAAW,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IAE9D,0DAA0D;IAC1D,MAAM,aAAa,GAAG,MAAM,SAAS,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAE5E,OAAO;QACL,OAAO,EAAE,IAAI;QACb,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,MAAM;QACrC,SAAS,EAAE,SAAS;QACpB,OAAO,EAAE,YAAY,IAAI,CAAC,EAAE,aAAa,IAAI,CAAC,EAAE,EAAE;KACnD,CAAC;AACJ,CAAC"}

package/dist/core/relationship-completeness.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Relationship completeness diagnostics for hierarchy items.
+ * This module reports missing parent links without mutating items.
+ */
+import type { ItemMetadata, ItemType, Methodology } from '../schemas/index.js';
+export interface RelationshipCompletenessResult {
+    item_id: string;
+    item_type: ItemType;
+    outcome: 'complete' | 'pending' | 'invalid' | 'not-applicable';
+    complete: boolean;
+    pending: boolean;
+    invalid: boolean;
+    not_applicable: boolean;
+    expected_parent_types: ItemType[];
+    /** `tests` for TEST items, whose runs need a direct tests relationship; `implements` otherwise. */
+    parent_relation: 'implements' | 'tests';
+    parent_ids: string[];
+    missing_parent: boolean;
+    message?: string;
+    notes?: string[];
+}
+export interface RelationshipParentTypes {
+    [itemId: string]: ItemType | undefined;
+}
+/** Report whether an item has its expected hierarchy parent relationship. */
+export declare function evaluateRelationshipCompleteness(metadata: Pick<ItemMetadata, 'id' | 'type'> & {
+    linked_items?: Partial<Pick<ItemMetadata['linked_items'], 'implements' | 'tests'>>;
+}, methodology: Methodology, parentTypes?: RelationshipParentTypes): RelationshipCompletenessResult;
+//# sourceMappingURL=relationship-completeness.d.ts.map

package/dist/core/relationship-completeness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-completeness.d.ts","sourceRoot":"","sources":["../../src/core/relationship-completeness.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAE/E,MAAM,WAAW,8BAA8B;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,QAAQ,CAAC;IACpB,OAAO,EAAE,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,gBAAgB,CAAC;IAC/D,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,OAAO,CAAC;IACxB,qBAAqB,EAAE,QAAQ,EAAE,CAAC;IAClC,mGAAmG;IACnG,eAAe,EAAE,YAAY,GAAG,OAAO,CAAC;IACxC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;CACxC;AA0BD,6EAA6E;AAC7E,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,GAAG,MAAM,CAAC,GAAG;IAC5C,YAAY,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,cAAc,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC;CACpF,EACD,WAAW,EAAE,WAAW,EACxB,WAAW,GAAE,uBAA4B,GACxC,8BAA8B,CA2ChC"}

package/dist/core/relationship-completeness.js

@@ -0,0 +1,82 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Relationship completeness diagnostics for hierarchy items.
+ * This module reports missing parent links without mutating items.
+ */
+const SCRUM_PARENTS = {
+    story: ['epic'],
+    spike: ['epic'],
+    task: ['story', 'spike', 'bug'],
+    bug: ['story'],
+    test: ['epic', 'story'],
+};
+const WATERFALL_PARENTS = {
+    feature: ['requirement'],
+    spike: ['requirement'],
+    task: ['feature', 'spike', 'bug'],
+    bug: ['feature'],
+    test: ['requirement', 'feature'],
+};
+function expectedParents(type, methodology) {
+    const map = methodology === 'waterfall' ? WATERFALL_PARENTS : SCRUM_PARENTS;
+    if (methodology === 'hybrid') {
+        return [...new Set([...(SCRUM_PARENTS[type] ?? []), ...(WATERFALL_PARENTS[type] ?? [])])];
+    }
+    return map[type] ?? [];
+}
+/** Report whether an item has its expected hierarchy parent relationship. */
+export function evaluateRelationshipCompleteness(metadata, methodology, parentTypes = {}) {
+    // TASK-812: a TEST is accepted through `tests`, which is what workflow_run_start enforces.
+    const relation = metadata.type === 'test' ? 'tests' : 'implements';
+    const expected_parent_types = expectedParents(metadata.type, methodology);
+    const parent_ids = metadata.linked_items?.[relation] ?? [];
+    const hasInvalidParent = parent_ids.some((parentId) => {
+        const parentType = parentTypes[parentId];
+        return parentType !== undefined && !expected_parent_types.includes(parentType);
+    });
+    const not_applicable = expected_parent_types.length === 0;
+    const pending = !not_applicable && parent_ids.length === 0;
+    const invalid = !not_applicable && !pending && hasInvalidParent;
+    const outcome = not_applicable
+        ? 'not-applicable'
+        : invalid
+            ? 'invalid'
+            : pending
+                ? 'pending'
+                : 'complete';
+    const notes = relation === 'tests' && (metadata.linked_items?.implements ?? []).length > 0
+        ? [
+            `implements on ${metadata.id} is not a run-enabling relation; a TEST run needs a direct tests relationship`,
+        ]
+        : undefined;
+    return {
+        item_id: metadata.id,
+        item_type: metadata.type,
+        outcome,
+        complete: outcome === 'complete',
+        pending,
+        invalid,
+        not_applicable,
+        expected_parent_types,
+        parent_relation: relation,
+        parent_ids,
+        missing_parent: pending,
+        ...(pending || invalid
+            ? { message: completenessMessage(metadata.id, relation, pending, expected_parent_types) }
+            : {}),
+        ...(notes ? { notes } : {}),
+    };
+}
+function completenessMessage(itemId, relation, pending, expected) {
+    if (relation === 'tests') {
+        return pending
+            ? `${itemId} should test the item it accepts (tests → ${expected.join(' or ')}); workflow_run_start requires a direct tests relationship`
+            : `${itemId} has a tests link to a type it cannot accept`;
+    }
+    return pending
+        ? `${itemId} should implement a parent item (${expected.join(' or ')})`
+        : `${itemId} has an implements link to an invalid parent type`;
+}
+//# sourceMappingURL=relationship-completeness.js.map

package/dist/core/relationship-completeness.js.map

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

package/dist/core/relationship-lock.d.ts

@@ -0,0 +1,2 @@
+export declare function withRelationshipLock<T>(itemIds: readonly string[], operation: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=relationship-lock.d.ts.map

package/dist/core/relationship-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-lock.d.ts","sourceRoot":"","sources":["../../src/core/relationship-lock.ts"],"names":[],"mappings":"AAMA,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAC1B,OAAO,CAAC,CAAC,CAAC,CAyBZ"}