pumuki 6.3.13 → 6.3.14

package/integrations/lifecycle/cli.ts

@@ -4,6 +4,14 @@ import { runLifecycleRemove } from './remove';
 import { readLifecycleStatus } from './status';
 import { runLifecycleUninstall } from './uninstall';
 import { runLifecycleUpdate } from './update';
+import {
+  closeSddSession,
+  evaluateSddPolicy,
+  openSddSession,
+  readSddStatus,
+  refreshSddSession,
+  type SddStage,
+} from '../sdd';
 
 type LifecycleCommand =
   | 'install'
@@ -11,12 +19,23 @@ type LifecycleCommand =
   | 'remove'
   | 'update'
   | 'doctor'
-  | 'status';
+  | 'status'
+  | 'sdd';
+
+type SddCommand = 'status' | 'validate' | 'session';
+
+type SddSessionAction = 'open' | 'refresh' | 'close';
 
 type ParsedArgs = {
   command: LifecycleCommand;
   purgeArtifacts: boolean;
   updateSpec?: string;
+  json: boolean;
+  sddCommand?: SddCommand;
+  sddStage?: SddStage;
+  sddSessionAction?: SddSessionAction;
+  sddChangeId?: string;
+  sddTtlMinutes?: number;
 };
 
 const HELP_TEXT = `
@@ -27,6 +46,11 @@ Pumuki lifecycle commands:
   pumuki update [--latest|--spec=<package-spec>]
   pumuki doctor
   pumuki status
+  pumuki sdd status [--json]
+  pumuki sdd validate [--stage=PRE_WRITE|PRE_COMMIT|PRE_PUSH|CI] [--json]
+  pumuki sdd session --open --change=<change-id> [--ttl-minutes=<n>] [--json]
+  pumuki sdd session --refresh [--ttl-minutes=<n>] [--json]
+  pumuki sdd session --close [--json]
 `.trim();
 
 const isLifecycleCommand = (value: string): value is LifecycleCommand =>
@@ -35,7 +59,21 @@ const isLifecycleCommand = (value: string): value is LifecycleCommand =>
   value === 'remove' ||
   value === 'update' ||
   value === 'doctor' ||
-  value === 'status';
+  value === 'status' ||
+  value === 'sdd';
+
+const parseSddStage = (value: string | undefined): SddStage => {
+  const normalized = (value ?? 'PRE_COMMIT').trim().toUpperCase();
+  if (
+    normalized === 'PRE_WRITE' ||
+    normalized === 'PRE_COMMIT' ||
+    normalized === 'PRE_PUSH' ||
+    normalized === 'CI'
+  ) {
+    return normalized;
+  }
+  throw new Error(`Unsupported SDD stage "${value}". Use PRE_WRITE, PRE_COMMIT, PRE_PUSH or CI.`);
+};
 
 export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs => {
   const commandRaw = argv[0];
@@ -48,7 +86,105 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
 
   let purgeArtifacts = false;
   let updateSpec: string | undefined;
+  let json = false;
+  let sddCommand: SddCommand | undefined;
+  let sddStage: SddStage | undefined;
+  let sddSessionAction: SddSessionAction | undefined;
+  let sddChangeId: string | undefined;
+  let sddTtlMinutes: number | undefined;
+
+  if (commandRaw === 'sdd') {
+    const subcommandRaw = argv[1] ?? 'status';
+    if (
+      subcommandRaw !== 'status' &&
+      subcommandRaw !== 'validate' &&
+      subcommandRaw !== 'session'
+    ) {
+      throw new Error(`Unsupported SDD subcommand "${subcommandRaw}".\n\n${HELP_TEXT}`);
+    }
+    sddCommand = subcommandRaw;
+
+    for (const arg of argv.slice(2)) {
+      if (arg === '--json') {
+        json = true;
+        continue;
+      }
+      if (arg.startsWith('--stage=')) {
+        sddStage = parseSddStage(arg.slice('--stage='.length));
+        continue;
+      }
+      if (arg === '--open') {
+        sddSessionAction = 'open';
+        continue;
+      }
+      if (arg === '--refresh') {
+        sddSessionAction = 'refresh';
+        continue;
+      }
+      if (arg === '--close') {
+        sddSessionAction = 'close';
+        continue;
+      }
+      if (arg.startsWith('--change=')) {
+        sddChangeId = arg.slice('--change='.length).trim();
+        continue;
+      }
+      if (arg.startsWith('--ttl-minutes=')) {
+        const minutes = Number.parseInt(arg.slice('--ttl-minutes='.length), 10);
+        if (!Number.isFinite(minutes) || minutes <= 0) {
+          throw new Error(`Invalid --ttl-minutes value "${arg}".`);
+        }
+        sddTtlMinutes = minutes;
+        continue;
+      }
+      throw new Error(`Unsupported argument "${arg}".\n\n${HELP_TEXT}`);
+    }
+
+    if (sddCommand === 'status') {
+      return {
+        command: commandRaw,
+        purgeArtifacts: false,
+        json,
+        sddCommand,
+      };
+    }
+    if (sddCommand === 'validate') {
+      return {
+        command: commandRaw,
+        purgeArtifacts: false,
+        json,
+        sddCommand,
+        sddStage: sddStage ?? 'PRE_COMMIT',
+      };
+    }
+
+    if (!sddSessionAction) {
+      throw new Error(
+        `Missing SDD session action. Use one of --open | --refresh | --close.\n\n${HELP_TEXT}`
+      );
+    }
+    if (sddSessionAction === 'open' && (!sddChangeId || sddChangeId.length === 0)) {
+      throw new Error(`Missing --change=<change-id> for "pumuki sdd session --open".\n\n${HELP_TEXT}`);
+    }
+    if (sddSessionAction !== 'open' && sddChangeId) {
+      throw new Error(`--change is only supported with "--open".\n\n${HELP_TEXT}`);
+    }
+    return {
+      command: commandRaw,
+      purgeArtifacts: false,
+      json,
+      sddCommand,
+      sddSessionAction,
+      sddChangeId,
+      sddTtlMinutes,
+    };
+  }
+
   for (const arg of argv.slice(1)) {
+    if (arg === '--json') {
+      json = true;
+      continue;
+    }
     if (arg === '--purge-artifacts') {
       purgeArtifacts = true;
       continue;
@@ -69,6 +205,7 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
     command: commandRaw,
     purgeArtifacts,
     updateSpec,
+    json,
   };
 };
 
@@ -109,6 +246,14 @@ export const runLifecycleCli = async (
         console.log(
           `[pumuki] installed ${result.version} at ${result.repoRoot} (hooks changed: ${result.changedHooks.join(', ') || 'none'})`
         );
+        if (result.openSpecBootstrap) {
+          console.log(
+            `[pumuki] openspec bootstrap: installed=${result.openSpecBootstrap.packageInstalled ? 'yes' : 'no'} project=${result.openSpecBootstrap.projectInitialized ? 'yes' : 'no'} actions=${result.openSpecBootstrap.actions.join(', ') || 'none'}`
+          );
+          if (result.openSpecBootstrap.skippedReason === 'NO_PACKAGE_JSON') {
+            console.log('[pumuki] openspec bootstrap skipped npm install (package.json not found)');
+          }
+        }
         return 0;
       }
       case 'uninstall': {
@@ -142,6 +287,9 @@ export const runLifecycleCli = async (
         console.log(
           `[pumuki] updated to ${result.targetSpec} at ${result.repoRoot} (hooks changed: ${result.reinstallHooksChanged.join(', ') || 'none'})`
         );
+        console.log(
+          `[pumuki] openspec compatibility: migrated-legacy=${result.openSpecCompatibility.migratedLegacyPackage ? 'yes' : 'no'} actions=${result.openSpecCompatibility.actions.join(', ') || 'none'}`
+        );
         return 0;
       }
       case 'doctor': {
@@ -151,16 +299,104 @@ export const runLifecycleCli = async (
       }
       case 'status': {
         const status = readLifecycleStatus();
-        console.log(`[pumuki] repo: ${status.repoRoot}`);
-        console.log(`[pumuki] package version: ${status.packageVersion}`);
-        console.log(`[pumuki] lifecycle installed: ${status.lifecycleState.installed ?? 'false'}`);
-        console.log(`[pumuki] lifecycle version: ${status.lifecycleState.version ?? 'unknown'}`);
-        console.log(
-          `[pumuki] hooks: pre-commit=${status.hookStatus['pre-commit'].managedBlockPresent ? 'managed' : 'missing'}, pre-push=${status.hookStatus['pre-push'].managedBlockPresent ? 'managed' : 'missing'}`
-        );
-        console.log(
-          `[pumuki] tracked node_modules paths: ${status.trackedNodeModulesCount}`
-        );
+        if (parsed.json) {
+          console.log(JSON.stringify(status, null, 2));
+        } else {
+          console.log(`[pumuki] repo: ${status.repoRoot}`);
+          console.log(`[pumuki] package version: ${status.packageVersion}`);
+          console.log(`[pumuki] lifecycle installed: ${status.lifecycleState.installed ?? 'false'}`);
+          console.log(`[pumuki] lifecycle version: ${status.lifecycleState.version ?? 'unknown'}`);
+          console.log(
+            `[pumuki] hooks: pre-commit=${status.hookStatus['pre-commit'].managedBlockPresent ? 'managed' : 'missing'}, pre-push=${status.hookStatus['pre-push'].managedBlockPresent ? 'managed' : 'missing'}`
+          );
+          console.log(
+            `[pumuki] tracked node_modules paths: ${status.trackedNodeModulesCount}`
+          );
+        }
+        return 0;
+      }
+      case 'sdd': {
+        if (parsed.sddCommand === 'status') {
+          const sddStatus = readSddStatus();
+          if (parsed.json) {
+            console.log(JSON.stringify(sddStatus, null, 2));
+          } else {
+            console.log(`[pumuki][sdd] repo: ${sddStatus.repoRoot}`);
+            console.log(
+              `[pumuki][sdd] openspec: installed=${sddStatus.openspec.installed ? 'yes' : 'no'} version=${sddStatus.openspec.version ?? 'unknown'}`
+            );
+            console.log(
+              `[pumuki][sdd] openspec compatibility: compatible=${sddStatus.openspec.compatible ? 'yes' : 'no'} minimum=${sddStatus.openspec.minimumVersion} recommended=${sddStatus.openspec.recommendedVersion} parsed=${sddStatus.openspec.parsedVersion ?? 'unknown'}`
+            );
+            console.log(
+              `[pumuki][sdd] openspec project initialized: ${sddStatus.openspec.projectInitialized ? 'yes' : 'no'}`
+            );
+            console.log(
+              `[pumuki][sdd] session: active=${sddStatus.session.active ? 'yes' : 'no'} valid=${sddStatus.session.valid ? 'yes' : 'no'} change=${sddStatus.session.changeId ?? 'none'}`
+            );
+            if (typeof sddStatus.session.remainingSeconds === 'number') {
+              console.log(
+                `[pumuki][sdd] session remaining seconds: ${sddStatus.session.remainingSeconds}`
+              );
+            }
+          }
+          return 0;
+        }
+        if (parsed.sddCommand === 'validate') {
+          const result = evaluateSddPolicy({
+            stage: parsed.sddStage ?? 'PRE_COMMIT',
+          });
+          if (parsed.json) {
+            console.log(JSON.stringify(result, null, 2));
+          } else {
+            console.log(
+              `[pumuki][sdd] stage=${result.stage} allowed=${result.decision.allowed ? 'yes' : 'no'} code=${result.decision.code}`
+            );
+            console.log(`[pumuki][sdd] ${result.decision.message}`);
+            if (result.validation) {
+              console.log(
+                `[pumuki][sdd] validation: ok=${result.validation.ok ? 'yes' : 'no'} failed=${result.validation.totals.failed} errors=${result.validation.issues.errors}`
+              );
+            }
+          }
+          return result.decision.allowed ? 0 : 1;
+        }
+        if (parsed.sddCommand === 'session') {
+          if (parsed.sddSessionAction === 'open') {
+            const session = openSddSession({
+              changeId: parsed.sddChangeId ?? '',
+              ttlMinutes: parsed.sddTtlMinutes,
+            });
+            if (parsed.json) {
+              console.log(JSON.stringify(session, null, 2));
+            } else {
+              console.log(
+                `[pumuki][sdd] session opened: change=${session.changeId} ttlMinutes=${session.ttlMinutes ?? 'unknown'} valid=${session.valid ? 'yes' : 'no'}`
+              );
+            }
+            return 0;
+          }
+          if (parsed.sddSessionAction === 'refresh') {
+            const session = refreshSddSession({
+              ttlMinutes: parsed.sddTtlMinutes,
+            });
+            if (parsed.json) {
+              console.log(JSON.stringify(session, null, 2));
+            } else {
+              console.log(
+                `[pumuki][sdd] session refreshed: change=${session.changeId ?? 'none'} ttlMinutes=${session.ttlMinutes ?? 'unknown'} valid=${session.valid ? 'yes' : 'no'}`
+              );
+            }
+            return 0;
+          }
+          const session = closeSddSession();
+          if (parsed.json) {
+            console.log(JSON.stringify(session, null, 2));
+          } else {
+            console.log('[pumuki][sdd] session closed');
+          }
+          return 0;
+        }
         return 0;
       }
       default:

package/integrations/lifecycle/constants.ts

@@ -6,6 +6,7 @@ export const PUMUKI_CONFIG_KEYS = {
   version: 'pumuki.version',
   hooks: 'pumuki.hooks',
   installedAt: 'pumuki.installed-at',
+  openSpecManagedArtifacts: 'pumuki.openspec.managed-artifacts',
 } as const;
 
 export const PUMUKI_MANAGED_HOOKS = ['pre-commit', 'pre-push'] as const;

package/integrations/lifecycle/gitService.ts

@@ -22,6 +22,7 @@ export class LifecycleGitService implements ILifecycleGitService {
     return execFileSync('git', args, {
       cwd,
       encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
     });
   }
 

package/integrations/lifecycle/install.ts

@@ -1,18 +1,23 @@
 import { installPumukiHooks } from './hookManager';
 import { LifecycleGitService, type ILifecycleGitService } from './gitService';
 import { doctorHasBlockingIssues, runLifecycleDoctor } from './doctor';
+import { runOpenSpecBootstrap, type OpenSpecBootstrapResult } from './openSpecBootstrap';
+import { LifecycleNpmService, type ILifecycleNpmService } from './npmService';
 import { getCurrentPumukiVersion } from './packageInfo';
-import { writeLifecycleState } from './state';
+import { readOpenSpecManagedArtifacts, writeLifecycleState } from './state';
 
 export type LifecycleInstallResult = {
   repoRoot: string;
   version: string;
   changedHooks: ReadonlyArray<string>;
+  openSpecBootstrap?: OpenSpecBootstrapResult;
 };
 
 export const runLifecycleInstall = (params?: {
   cwd?: string;
   git?: ILifecycleGitService;
+  npm?: ILifecycleNpmService;
+  bootstrapOpenSpec?: boolean;
 }): LifecycleInstallResult => {
   const git = params?.git ?? new LifecycleGitService();
   const report = runLifecycleDoctor({
@@ -28,17 +33,35 @@ export const runLifecycleInstall = (params?: {
     );
   }
 
+  const shouldBootstrapOpenSpec =
+    params?.bootstrapOpenSpec ?? process.env.PUMUKI_SKIP_OPENSPEC_BOOTSTRAP !== '1';
+
+  const openSpecBootstrap = shouldBootstrapOpenSpec
+    ? runOpenSpecBootstrap({
+      repoRoot: report.repoRoot,
+      npm: params?.npm ?? new LifecycleNpmService(),
+    })
+    : undefined;
+
   const hookResult = installPumukiHooks(report.repoRoot);
   const version = getCurrentPumukiVersion();
+  const mergedOpenSpecArtifacts = new Set(
+    readOpenSpecManagedArtifacts(git, report.repoRoot)
+  );
+  for (const artifact of openSpecBootstrap?.managedArtifacts ?? []) {
+    mergedOpenSpecArtifacts.add(artifact);
+  }
   writeLifecycleState({
     git,
     repoRoot: report.repoRoot,
     version,
+    openSpecManagedArtifacts: Array.from(mergedOpenSpecArtifacts),
   });
 
   return {
     repoRoot: report.repoRoot,
     version,
     changedHooks: hookResult.changedHooks,
+    openSpecBootstrap,
   };
 };

package/integrations/lifecycle/openSpecBootstrap.ts

@@ -0,0 +1,190 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  detectOpenSpecInstallation,
+  evaluateOpenSpecCompatibility,
+  isOpenSpecProjectInitialized,
+  OPENSPEC_NPM_PACKAGE_NAME,
+} from '../sdd/openSpecCli';
+import { LifecycleNpmService, type ILifecycleNpmService } from './npmService';
+
+export type OpenSpecBootstrapResult = {
+  repoRoot: string;
+  packageInstalled: boolean;
+  projectInitialized: boolean;
+  actions: ReadonlyArray<string>;
+  managedArtifacts: ReadonlyArray<string>;
+  skippedReason?: 'NO_PACKAGE_JSON';
+};
+
+type PackageDependencySource = 'dependencies' | 'devDependencies' | 'none';
+
+type PackageJson = {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+};
+
+const readPackageJson = (repoRoot: string): PackageJson | undefined => {
+  const packageJsonPath = join(repoRoot, 'package.json');
+  if (!existsSync(packageJsonPath)) {
+    return undefined;
+  }
+  return JSON.parse(readFileSync(packageJsonPath, 'utf8')) as PackageJson;
+};
+
+const resolveDependencySource = (
+  packageJson: PackageJson | undefined,
+  dependencyName: string
+): PackageDependencySource => {
+  if (!packageJson) {
+    return 'none';
+  }
+  if (typeof packageJson.dependencies?.[dependencyName] === 'string') {
+    return 'dependencies';
+  }
+  if (typeof packageJson.devDependencies?.[dependencyName] === 'string') {
+    return 'devDependencies';
+  }
+  return 'none';
+};
+
+const OPENSPEC_LEGACY_NPM_PACKAGE_NAME = 'openspec';
+const OPENSPEC_PROJECT_MD = 'openspec/project.md';
+const OPENSPEC_ARCHIVE_GITKEEP = 'openspec/changes/archive/.gitkeep';
+const OPENSPEC_SPECS_GITKEEP = 'openspec/specs/.gitkeep';
+
+export type OpenSpecCompatibilityMigrationResult = {
+  repoRoot: string;
+  migratedLegacyPackage: boolean;
+  migratedFrom?: Exclude<PackageDependencySource, 'none'>;
+  actions: ReadonlyArray<string>;
+};
+
+const scaffoldOpenSpecProject = (repoRoot: string): ReadonlyArray<string> => {
+  const openspecRoot = join(repoRoot, 'openspec');
+  const changesRoot = join(openspecRoot, 'changes');
+  const archiveRoot = join(changesRoot, 'archive');
+  const specsRoot = join(openspecRoot, 'specs');
+
+  const projectDescriptionPath = join(repoRoot, OPENSPEC_PROJECT_MD);
+  const archiveKeepPath = join(repoRoot, OPENSPEC_ARCHIVE_GITKEEP);
+  const specsKeepPath = join(repoRoot, OPENSPEC_SPECS_GITKEEP);
+
+  const managedArtifacts: string[] = [];
+
+  const ensureDirectory = (directoryPath: string): void => {
+    if (!existsSync(directoryPath)) {
+      mkdirSync(directoryPath, { recursive: true });
+    }
+  };
+
+  ensureDirectory(openspecRoot);
+  ensureDirectory(changesRoot);
+  ensureDirectory(archiveRoot);
+  ensureDirectory(specsRoot);
+
+  if (!existsSync(projectDescriptionPath)) {
+    writeFileSync(
+      projectDescriptionPath,
+      [
+        '# OpenSpec Project',
+        '',
+        'This repository is bootstrapped by Pumuki for SDD/OpenSpec workflows.',
+        'Update this document with project context and design constraints.',
+        '',
+      ].join('\n'),
+      'utf8'
+    );
+    managedArtifacts.push(OPENSPEC_PROJECT_MD);
+  }
+
+  if (!existsSync(archiveKeepPath)) {
+    writeFileSync(archiveKeepPath, '', 'utf8');
+    managedArtifacts.push(OPENSPEC_ARCHIVE_GITKEEP);
+  }
+
+  if (!existsSync(specsKeepPath)) {
+    writeFileSync(specsKeepPath, '', 'utf8');
+    managedArtifacts.push(OPENSPEC_SPECS_GITKEEP);
+  }
+
+  return managedArtifacts;
+};
+
+export const runOpenSpecCompatibilityMigration = (params: {
+  repoRoot: string;
+  npm?: ILifecycleNpmService;
+}): OpenSpecCompatibilityMigrationResult => {
+  const npm = params.npm ?? new LifecycleNpmService();
+  const packageJson = readPackageJson(params.repoRoot);
+  const legacySource = resolveDependencySource(
+    packageJson,
+    OPENSPEC_LEGACY_NPM_PACKAGE_NAME
+  );
+  if (legacySource === 'none') {
+    return {
+      repoRoot: params.repoRoot,
+      migratedLegacyPackage: false,
+      actions: [],
+    };
+  }
+
+  const actions: string[] = [];
+  npm.runNpm(['uninstall', OPENSPEC_LEGACY_NPM_PACKAGE_NAME], params.repoRoot);
+  actions.push(`npm-uninstall:${OPENSPEC_LEGACY_NPM_PACKAGE_NAME}`);
+
+  const installArgs =
+    legacySource === 'dependencies'
+      ? ['install', '--save-exact', `${OPENSPEC_NPM_PACKAGE_NAME}@latest`]
+      : ['install', '--save-dev', '--save-exact', `${OPENSPEC_NPM_PACKAGE_NAME}@latest`];
+
+  npm.runNpm(installArgs, params.repoRoot);
+  actions.push(`npm-install:${OPENSPEC_NPM_PACKAGE_NAME}@latest`);
+
+  return {
+    repoRoot: params.repoRoot,
+    migratedLegacyPackage: true,
+    migratedFrom: legacySource,
+    actions,
+  };
+};
+
+export const runOpenSpecBootstrap = (params: {
+  repoRoot: string;
+  npm?: ILifecycleNpmService;
+}): OpenSpecBootstrapResult => {
+  const npm = params.npm ?? new LifecycleNpmService();
+  const actions: string[] = [];
+
+  const installation = detectOpenSpecInstallation(params.repoRoot);
+  const compatibility = evaluateOpenSpecCompatibility(installation);
+  let packageInstalled = installation.installed;
+  const packageJsonPath = join(params.repoRoot, 'package.json');
+  const hasPackageJson = existsSync(packageJsonPath);
+
+  if ((!packageInstalled || !compatibility.compatible) && hasPackageJson) {
+    npm.runNpm(
+      ['install', '--save-dev', '--save-exact', `${OPENSPEC_NPM_PACKAGE_NAME}@latest`],
+      params.repoRoot
+    );
+    packageInstalled = true;
+    actions.push(`npm-install:${OPENSPEC_NPM_PACKAGE_NAME}@latest`);
+  }
+
+  const projectInitializedBefore = isOpenSpecProjectInitialized(params.repoRoot);
+  const managedArtifacts = !projectInitializedBefore
+    ? scaffoldOpenSpecProject(params.repoRoot)
+    : [];
+  if (managedArtifacts.length > 0) {
+    actions.push('scaffold:openspec-project');
+  }
+
+  return {
+    repoRoot: params.repoRoot,
+    packageInstalled,
+    projectInitialized: isOpenSpecProjectInitialized(params.repoRoot),
+    actions,
+    managedArtifacts,
+    skippedReason: !packageInstalled && !hasPackageJson ? 'NO_PACKAGE_JSON' : undefined,
+  };
+};

package/integrations/lifecycle/state.ts

@@ -6,6 +6,26 @@ export type LifecycleState = {
   version?: string;
   hooks?: string;
   installedAt?: string;
+  openSpecManagedArtifacts?: string;
+};
+
+const parseManagedArtifacts = (raw: string | undefined): string[] => {
+  if (typeof raw !== 'string' || raw.trim().length === 0) {
+    return [];
+  }
+  return raw
+    .split(',')
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0);
+};
+
+const serializeManagedArtifacts = (artifacts: ReadonlyArray<string>): string | undefined => {
+  const unique = Array.from(new Set(artifacts.map((value) => value.trim()).filter((value) => value.length > 0)))
+    .sort();
+  if (unique.length === 0) {
+    return undefined;
+  }
+  return unique.join(',');
 };
 
 export const readLifecycleState = (
@@ -16,18 +36,54 @@ export const readLifecycleState = (
   version: git.getLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.version),
   hooks: git.getLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.hooks),
   installedAt: git.getLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.installedAt),
+  openSpecManagedArtifacts: git.getLocalConfig(
+    repoRoot,
+    PUMUKI_CONFIG_KEYS.openSpecManagedArtifacts
+  ),
 });
 
 export const writeLifecycleState = (params: {
   git: ILifecycleGitService;
   repoRoot: string;
   version: string;
+  openSpecManagedArtifacts?: ReadonlyArray<string>;
 }): void => {
   const { git, repoRoot, version } = params;
   git.setLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.installed, 'true');
   git.setLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.version, version);
   git.setLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.hooks, PUMUKI_MANAGED_HOOKS.join(','));
   git.setLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.installedAt, new Date().toISOString());
+  if (params.openSpecManagedArtifacts) {
+    const serialized = serializeManagedArtifacts(params.openSpecManagedArtifacts);
+    if (serialized) {
+      git.setLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.openSpecManagedArtifacts, serialized);
+    } else {
+      git.unsetLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.openSpecManagedArtifacts);
+    }
+  }
+};
+
+export const readOpenSpecManagedArtifacts = (
+  git: ILifecycleGitService,
+  repoRoot: string
+): ReadonlyArray<string> =>
+  parseManagedArtifacts(git.getLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.openSpecManagedArtifacts));
+
+export const writeOpenSpecManagedArtifacts = (params: {
+  git: ILifecycleGitService;
+  repoRoot: string;
+  artifacts: ReadonlyArray<string>;
+}): void => {
+  const serialized = serializeManagedArtifacts(params.artifacts);
+  if (serialized) {
+    params.git.setLocalConfig(
+      params.repoRoot,
+      PUMUKI_CONFIG_KEYS.openSpecManagedArtifacts,
+      serialized
+    );
+    return;
+  }
+  params.git.unsetLocalConfig(params.repoRoot, PUMUKI_CONFIG_KEYS.openSpecManagedArtifacts);
 };
 
 export const clearLifecycleState = (
@@ -38,4 +94,5 @@ export const clearLifecycleState = (
   git.unsetLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.version);
   git.unsetLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.hooks);
   git.unsetLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.installedAt);
+  git.unsetLocalConfig(repoRoot, PUMUKI_CONFIG_KEYS.openSpecManagedArtifacts);
 };