@lumenflow/cli 4.24.0 → 5.0.1

package/packs/software-delivery/src/config/workspace-reader.ts

@@ -0,0 +1,310 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Pack-side workspace.yaml reader.
+ *
+ * Locates the project root (via kernel primitive) and returns the
+ * `software_delivery` section of `workspace.yaml`. Loose typing on purpose —
+ * the authoritative schema lives in `@lumenflow/core`; this helper exists to
+ * keep the pack core-free for Option 1b prep work (INIT-058).
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { findProjectRoot } from '@lumenflow/kernel/primitives/project-root';
+import { WORKSPACE_CONFIG_FILE_NAME } from '@lumenflow/kernel/primitives/workspace-constants';
+import { parse as parseYaml } from 'yaml';
+
+import {
+  AGENTS_DEFAULTS,
+  CLEANUP_DEFAULTS,
+  CLOUD_DEFAULTS,
+  DIRECTORIES_DEFAULTS,
+  ESCALATION_DEFAULTS,
+  EXPERIMENTAL_DEFAULTS,
+  GATES_DEFAULTS,
+  GIT_DEFAULTS,
+  INITIATIVE_ID_DEFAULTS,
+  LUMENFLOW_CONFIG_DEFAULTS,
+  MEMORY_DEFAULTS,
+  STATE_PATHS_DEFAULTS,
+  TELEMETRY_DEFAULTS,
+  UI_DEFAULTS,
+  WU_DEFAULTS,
+  WU_ID_DEFAULTS,
+  YAML_DEFAULTS,
+  type AgentsConfig,
+  type CleanupConfig,
+  type CloudConfig,
+  type DirectoriesConfig,
+  type EscalationConfig,
+  type EventArchivalConfig,
+  type ExperimentalConfig,
+  type GatesConfig,
+  type GitConfig,
+  type IdFormatConfig,
+  type LumenflowConfig,
+  type MemoryConfig,
+  type PackageManager,
+  type PushRetryConfig,
+  type StatePathsConfig,
+  type TelemetryConfig,
+  type TestRunner,
+  type UiConfig,
+  type WuConfig,
+  type YamlConfig,
+} from './schemas/lumenflow-config-schema-types.js';
+
+export type SoftwareDeliveryConfig = Record<string, unknown>;
+
+/**
+ * Read `workspace.yaml` relative to the given `cwd`'s project root and return
+ * the `software_delivery` section (or an empty object if absent/empty).
+ *
+ * @throws If the project root cannot be located or the YAML is malformed.
+ */
+export function readSoftwareDeliveryConfig(cwd: string): SoftwareDeliveryConfig {
+  const root = findProjectRoot(cwd);
+  const raw = readFileSync(join(root, WORKSPACE_CONFIG_FILE_NAME), 'utf8');
+  const doc = parseYaml(raw) as Record<string, unknown> | null | undefined;
+  const section = doc?.['software_delivery'];
+  if (section && typeof section === 'object' && !Array.isArray(section)) {
+    return section as SoftwareDeliveryConfig;
+  }
+  return {};
+}
+
+/**
+ * Re-export pack-local directory/state-path type aliases. These mirror
+ * `@lumenflow/core/schemas/directories-config`; drift is enforced by the
+ * integration-tests parity tests.
+ */
+export type WorkspaceDirectories = DirectoriesConfig;
+export type WorkspaceStatePaths = StatePathsConfig;
+export type WorkspaceEventArchivalConfig = EventArchivalConfig;
+
+function readObjectRecord(cwd: string, key: string): Record<string, unknown> {
+  const section = readSoftwareDeliveryConfig(cwd);
+  const value = section[key];
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  return {};
+}
+
+/**
+ * Return the typed directory map for the workspace rooted at `cwd`.
+ *
+ * User-provided values in `software_delivery.directories` are merged over the
+ * built-in defaults. Unknown keys in the user's YAML are ignored by the return
+ * type but pass through the spread — the authoritative schema validation still
+ * lives in core's `getConfig()` pathway.
+ */
+export function getDirectories(cwd: string): WorkspaceDirectories {
+  const overrides = readObjectRecord(cwd, 'directories') as Partial<WorkspaceDirectories>;
+  return { ...DIRECTORIES_DEFAULTS, ...overrides };
+}
+
+/**
+ * Return the typed state-paths map for the workspace rooted at `cwd`.
+ *
+ * User-provided values in `software_delivery.state` are merged over the
+ * built-in defaults. `eventArchival` is merged as a nested object so a partial
+ * override (e.g. only `archiveAfter`) preserves the remaining defaults.
+ */
+export function getStatePaths(cwd: string): WorkspaceStatePaths {
+  const overrides = readObjectRecord(cwd, 'state') as Partial<WorkspaceStatePaths>;
+  const { eventArchival: overrideArchival, ...flatOverrides } = overrides;
+  const eventArchivalOverrides =
+    overrideArchival && typeof overrideArchival === 'object' && !Array.isArray(overrideArchival)
+      ? (overrideArchival as Partial<WorkspaceEventArchivalConfig>)
+      : {};
+  return {
+    ...STATE_PATHS_DEFAULTS,
+    ...flatOverrides,
+    eventArchival: {
+      ...STATE_PATHS_DEFAULTS.eventArchival,
+      ...eventArchivalOverrides,
+    },
+  };
+}
+
+function mergeGit(overrides: Partial<GitConfig> | undefined): GitConfig {
+  if (!overrides) return { ...GIT_DEFAULTS, push_retry: { ...GIT_DEFAULTS.push_retry } };
+  const { push_retry: overridePushRetry, ...flatOverrides } = overrides;
+  const pushRetryOverrides =
+    overridePushRetry && typeof overridePushRetry === 'object' && !Array.isArray(overridePushRetry)
+      ? (overridePushRetry as Partial<PushRetryConfig>)
+      : {};
+  return {
+    ...GIT_DEFAULTS,
+    ...flatOverrides,
+    push_retry: {
+      ...GIT_DEFAULTS.push_retry,
+      ...pushRetryOverrides,
+    },
+  };
+}
+
+function mergeWu(overrides: Partial<WuConfig> | undefined): WuConfig {
+  if (!overrides) return { ...WU_DEFAULTS, brief: { ...WU_DEFAULTS.brief } };
+  const { brief: overrideBrief, ...flatOverrides } = overrides;
+  const briefOverrides =
+    overrideBrief && typeof overrideBrief === 'object' && !Array.isArray(overrideBrief)
+      ? (overrideBrief as Partial<WuConfig['brief']>)
+      : {};
+  return {
+    ...WU_DEFAULTS,
+    ...flatOverrides,
+    brief: {
+      ...WU_DEFAULTS.brief,
+      ...briefOverrides,
+    },
+  };
+}
+
+function mergeSimple<T>(defaults: T, overrides: unknown): T {
+  if (overrides && typeof overrides === 'object' && !Array.isArray(overrides)) {
+    return { ...defaults, ...(overrides as object) } as T;
+  }
+  return { ...defaults };
+}
+
+function mergeTelemetry(overrides: Partial<TelemetryConfig> | undefined): TelemetryConfig {
+  if (!overrides) {
+    return { methodology: { ...TELEMETRY_DEFAULTS.methodology } };
+  }
+  const methodology =
+    overrides.methodology && typeof overrides.methodology === 'object'
+      ? { ...TELEMETRY_DEFAULTS.methodology, ...overrides.methodology }
+      : { ...TELEMETRY_DEFAULTS.methodology };
+  return { methodology };
+}
+
+function pickEnum<T extends string>(value: unknown, allowed: readonly T[], fallback: T): T {
+  return typeof value === 'string' && (allowed as readonly string[]).includes(value)
+    ? (value as T)
+    : fallback;
+}
+
+/**
+ * Return the fully-typed pack-local `LumenflowConfig` for the workspace rooted
+ * at `cwd`.
+ *
+ * Mirrors the shape produced by `@lumenflow/core`'s
+ * `getConfig({ projectRoot: cwd }).parse({})` for every field exposed on
+ * `LumenflowConfig`. Drift from core is enforced by
+ * `integration-tests/tests/config-parity.test.ts`.
+ *
+ * Behaviour parity with core:
+ * - Reads `workspace.yaml` relative to `cwd`'s project root via the kernel
+ *   `findProjectRoot` primitive.
+ * - Returns defaults when `workspace.yaml` is absent or lacks a
+ *   `software_delivery` block (graceful fallback, matches core's
+ *   non-`strictWorkspace` mode).
+ * - User-provided values are spread over defaults at the section level, with
+ *   nested merges for sections that have nested objects (state.eventArchival,
+ *   git.push_retry, wu.brief, telemetry.methodology).
+ */
+export function getConfig(cwd: string): LumenflowConfig {
+  let section: SoftwareDeliveryConfig;
+  try {
+    section = readSoftwareDeliveryConfig(cwd);
+  } catch {
+    // Graceful fallback — matches core's non-strictWorkspace behaviour when
+    // workspace.yaml is absent or unreadable.
+    return cloneDefaults();
+  }
+
+  return {
+    version: typeof section['version'] === 'string' ? section['version'] : '1.0.0',
+    directories: getDirectories(cwd),
+    state: getStatePaths(cwd),
+    git: mergeGit(section['git'] as Partial<GitConfig> | undefined),
+    wu: mergeWu(section['wu'] as Partial<WuConfig> | undefined),
+    wuId: mergeSimple<IdFormatConfig>(WU_ID_DEFAULTS, section['wuId']),
+    initiativeId: mergeSimple<IdFormatConfig>(INITIATIVE_ID_DEFAULTS, section['initiativeId']),
+    gates: mergeSimple<GatesConfig>(GATES_DEFAULTS, section['gates']),
+    memory: mergeSimple<MemoryConfig>(MEMORY_DEFAULTS, section['memory']),
+    ui: mergeSimple<UiConfig>(UI_DEFAULTS, section['ui']),
+    yaml: mergeSimple<YamlConfig>(YAML_DEFAULTS, section['yaml']),
+    agents: mergeSimple<AgentsConfig>(AGENTS_DEFAULTS, section['agents']),
+    experimental: mergeSimple<ExperimentalConfig>(EXPERIMENTAL_DEFAULTS, section['experimental']),
+    cleanup: mergeSimple<CleanupConfig>(CLEANUP_DEFAULTS, section['cleanup']),
+    telemetry: mergeTelemetry(section['telemetry'] as Partial<TelemetryConfig> | undefined),
+    methodology:
+      section['methodology'] && typeof section['methodology'] === 'object'
+        ? (section['methodology'] as Record<string, unknown>)
+        : undefined,
+    cloud: mergeSimple<CloudConfig>(CLOUD_DEFAULTS, section['cloud']),
+    lanes:
+      section['lanes'] && typeof section['lanes'] === 'object'
+        ? (section['lanes'] as Record<string, unknown>)
+        : undefined,
+    escalation: mergeSimple<EscalationConfig>(ESCALATION_DEFAULTS, section['escalation']),
+    package_manager: pickEnum<PackageManager>(
+      section['package_manager'],
+      ['pnpm', 'npm', 'yarn', 'bun'] as const,
+      'pnpm',
+    ),
+    test_runner: pickEnum<TestRunner>(
+      section['test_runner'],
+      ['vitest', 'jest', 'mocha'] as const,
+      'vitest',
+    ),
+    build_command:
+      typeof section['build_command'] === 'string' ? section['build_command'] : 'pnpm build',
+  };
+}
+
+function cloneDefaults(): LumenflowConfig {
+  return {
+    ...LUMENFLOW_CONFIG_DEFAULTS,
+    directories: { ...DIRECTORIES_DEFAULTS },
+    state: {
+      ...STATE_PATHS_DEFAULTS,
+      eventArchival: { ...STATE_PATHS_DEFAULTS.eventArchival },
+    },
+    git: { ...GIT_DEFAULTS, push_retry: { ...GIT_DEFAULTS.push_retry } },
+    wu: { ...WU_DEFAULTS, brief: { ...WU_DEFAULTS.brief } },
+    wuId: { ...WU_ID_DEFAULTS },
+    initiativeId: { ...INITIATIVE_ID_DEFAULTS },
+    gates: { ...GATES_DEFAULTS },
+    memory: { ...MEMORY_DEFAULTS },
+    ui: { ...UI_DEFAULTS },
+    yaml: { ...YAML_DEFAULTS },
+    agents: { ...AGENTS_DEFAULTS },
+    experimental: { ...EXPERIMENTAL_DEFAULTS },
+    cleanup: { ...CLEANUP_DEFAULTS },
+    telemetry: { methodology: { ...TELEMETRY_DEFAULTS.methodology } },
+    cloud: { ...CLOUD_DEFAULTS, env_signals: [...CLOUD_DEFAULTS.env_signals] },
+    escalation: { ...ESCALATION_DEFAULTS },
+  };
+}
+
+// Re-export pack-local schema types for downstream consumers migrating off
+// `@lumenflow/core/lumenflow-config-schema`.
+export type {
+  AgentsConfig,
+  CleanupConfig,
+  CloudConfig,
+  DirectoriesConfig,
+  EscalationConfig,
+  EventArchivalConfig,
+  ExperimentalConfig,
+  GatesConfig,
+  GitConfig,
+  IdFormatConfig,
+  LumenflowConfig,
+  MemoryConfig,
+  PackageManager,
+  PushRetryConfig,
+  StatePathsConfig,
+  TelemetryConfig,
+  TestRunner,
+  UiConfig,
+  WuConfig,
+  YamlConfig,
+} from './schemas/lumenflow-config-schema-types.js';

package/packs/software-delivery/src/constants/backlog-patterns.ts

@@ -0,0 +1,31 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Backlog Parsing Patterns
+ *
+ * Centralizes patterns for parsing status.md and backlog.md files.
+ * Used by lane-checker.ts and related backlog utilities.
+ */
+
+/** Markdown section header patterns for In Progress section */
+export const IN_PROGRESS_HEADERS = ['## in progress', '## 🔧 in progress'];
+
+/**
+ * Pattern for extracting WU ID from backlog links.
+ * Matches: [WU-123 — Title text](path/to/file.yaml)
+ * Captures: WU ID (e.g., "WU-123")
+ */
+export const WU_LINK_PATTERN = /\[([A-Z]+-\d+)\s*—\s*[^\]]+\]\([^)]+\)/gi;
+
+/**
+ * Check if a line matches an In Progress section header.
+ * @param {string} line - Line to check (will be trimmed and lowercased)
+ * @returns {boolean} True if line is an In Progress header
+ */
+export function isInProgressHeader(line: string) {
+  const normalized = line.trim().toLowerCase();
+  return IN_PROGRESS_HEADERS.some(
+    (header) => normalized === header || normalized.startsWith(header),
+  );
+}

package/packs/software-delivery/src/constants/client-ids.ts

@@ -0,0 +1,19 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Canonical client IDs for client-specific integrations and config keys.
+ *
+ * Kept in a standalone module so config schema can depend on these
+ * constants without importing context/hook modules.
+ */
+export const LUMENFLOW_CLIENT_IDS = {
+  CLAUDE_CODE: 'claude-code',
+  CODEX_CLI: 'codex-cli',
+  CURSOR: 'cursor',
+  GEMINI_CLI: 'gemini-cli',
+  WINDSURF: 'windsurf',
+} as const;
+
+/** Type for supported client IDs with integration support */
+export type LumenflowClientId = (typeof LUMENFLOW_CLIENT_IDS)[keyof typeof LUMENFLOW_CLIENT_IDS];

package/packs/software-delivery/src/constants/config-contract.ts

@@ -0,0 +1,7 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// WU-2681 (INIT-058 L2e): Shim — real module lives in @lumenflow/kernel/primitives/workspace-constants.
+// Re-export preserves the `@lumenflow/packs-software-delivery/constants/config-contract` subpath
+// for existing consumers (including core shims) until Layer 7 removes the shim.
+export * from '@lumenflow/kernel/primitives/workspace-constants';

package/packs/software-delivery/src/constants/docs-layout-presets.ts

@@ -0,0 +1,50 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Canonical docs layout presets used across scaffolding and defaults.
+ *
+ * Keeping presets in one place avoids path-literal drift between:
+ * - schema defaults
+ * - init docs-structure mapping
+ * - runtime prompt/path helpers
+ */
+
+function buildDocsLayout(operations: string, tasks: string, adrDir: string) {
+  const frameworkRoot = `${operations}/_frameworks/lumenflow`;
+  const onboarding = `${frameworkRoot}/agent/onboarding`;
+
+  return {
+    operations,
+    tasks,
+    adrDir,
+    onboarding,
+    quickRefLink: `${onboarding}/quick-ref-commands.md`,
+    completeGuidePath: `${frameworkRoot}/lumenflow-complete.md`,
+    quickRefPath: `${onboarding}/quick-ref-commands.md`,
+    startingPromptPath: `${onboarding}/starting-prompt.md`,
+    sizingGuidePath: `${frameworkRoot}/wu-sizing-guide.md`,
+    governancePath: `${operations}/governance/project-governance.md`,
+  } as const;
+}
+
+const DOCS_ROOT = 'docs';
+const SIMPLE_TASKS_PATH = `${DOCS_ROOT}/tasks`;
+const SIMPLE_ADR_PATH = `${DOCS_ROOT}/architecture-decisions`;
+const ARC42_OPERATIONS_PATH = [DOCS_ROOT, 'operations'].join('/');
+const ARC42_TASKS_PATH = [ARC42_OPERATIONS_PATH, 'tasks'].join('/');
+const ARC42_ADR_PATH = [DOCS_ROOT, '09-architecture-decisions'].join('/');
+
+export const DOCS_LAYOUT_PRESETS = {
+  simple: buildDocsLayout(DOCS_ROOT, SIMPLE_TASKS_PATH, SIMPLE_ADR_PATH),
+  arc42: buildDocsLayout(ARC42_OPERATIONS_PATH, ARC42_TASKS_PATH, ARC42_ADR_PATH),
+} as const;
+
+export type DocsLayoutType = keyof typeof DOCS_LAYOUT_PRESETS;
+export type DocsLayoutPreset = (typeof DOCS_LAYOUT_PRESETS)[DocsLayoutType];
+
+export const DEFAULT_DOCS_LAYOUT: DocsLayoutType = 'simple';
+
+export function getDocsLayoutPreset(layout: DocsLayoutType): DocsLayoutPreset {
+  return DOCS_LAYOUT_PRESETS[layout];
+}

package/packs/software-delivery/src/constants/duration-constants.ts

@@ -0,0 +1,20 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Duration Constants — Re-export shim (ADR-012, INIT-058 Layer 1, WU-2664).
+ *
+ * Moved to `@lumenflow/kernel/primitives/duration-utils`. This shim preserves
+ * the legacy import path for in-repo consumers until the barrel slim in
+ * Layer 7.
+ *
+ * @module constants/duration-constants
+ */
+
+export {
+  MS_PER_SECOND,
+  MS_PER_MINUTE,
+  MS_PER_HOUR,
+  MS_PER_DAY,
+  DURATION_MS,
+} from '@lumenflow/kernel/primitives/duration-utils';

package/packs/software-delivery/src/constants/gate-constants.ts

@@ -0,0 +1,32 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Gate Configuration Constants
+ *
+ * WU-2010: Centralizes magic numbers for gates, including
+ * pre-commit/local gates AND config-driven gate thresholds.
+ * Used by gates-pre-commit.ts, gates-local.ts, gates-config.ts,
+ * and lumenflow-config-schema.ts.
+ */
+
+/** Gate execution configuration */
+export const GATE_CONFIG = {
+  /** Maximum execution time per gate step (ms) */
+  TIMEOUT_MS: 180000,
+
+  /** Maximum file size allowed in commits (bytes) - 5MB */
+  MAX_FILE_SIZE_BYTES: 5 * 1024 * 1024,
+
+  /** Total number of gates (for progress display) */
+  TOTAL_GATES: 14,
+};
+
+/** Default minimum code coverage percentage (used by TDD methodology) */
+export const DEFAULT_MIN_COVERAGE = 90;
+
+/** Default maximum allowed ESLint warnings before gate failure */
+export const DEFAULT_MAX_ESLINT_WARNINGS = 100;
+
+/** Default timeout for individual gate commands in gates-config (ms) */
+export const DEFAULT_GATE_TIMEOUT_MS = 120_000; // 2 minutes

package/packs/software-delivery/src/constants/index.ts

@@ -0,0 +1,29 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Barrel for pack-local constants. Populated by Layer 2 of INIT-058.
+// WU-2677: moved wu-statuses, object-guards, config-contract, gate-constants from @lumenflow/core.
+// WU-2674: added wu-ui-constants (leaf supplying EMOJI/STRING_LITERALS to policy/coverage-gate).
+// WU-2678: added wu-paths-constants, docs-layout-presets from @lumenflow/core (L4 sandbox cohort deps).
+// WU-2679: added wu-git-constants, wu-cli-constants, client-ids, wu-domain-constants, wu-type-helpers
+// (L2c finish — eliminates wu-constants barrel as cross-cohort coupling point).
+// WU-2680: added wu-validation-constants (L2d single leaf — unblocks lane-inference.ts migration).
+// WU-2698: added backlog-patterns, duration-constants, section-headings, wu-id-format
+// (L4-prep narrow — pure leaves + rewrites from @lumenflow/core).
+export * from './wu-statuses.js';
+export * from './object-guards.js';
+export * from './config-contract.js';
+export * from './gate-constants.js';
+export * from './wu-ui-constants.js';
+export * from './docs-layout-presets.js';
+export * from './wu-paths-constants.js';
+export * from './wu-git-constants.js';
+export * from './wu-cli-constants.js';
+export * from './client-ids.js';
+export * from './wu-domain-constants.js';
+export * from './wu-type-helpers.js';
+export * from './wu-validation-constants.js';
+export * from './backlog-patterns.js';
+export * from './duration-constants.js';
+export * from './section-headings.js';
+export * from './wu-id-format.js';

package/packs/software-delivery/src/constants/lock-constants.ts

@@ -0,0 +1,35 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Shared Lock Constants
+ *
+ * WU-2010: Consolidated lock-related constants used by both
+ * merge-lock.ts and cleanup-lock.ts to eliminate duplication.
+ *
+ * @module constants/lock-constants
+ */
+
+/**
+ * Default timeout for waiting to acquire a lock (ms).
+ * After this time, acquisition fails if the lock is held.
+ */
+export const LOCK_TIMEOUT_MS = 30_000; // 30 seconds
+
+/**
+ * Time after which a merge lock is considered stale (ms).
+ * Should be greater than expected merge operation duration.
+ */
+export const MERGE_LOCK_STALE_MS = 60_000; // 60 seconds
+
+/**
+ * Time after which a cleanup lock is considered stale (ms).
+ * Cleanup is slower than merge, so a longer timeout is used.
+ */
+export const CLEANUP_LOCK_STALE_MS = 5 * 60 * 1_000; // 5 minutes
+
+/**
+ * Polling interval for lock acquisition retries (ms).
+ * Used by both merge and cleanup lock loops.
+ */
+export const LOCK_POLL_INTERVAL_MS = 500;

package/packs/software-delivery/src/constants/object-guards.ts

@@ -0,0 +1,12 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Object Guards — Re-export shim (ADR-012, INIT-058 Layer 2f, WU-2685).
+ *
+ * Relocated to `@lumenflow/kernel/primitives/object-guards` because the
+ * utilities are pack-agnostic type predicates. Shim preserves the legacy
+ * pack import path for in-repo consumers until Layer 7 barrel slim.
+ */
+
+export * from '@lumenflow/kernel/primitives/object-guards';

package/packs/software-delivery/src/constants/section-headings.ts

@@ -0,0 +1,107 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Section Headings Constants
+ *
+ * Centralized section heading defaults for backlog.md and status.md
+ * Eliminates magic strings scattered throughout wu-* tools
+ *
+ * Usage: Use getSectionHeadingsWithDefaults() to get frontmatter-configured
+ * headings with sensible fallbacks if frontmatter is missing/malformed
+ *
+ * WU-2698 (INIT-058 L4-prep narrow): moved from @lumenflow/core/src/section-headings.ts.
+ * The `getSectionHeadings` helper (previously imported from core's backlog-parser) is
+ * inlined here to keep the pack core-free.
+ */
+
+import { BACKLOG_SECTIONS, STATUS_SECTIONS } from './wu-ui-constants.js';
+
+/**
+ * Section configuration from frontmatter.
+ */
+interface SectionConfig {
+  heading?: string;
+}
+
+/**
+ * Extract section headings from frontmatter.
+ *
+ * Inlined from @lumenflow/core/src/backlog-parser.ts (WU-2698) so that this
+ * module does not depend on core during the INIT-058 L4-prep migration.
+ *
+ * @param {object|null} frontmatter - Parsed frontmatter object.
+ * @returns {object} Map of section names to heading strings (e.g., {ready: "## 🚀 Ready"}).
+ */
+function getSectionHeadings(frontmatter: Record<string, unknown> | null): Record<string, string> {
+  if (!frontmatter) {
+    return {};
+  }
+  const sections = (frontmatter as { sections?: Record<string, SectionConfig> }).sections;
+  if (!sections) {
+    return {};
+  }
+
+  const headings: Record<string, string> = {};
+  for (const [sectionName, sectionConfig] of Object.entries(sections)) {
+    if (sectionConfig && typeof sectionConfig.heading === 'string') {
+      headings[sectionName] = sectionConfig.heading;
+    }
+  }
+
+  return headings;
+}
+
+/**
+ * Default section headings (fallbacks when frontmatter is missing)
+ * Re-exports from wu-ui-constants.ts for backwards compatibility
+ */
+export const DEFAULT_SECTION_HEADINGS = {
+  backlog: {
+    ready: BACKLOG_SECTIONS.READY,
+    in_progress: BACKLOG_SECTIONS.IN_PROGRESS,
+    blocked: BACKLOG_SECTIONS.BLOCKED,
+    done: BACKLOG_SECTIONS.DONE,
+  },
+  status: {
+    in_progress: STATUS_SECTIONS.IN_PROGRESS,
+    completed: STATUS_SECTIONS.COMPLETED,
+    blocked: STATUS_SECTIONS.BLOCKED,
+  },
+};
+
+/**
+ * Get section headings with frontmatter override + defaults
+ *
+ * Replaces scattered pattern: headings.done || '## ✅ Done'
+ * Centralizes fallback logic for consistent heading resolution
+ *
+ * @param {object|null} frontmatter - Parsed frontmatter from backlog.md/status.md
+ * @param {'backlog'|'status'} docType - Document type
+ * @returns {object} Section headings (configured or default)
+ */
+export function getSectionHeadingsWithDefaults(
+  frontmatter: Record<string, unknown> | null,
+  docType: keyof typeof DEFAULT_SECTION_HEADINGS = 'backlog',
+) {
+  const defaults = DEFAULT_SECTION_HEADINGS[docType] as {
+    ready?: string;
+    in_progress?: string;
+    blocked?: string;
+    done?: string;
+    completed?: string;
+  };
+  const configured = frontmatter ? getSectionHeadings(frontmatter) : {};
+
+  return {
+    ready: configured.ready || defaults.ready || DEFAULT_SECTION_HEADINGS.backlog.ready,
+    in_progress:
+      configured.in_progress ||
+      defaults.in_progress ||
+      DEFAULT_SECTION_HEADINGS.backlog.in_progress,
+    blocked: configured.blocked || defaults.blocked || DEFAULT_SECTION_HEADINGS.backlog.blocked,
+    done: configured.done || defaults.done || DEFAULT_SECTION_HEADINGS.backlog.done,
+    completed:
+      configured.completed || defaults.completed || DEFAULT_SECTION_HEADINGS.status.completed,
+  };
+}