vibe-commander 0.2.1 → 0.2.3

package/AGENTS.md

@@ -10,6 +10,8 @@ vc init                          # Initialize project (create config)
 vc init --from-existing          # Auto-detect from existing files
 vc init --force                  # Overwrite existing config
 vc set-unit <unitId>             # Set current working unit
+vc set-unit --next               # Auto-select next ready unit from backlog
+vc set-unit --next --dry-run     # Preview auto-selected unit without modifying files
 vc set-unit <unitId> --dry-run   # Preview without modifying files
 vc update-commit [sha|N]         # Update commit SHA (no arg=HEAD, number=recent N)
 vc list-units [--phase Mvp]      # List incomplete units
@@ -43,6 +45,21 @@ vc set-unit U-013[Mvp] --json
 vc update-commit --json
 ```
 
+## Quick Set Workflow (--next)
+
+```bash
+# 1. Preview which unit will be auto-selected (no file changes)
+vc set-unit --next --dry-run --json
+
+# 2. Apply: auto-select next ready unit and configure command file
+vc set-unit --next --json
+
+# 3. Update commit SHA after making changes
+vc update-commit --json
+```
+
+`--next` selects the first ready unit from the backlog (roadmap order). It is mutually exclusive with `<unitId>`. Pipe mode: `echo '{"next":true}' | vc set-unit --stdin --json`
+
 ## Config File
 
 - Location: `vibe-commander.config.json` in project root

package/dist/adapters/cli/commands/context-resolver.js

@@ -13,6 +13,7 @@ import { ok, fail } from '../../../types/index.js';
 import { loadConfig } from '../../../config/loader.js';
 import { resolveUnitType, locatePlan } from '../../../config/resolver.js';
 import { parseUnitPlan } from '../../../core/parsers/plan-parser.js';
+import { extractTitleFromContent } from '../../../core/parsers/title-extractor.js';
 import { resolveDepDocs } from '../../../core/resolvers/dep-doc-resolver.js';
 import { resolveActualDocs, collectGitCommits, buildSpecialRequests } from './io-helpers.js';
 /**
@@ -68,6 +69,8 @@ export function resolveCommandContext(unitId, projectRoot, requestKeys) {
         }
         // 6b. Git 커밋 수집 (Adapter I/O)
         depCommits = collectGitCommits(depIds, config.commitSearch, projectRoot);
+        // 6c. description이 빈 의존 유닛에 대해 의존 계획서 H1 title Fallback
+        enrichEmptyDescriptions(meta.depends, config, projectRoot);
     }
     // 7. 특별 요청사항 조합
     const srResult = buildSpecialRequests(config, unitTypeConfig.key, requestKeys);
@@ -90,4 +93,31 @@ export function resolveCommandContext(unitId, projectRoot, requestKeys) {
         warnings,
     });
 }
+// ── description Fallback 헬퍼 ──
+/**
+ * description이 빈 의존 유닛에 대해 의존 계획서 파일의 H1 title로 보강한다
+ *
+ * Graceful Degradation: 파일 미존재, 읽기 실패, title 추출 실패 시 빈 상태 유지.
+ * 기존에 description이 채워져 있으면 절대 덮어쓰지 않는다.
+ */
+function enrichEmptyDescriptions(depends, config, projectRoot) {
+    for (const dep of depends) {
+        if (dep.description !== '')
+            continue;
+        const planResult = locatePlan(dep.unitId, config);
+        if (!planResult.success)
+            continue;
+        const depPlanPath = join(projectRoot, planResult.data);
+        try {
+            const content = readFileSync(depPlanPath, 'utf-8');
+            const titleOnly = extractTitleFromContent(content);
+            if (titleOnly) {
+                dep.description = titleOnly;
+            }
+        }
+        catch {
+            // Graceful Degradation: 파일 미존재 시 빈 description 유지
+        }
+    }
+}
 //# sourceMappingURL=context-resolver.js.map

package/dist/adapters/cli/commands/list-units.d.ts

@@ -27,9 +27,8 @@ export interface ListUnitsResult {
  * 2. 로드맵 경로 확인 — null이면 에러 반환
  * 3. 로드맵 파일 읽기 (Adapter I/O)
  * 4. 백로그 파싱 (parseBacklog)
- * 5. completed 제외, phase 필터링
- * 6. 상태별 분류 (inProgress/ready/blocked)
- * 7. 결과 반환
+ * 5. 백로그 분류 및 필터링 (classifyBacklog)
+ * 6. 결과 반환
  *
  * @param args - 파싱된 CLI 인자 (command === 'list-units' 보장)
  * @param projectRoot - 프로젝트 루트 절대 경로

package/dist/adapters/cli/commands/list-units.js

@@ -14,6 +14,7 @@ import { join } from 'node:path';
 import { ok, fail } from '../../../types/index.js';
 import { loadConfig } from '../../../config/loader.js';
 import { parseBacklog } from '../../../core/parsers/backlog-parser.js';
+import { classifyBacklog } from '../../../core/resolvers/backlog-resolver.js';
 /**
  * list-units 커맨드를 실행한다
  *
@@ -22,9 +23,8 @@ import { parseBacklog } from '../../../core/parsers/backlog-parser.js';
  * 2. 로드맵 경로 확인 — null이면 에러 반환
  * 3. 로드맵 파일 읽기 (Adapter I/O)
  * 4. 백로그 파싱 (parseBacklog)
- * 5. completed 제외, phase 필터링
- * 6. 상태별 분류 (inProgress/ready/blocked)
- * 7. 결과 반환
+ * 5. 백로그 분류 및 필터링 (classifyBacklog)
+ * 6. 결과 반환
  *
  * @param args - 파싱된 CLI 인자 (command === 'list-units' 보장)
  * @param projectRoot - 프로젝트 루트 절대 경로
@@ -57,36 +57,10 @@ export function handleListUnits(args, projectRoot) {
     const parseResult = parseBacklog(roadmapContent, config.backlogParsing);
     if (!parseResult.success)
         return parseResult;
-    // 5. 활성 항목만 필터 (completed 제외)
-    let entries = parseResult.data.filter((e) => e.status !== 'completed');
-    // 6. phase 필터링 (대소문자 무시)
-    if (phase) {
-        const normalizedPhase = phase.toLowerCase();
-        entries = entries.filter((e) => {
-            const entryPhase = extractPhase(e.unitId);
-            return entryPhase !== null && entryPhase.toLowerCase() === normalizedPhase;
-        });
-    }
-    // 7. 상태별 분류
-    const inProgress = entries.filter((e) => e.status === 'inProgress');
-    const ready = entries.filter((e) => e.status === 'ready');
-    const blocked = entries.filter((e) => e.status === 'blocked');
-    return ok({
-        total: entries.length,
-        inProgress,
-        ready,
-        blocked,
-        ...(phase !== undefined && { phase }),
-    });
-}
-/**
- * 유닛 ID에서 phase 태그를 추출한다
- *
- * "U-016[Mvp]" → "Mvp"
- * "CP-MVP-03" → null
- */
-function extractPhase(unitId) {
-    const match = unitId.match(/\[([^\]]+)\]$/);
-    return match?.[1] ?? null;
+    // 5. 백로그 분류 및 필터링 (Core 순수 함수)
+    const classificationResult = classifyBacklog(parseResult.data, { phase });
+    if (!classificationResult.success)
+        return classificationResult;
+    return ok(classificationResult.data);
 }
 //# sourceMappingURL=list-units.js.map

package/dist/adapters/cli/commands/set-unit.d.ts

@@ -27,6 +27,11 @@ export interface SetUnitResult {
     warnings: string[];
     dryRun?: boolean;
     preview?: string;
+    autoSelected?: boolean;
+    selectedFrom?: {
+        ready: number;
+        total: number;
+    };
 }
 /**
  * set-unit 커맨드를 실행한다

package/dist/adapters/cli/commands/set-unit.js

@@ -10,11 +10,18 @@
  *
  * @module
  */
-import { writeFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { ok, fail } from '../../../types/index.js';
 import { validateUnitId } from '../../../core/validators/input-validator.js';
+import { parseBacklog } from '../../../core/parsers/backlog-parser.js';
+import { classifyBacklog } from '../../../core/resolvers/backlog-resolver.js';
 import { renderSection } from '../../../core/renderers/section-renderer.js';
 import { updateSection } from '../../../core/renderers/section-updater.js';
+import { findMarkerRange } from '../../../core/renderers/marker-utils.js';
+import { extractSubsectionContent } from '../../../core/parsers/subsection-extractor.js';
+import { normalizeLineEndings } from '../../../core/parsers/md-utils.js';
+import { loadConfig } from '../../../config/loader.js';
 import { resolveCommandContext } from './context-resolver.js';
 import { readCommandsFile, enrichWithSuggestions } from './io-helpers.js';
 import { writeActiveUnitType } from './state-helpers.js';
@@ -37,9 +44,21 @@ export async function handleSetUnit(args, projectRoot) {
     if (args.command !== 'set-unit') {
         return fail('INTERNAL_ERROR', 'handleSetUnit에 잘못된 커맨드가 전달되었습니다');
     }
-    const { unitId, noPrompt, dryRun } = args;
+    const { noPrompt, dryRun, next } = args;
+    let unitId = args.unitId;
     const requestKeys = 'requestKeys' in args ? args.requestKeys : [];
-    // 0. 입력 안전성 검증 (제어 문자, 경로 순회, URL 인코딩 등)
+    let autoSelected = false;
+    let selectedFrom;
+    // 0-a. --next: 백로그에서 ready 유닛 자동 선택
+    if (next) {
+        const pickResult = pickNextUnit(projectRoot);
+        if (!pickResult.success)
+            return pickResult;
+        unitId = pickResult.data.unitId;
+        autoSelected = true;
+        selectedFrom = { ready: pickResult.data.readyCount, total: pickResult.data.totalCount };
+    }
+    // 0-b. 입력 안전성 검증 (제어 문자, 경로 순회, URL 인코딩 등)
     const safetyCheck = validateUnitId(unitId);
     if (!safetyCheck.valid) {
         return fail('INVALID_INPUT', safetyCheck.error ?? '입력 검증 실패');
@@ -57,12 +76,25 @@ export async function handleSetUnit(args, projectRoot) {
         pairingAnswers = await promptAllQuestions(context.pairingQuestions);
         context.pairingAnswers = pairingAnswers;
     }
-    // 3. 섹션 렌더링 (Core 순수 함수)
-    const sectionBody = renderSection(context, unitTypeConfig);
-    // 4. 커맨드 파일 업데이트 (Adapter I/O) — dry-run 시 건너뜀
+    // 3. 커맨드 파일 읽기 (보존 추출 + 업데이트에 재사용)
+    const cmdFile = readCommandsFile(config, projectRoot);
+    // 4. 기존 특별 요청사항 추출 (보존 로직)
+    const specialRequestsHeading = config.commandSections.specialRequestsHeading;
+    let preservedSpecialRequests;
+    if (cmdFile.success) {
+        const extracted = extractExistingSpecialRequests(cmdFile.data.content, unitTypeConfig.commandSection, specialRequestsHeading, config.commandSections.useMarkers ? unitTypeConfig.key : undefined, config.commandSections.separator);
+        if (extracted) {
+            preservedSpecialRequests = extracted;
+        }
+    }
+    // 5. 섹션 렌더링 (Core 순수 함수)
+    const sectionBody = renderSection(context, unitTypeConfig, undefined, {
+        preservedSpecialRequests,
+        specialRequestsHeading,
+    });
+    // 6. 커맨드 파일 업데이트 (Adapter I/O) — dry-run 시 건너뜀
     let commandsUpdated = false;
     if (!dryRun) {
-        const cmdFile = readCommandsFile(config, projectRoot);
         if (cmdFile.success) {
             const useMarkers = config.commandSections.useMarkers;
             const markerOptions = useMarkers ? { sectionKey: unitTypeConfig.key } : undefined;
@@ -84,7 +116,7 @@ export async function handleSetUnit(args, projectRoot) {
         else {
             warnings.push(`커맨드 파일을 읽을 수 없습니다: ${config.paths.commands}`);
         }
-        // 5. 활성 유닛 타입 상태 기록 (update-commit 자동 감지용)
+        // 7. 활성 유닛 타입 상태 기록 (update-commit 자동 감지용)
         writeActiveUnitType(projectRoot, unitTypeKey);
     }
     // 6. 결과 반환
@@ -101,6 +133,107 @@ export async function handleSetUnit(args, projectRoot) {
         commandsUpdated,
         warnings,
         ...(dryRun && { dryRun: true, preview: sectionBody }),
+        ...(autoSelected && { autoSelected, selectedFrom }),
+    });
+}
+/**
+ * 백로그에서 첫 번째 ready 유닛을 선택한다
+ *
+ * loadConfig → 로드맵 확인 → parseBacklog → ready 필터 → 첫 번째 반환
+ */
+function pickNextUnit(projectRoot) {
+    const configResult = loadConfig(projectRoot);
+    if (!configResult.success)
+        return configResult;
+    const config = configResult.data;
+    if (!config.paths.roadmap) {
+        return fail('ROADMAP_NOT_CONFIGURED', '--next 옵션을 사용하려면 로드맵 파일이 설정되어야 합니다', 'vibe-commander.config.json의 paths.roadmap을 설정하거나, vc set-unit <unitId>로 직접 지정하세요');
+    }
+    const roadmapAbsPath = join(projectRoot, config.paths.roadmap);
+    let roadmapContent;
+    try {
+        roadmapContent = readFileSync(roadmapAbsPath, 'utf-8');
+    }
+    catch {
+        return fail('ROADMAP_NOT_FOUND', `로드맵 파일을 찾을 수 없습니다: ${config.paths.roadmap}`, `절대 경로: ${roadmapAbsPath}`);
+    }
+    const parseResult = parseBacklog(roadmapContent, config.backlogParsing);
+    if (!parseResult.success)
+        return parseResult;
+    // 백로그 분류 (Core 순수 함수)
+    const classificationResult = classifyBacklog(parseResult.data);
+    if (!classificationResult.success)
+        return classificationResult;
+    const { ready, inProgress, blocked, total } = classificationResult.data;
+    if (ready.length === 0) {
+        return fail('NO_READY_UNITS', '착수 가능한(ready) 유닛이 없습니다', `현재 상태: 진행중 ${String(inProgress.length)}개, 블록됨 ${String(blocked.length)}개. vc list-units로 확인하세요`);
+    }
+    const first = ready[0];
+    if (!first) {
+        return fail('NO_READY_UNITS', '착수 가능한(ready) 유닛이 없습니다');
+    }
+    return ok({
+        unitId: first.unitId,
+        readyCount: ready.length,
+        totalCount: total,
     });
 }
+// ── 특별 요청사항 보존 헬퍼 ──
+/**
+ * 커맨드 파일에서 대상 섹션 내 기존 특별 요청사항 콘텐츠를 추출한다
+ *
+ * Fallback 체인:
+ * 1. 마커 기반: findMarkerRange로 섹션 범위 확보 → 내부에서 서브섹션 추출
+ * 2. 헤더 기반: commandSection 헤더로 섹션 범위 확보 → 내부에서 서브섹션 추출
+ * 3. 둘 다 실패: null 반환 (기존 동작 Fallback)
+ *
+ * 추출된 콘텐츠에서 trailing separator는 제거하여 이중 separator를 방지한다.
+ */
+function extractExistingSpecialRequests(fileContent, sectionHeader, specialRequestsHeading, sectionKey, separator) {
+    const lines = normalizeLineEndings(fileContent).split('\n');
+    let raw = null;
+    // 1. 마커 기반 범위 탐색
+    if (sectionKey) {
+        const range = findMarkerRange(lines, sectionKey);
+        if (range) {
+            const sectionContent = lines.slice(range.start + 1, range.end).join('\n');
+            raw = extractSubsectionContent(sectionContent, specialRequestsHeading);
+        }
+    }
+    // 2. 헤더 기반 Fallback
+    if (raw === null) {
+        const needle = sectionHeader.trim();
+        const headerIdx = lines.findIndex((l) => l.trim() === needle);
+        if (headerIdx === -1)
+            return null;
+        const hashMatch = needle.match(/^(#+)/);
+        const level = hashMatch?.[1] ? hashMatch[1].length : 1;
+        let endIdx = lines.length;
+        for (let i = headerIdx + 1; i < lines.length; i++) {
+            const line = (lines[i] ?? '').trim();
+            const lineMatch = line.match(/^(#+)\s/);
+            if (lineMatch?.[1] && lineMatch[1].length <= level) {
+                endIdx = i;
+                break;
+            }
+        }
+        const sectionContent = lines.slice(headerIdx, endIdx).join('\n');
+        raw = extractSubsectionContent(sectionContent, specialRequestsHeading);
+    }
+    if (!raw)
+        return null;
+    // trailing separator 제거 (updateSection이 별도 삽입하므로 이중 방지)
+    if (separator) {
+        const resultLines = raw.split('\n');
+        const sep = separator.trim();
+        while (resultLines.length > 0 && (resultLines[resultLines.length - 1] ?? '').trim() === sep) {
+            resultLines.pop();
+        }
+        while (resultLines.length > 0 && (resultLines[resultLines.length - 1] ?? '').trim() === '') {
+            resultLines.pop();
+        }
+        return resultLines.length > 0 ? resultLines.join('\n') : null;
+    }
+    return raw;
+}
 //# sourceMappingURL=set-unit.js.map

package/dist/adapters/cli/formatters-unit.js

@@ -19,9 +19,13 @@ export function formatSetUnit(result, json) {
     const data = result.data;
     if (!isSetUnitResult(data))
         return;
+    const autoData = data;
     console.log(`
 ${GREEN}✅ 작업 유닛 설정 완료: ${data.unitId}${RESET}
 `);
+    if (autoData.autoSelected && autoData.selectedFrom) {
+        console.log(`${CYAN}🎯 자동 선택됨${RESET} ${DIM}(ready ${String(autoData.selectedFrom.ready)}개 중 첫 번째)${RESET}`);
+    }
     console.log(`${BOLD}📝 제목${RESET}: ${data.title}`);
     console.log(`${BOLD}📂 유형${RESET}: ${data.unitType}`);
     console.log(`${BOLD}📄 계획서${RESET}: ${data.planPath}`);

package/dist/adapters/cli/output.js

@@ -100,6 +100,7 @@ ${YELLOW}글로벌 옵션:${RESET}
   ${CYAN}--stdin${RESET}                        stdin에서 JSON 입력 읽기
 
 ${YELLOW}set-unit 옵션:${RESET}
+  ${CYAN}--next${RESET}                            백로그에서 ready 유닛을 자동 선택
   ${CYAN}--request${RESET} <key1,key2>             커스텀 특별 요청사항 키 선택 (콤마 구분)
   ${CYAN}--no-prompt${RESET}                       페어링 질문 인터랙티브 프롬프트 비활성화
   ${CYAN}--dry-run${RESET}                         커맨드 파일 수정 없이 미리보기만 출력
@@ -126,6 +127,8 @@ ${YELLOW}예시:${RESET}
   ${DIM}$ vc init${RESET}
   ${DIM}$ vc init --from-existing${RESET}              ${DIM}# 기존 파일 스캔으로 자동 설정${RESET}
   ${DIM}$ vc set-unit U-013[Mvp]${RESET}
+  ${DIM}$ vc set-unit --next${RESET}                          ${DIM}# 다음 ready 유닛 자동 선택${RESET}
+  ${DIM}$ vc set-unit --next --dry-run${RESET}                ${DIM}# 자동 선택 미리보기만${RESET}
   ${DIM}$ vc set-unit U-013[Mvp] --dry-run${RESET}            ${DIM}# 커맨드 파일 미수정, 미리보기만${RESET}
   ${DIM}$ vc set-unit U-013[Mvp] --dry-run --json${RESET}     ${DIM}# 미리보기를 JSON으로 출력${RESET}
   ${DIM}$ vc set-unit U-013[Mvp] --request mcp-nanobanana,mcp-codrag${RESET}

package/dist/adapters/cli/router.d.ts

@@ -12,6 +12,7 @@ import type { ToolResult } from '../../types/index.js';
 export interface SetUnitArgs {
     command: 'set-unit';
     unitId: string;
+    next: boolean;
     requestKeys: string[];
     noPrompt: boolean;
     dryRun: boolean;

package/dist/adapters/cli/router.js

@@ -68,12 +68,16 @@ export function parseArgs(argv) {
 /**
  * set-unit 서브커맨드의 인자를 파싱한다
  *
- * 필수: <unitId> — 위치 인자 (첫 번째 non-flag 인자)
+ * 필수: <unitId> 또는 --next (상호 배타)
  */
 function parseSetUnit(args, json) {
+    const next = hasFlag(args, '--next');
     const unitId = getPositionalArg(args);
-    if (!unitId) {
-        return fail('MISSING_ARGUMENT', "'set-unit' 명령어에 <unitId> 인자가 필요합니다", '사용법: vc set-unit <unitId> [--request key1,key2] [--no-prompt]');
+    if (next && unitId) {
+        return fail('CONFLICTING_OPTIONS', '--next와 <unitId>는 동시에 사용할 수 없습니다', '사용법: vc set-unit --next 또는 vc set-unit <unitId>');
+    }
+    if (!next && !unitId) {
+        return fail('MISSING_ARGUMENT', "'set-unit' 명령어에 <unitId> 인자 또는 --next 옵션이 필요합니다", '사용법: vc set-unit <unitId> 또는 vc set-unit --next');
     }
     const requestRaw = getOptionValue(args, '--request');
     const requestKeys = requestRaw
@@ -86,7 +90,7 @@ function parseSetUnit(args, json) {
     const dryRun = hasFlag(args, '--dry-run');
     return {
         success: true,
-        data: { command: 'set-unit', unitId, requestKeys, noPrompt, dryRun, json },
+        data: { command: 'set-unit', unitId: unitId ?? '', next, requestKeys, noPrompt, dryRun, json },
     };
 }
 /**

package/dist/adapters/cli/stdin-parser.js

@@ -21,15 +21,27 @@ import { ok, fail } from '../../types/index.js';
 export function parseStdinArgs(subcommand, data, json, rawArgs) {
     switch (subcommand) {
         case 'set-unit': {
+            const next = data.next === true;
             const unitId = typeof data.unitId === 'string' ? data.unitId : undefined;
-            if (!unitId) {
-                return fail('STDIN_MISSING_FIELD', 'stdin JSON에 "unitId" (string) 필드가 필요합니다', '예시: {"unitId": "U-001[Mvp]"}');
+            if (next && unitId) {
+                return fail('CONFLICTING_OPTIONS', '"next"와 "unitId"는 동시에 사용할 수 없습니다', '예시: {"next": true} 또는 {"unitId": "U-001[Mvp]"}');
+            }
+            if (!next && !unitId) {
+                return fail('STDIN_MISSING_FIELD', 'stdin JSON에 "unitId" (string) 또는 "next": true 필드가 필요합니다', '예시: {"unitId": "U-001[Mvp]"} 또는 {"next": true}');
             }
             const requestKeys = Array.isArray(data.requestKeys)
                 ? data.requestKeys.filter((k) => typeof k === 'string')
                 : [];
             const dryRun = rawArgs?.includes('--dry-run') ?? false;
-            return ok({ command: 'set-unit', unitId, requestKeys, noPrompt: true, dryRun, json });
+            return ok({
+                command: 'set-unit',
+                unitId: unitId ?? '',
+                next,
+                requestKeys,
+                noPrompt: true,
+                dryRun,
+                json,
+            });
         }
         case 'update-commit': {
             const modeValue = typeof data.mode === 'string' ? data.mode : undefined;

package/dist/config/schema.d.ts

@@ -93,6 +93,7 @@ export declare const commandSectionsSchema: z.ZodObject<{
     preserveOtherSections: z.ZodDefault<z.ZodBoolean>;
     commitFieldName: z.ZodDefault<z.ZodString>;
     useMarkers: z.ZodDefault<z.ZodBoolean>;
+    specialRequestsHeading: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>;
 /** 기본 문서 탐색 설정 */
 export declare const DEFAULT_DOC_DISCOVERY: {
@@ -173,6 +174,7 @@ export declare const projectConfigSchema: z.ZodObject<{
         preserveOtherSections: z.ZodDefault<z.ZodBoolean>;
         commitFieldName: z.ZodDefault<z.ZodString>;
         useMarkers: z.ZodDefault<z.ZodBoolean>;
+        specialRequestsHeading: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
     defaultSpecialRequests: z.ZodDefault<z.ZodArray<z.ZodString>>;
     specialRequestsByType: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;

package/dist/config/schema.js

@@ -227,6 +227,11 @@ export const commandSectionsSchema = z.object({
         .boolean()
         .default(false)
         .describe('Use HTML comment markers (<!-- vc:begin/end -->) for safer section boundary detection'),
+    /** 특별 요청사항 섹션 헤딩 (기본: "### 특별 요청사항") */
+    specialRequestsHeading: z
+        .string()
+        .default('### 특별 요청사항')
+        .describe('Sub-heading for special requests in the command file'),
 });
 // ── 최상위 설정 ──
 /** 기본 문서 탐색 설정 */

package/dist/core/parsers/dep-line-parser.js

@@ -115,7 +115,7 @@ function extractDepFromLine(line, idPattern) {
     }
     if (candidates.length === 0)
         return null;
-    // idPattern으로 필터링
+    // idPattern으로 필터링: 볼드 헤더(`**헤더**: [ID](url)`)에서 비유닛 볼드를 건너뜀
     const idRegex = idPattern ? safeRegex(idPattern) : null;
     const validCandidate = idRegex ? candidates.find((c) => idRegex.test(c.id)) : candidates[0];
     if (!validCandidate)
@@ -150,8 +150,12 @@ function extractDescription(content, unitId, source) {
     const afterMatch = content.match(afterPattern);
     if (!afterMatch?.[1])
         return '';
-    // 구분자 제거: 시작 부분의 :, —, -, | 등
-    return afterMatch[1].replace(/^[:\-—|]+\s*/, '').trim();
+    let rest = afterMatch[1].trim();
+    // 구분자 제거: 시작 부분의 :, — (공백 유연) 또는 — , - (공백 필수)
+    // : -10% 같은 경우 :만 제거하고 -10%는 보존하기 위해 순차적으로 처리
+    rest = rest.replace(/^[:—]\s*/, '');
+    rest = rest.replace(/^[—-]\s+/, '');
+    return rest.trim();
 }
 /**
  * 하위 항목에서 artifact 텍스트를 추출한다

package/dist/core/parsers/dependency-extractor.js

@@ -16,7 +16,7 @@
  */
 import { ok } from '../../types/index.js';
 import { parseMetadataTable } from './metadata-parser.js';
-import { FRONTMATTER_RE, findSectionLines, deduplicateBy, normalizeLineEndings, isNoneDependency, } from './md-utils.js';
+import { FRONTMATTER_RE, findSectionLines, deduplicateBy, normalizeLineEndings, isNoneDependency, escapeRegex, } from './md-utils.js';
 import { parseDependencyLines } from './dep-line-parser.js';
 /**
  * 계획서에서 의존 유닛 정보를 추출한다
@@ -79,10 +79,7 @@ export function extractDependenciesWithNotes(content, config, idPattern) {
     }
     // 2. Fallback: 메타데이터 테이블 (설정 소스가 metadata-table이면 이미 시도했으므로 건너뜀)
     if (config.dependsSource !== 'metadata-table') {
-        const fromTableResult = parseMetadataTable(normalized, config.metadataTable);
-        const fromTable = fromTableResult.success
-            ? fromTableResult.data.depends.map((unitId) => ({ unitId, description: '' }))
-            : [];
+        const fromTable = extractFromMetadataTable(normalized, config.metadataTable);
         if (fromTable.length > 0) {
             return ok({
                 deps: deduplicateBy(fromTable, (d) => d.unitId),
@@ -161,33 +158,102 @@ function extractFromFrontmatter(content) {
     }
     return [];
 }
-/** 메타데이터 테이블에서 의존성을 추출한다 */
+/**
+ * 메타데이터 테이블에서 의존성을 추출한다
+ *
+ * raw 값에 구분자(`—`, `:`, `-`)로 설명이 포함된 경우:
+ * `| 의존성 | U-101 — Token 발급 |` → `{ unitId: "U-101", description: "Token 발급" }`
+ *
+ * parseMetadataTable은 콤마 분리 후 전체 토큰을 unitId로 반환하므로,
+ * 여기서 unitId와 description을 분리한다.
+ */
 function extractFromMetadataTable(content, tableConfig) {
     const tableResult = parseMetadataTable(content, tableConfig);
     if (!tableResult.success)
         return [];
-    return tableResult.data.depends.map((unitId) => ({
-        unitId,
-        description: '',
-    }));
+    return tableResult.data.depends.map((rawToken) => splitUnitIdAndDescription(rawToken));
+}
+/**
+ * 구분자 패턴:
+ * 1. 콜론(:) 또는 em dash(—)는 공백 유연하게 허용
+ * 2. 하이픈(-)은 유닛 ID와 혼동될 수 있으므로 반드시 앞뒤 공백 필요
+ */
+const DESC_SEPARATOR_RE = /^(?:(.+?)\s*([—:])\s*(.+)|(.+?)\s+-\s+(.+))$/;
+/**
+ * `U-101 — Token 발급` 같은 토큰에서 unitId와 description을 분리한다
+ *
+ * 구분자가 없으면 전체가 unitId, description은 빈 문자열.
+ */
+function splitUnitIdAndDescription(rawToken) {
+    const match = rawToken.match(DESC_SEPARATOR_RE);
+    if (match) {
+        // 1번 그룹(ID), 3번 그룹(Desc) 또는 4번 그룹(ID), 5번 그룹(Desc)
+        const unitId = (match[1] || match[4] || '').trim();
+        const description = (match[3] || match[5] || '').trim();
+        if (unitId && description) {
+            return { unitId, description };
+        }
+    }
+    return { unitId: rawToken, description: '' };
 }
-/** 본문 전체에서 ID 패턴으로 의존성을 스캔한다 (Fallback 최후 수단) */
+/**
+ * 본문 전체에서 ID 패턴으로 의존성을 스캔한다 (Fallback 최후 수단)
+ *
+ * ID가 발견된 줄에서 구분자(`—`, `:`, `-`) 이후 텍스트를 description으로 추출 시도.
+ * 같은 줄에 설명이 없으면 다음 줄이 하위 항목인지 확인하여 추출.
+ */
 function extractFromBodyScan(content, idPattern) {
     try {
         const regex = new RegExp(idPattern, 'g');
         const matches = content.match(regex);
         if (!matches)
             return [];
-        // 중복 제거
         const unique = [...new Set(matches)];
+        const lines = content.split('\n');
         return unique.map((unitId) => ({
             unitId,
-            description: '',
+            description: extractDescriptionFromLines(lines, unitId),
         }));
     }
     catch {
-        // 잘못된 정규식 — 빈 배열 반환 (Graceful Degradation)
         return [];
     }
 }
+/**
+ * 본문 라인에서 unitId가 포함된 첫 번째 줄에서 description을 추출한다
+ *
+ * `**U-002**: 공유 타입`, `[U-002](url) — 설명`, `U-002의 ...` 패턴에서
+ * 구분자 이후 텍스트를 description으로 반환.
+ * 같은 줄에 설명이 없으면 다음 줄의 텍스트를 확인.
+ */
+function extractDescriptionFromLines(lines, unitId) {
+    const escapedId = escapeRegex(unitId);
+    const linePattern = new RegExp(escapedId);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (!linePattern.test(line))
+            continue;
+        // 1. 같은 줄에서 추출 시도
+        // 링크 형식: [ID](url) 뒤의 텍스트
+        const linkDesc = new RegExp(`\\[${escapedId}\\]\\([^)]*\\)\\s*[—:\\-]\\s*(.+)`);
+        const linkMatch = line.match(linkDesc);
+        if (linkMatch?.[1])
+            return linkMatch[1].trim();
+        // 볼드 형식: **ID** 뒤의 텍스트
+        const boldDesc = new RegExp(`\\*\\*${escapedId}\\*\\*\\s*[—:\\-]\\s*(.+)`);
+        const boldMatch = line.match(boldDesc);
+        if (boldMatch?.[1])
+            return boldMatch[1].trim();
+        // 2. 같은 줄에 구분자 설명이 없으면 다음 줄 확인
+        if (i + 1 < lines.length) {
+            const nextLine = (lines[i + 1] ?? '').trim();
+            // 다음 줄이 비어있지 않고, 다른 리스트 항목이나 헤더가 아니면 설명으로 간주
+            if (nextLine !== '' && !/^[-*#]/.test(nextLine)) {
+                return nextLine;
+            }
+        }
+        break;
+    }
+    return '';
+}
 //# sourceMappingURL=dependency-extractor.js.map

package/dist/core/parsers/index.d.ts

@@ -9,7 +9,8 @@
 export { parseUnitPlan } from './plan-parser.js';
 export type { ParseUnitPlanResult } from './plan-parser.js';
 export { parseBacklog } from './backlog-parser.js';
-export { extractTitle } from './title-extractor.js';
+export { extractSubsectionContent } from './subsection-extractor.js';
+export { extractTitle, extractTitleFromContent } from './title-extractor.js';
 export { parseMetadataTable } from './metadata-parser.js';
 export type { MetadataTableResult } from './metadata-parser.js';
 export { extractDependencies, extractDependenciesWithNotes } from './dependency-extractor.js';

package/dist/core/parsers/index.js

@@ -10,8 +10,10 @@
 export { parseUnitPlan } from './plan-parser.js';
 // 백로그 파서
 export { parseBacklog } from './backlog-parser.js';
+// 서브섹션 추출기
+export { extractSubsectionContent } from './subsection-extractor.js';
 // 개별 추출기 (필요 시 단독 사용)
-export { extractTitle } from './title-extractor.js';
+export { extractTitle, extractTitleFromContent } from './title-extractor.js';
 export { parseMetadataTable } from './metadata-parser.js';
 export { extractDependencies, extractDependenciesWithNotes } from './dependency-extractor.js';
 export { extractPairingQuestions } from './pairing-question-extractor.js';

package/dist/core/parsers/plan-parser-helpers.js

@@ -61,6 +61,11 @@ export function extractPhase(content, config) {
 export function extractDependsWithWarning(content, config, idPattern, warnings) {
     const result = extractDependenciesWithNotes(content, config, idPattern);
     if (result.success) {
+        // description이 빈 항목이 있으면 보강 힌트 추가
+        const emptyDescCount = result.data.deps.filter((d) => d.description === '').length;
+        if (emptyDescCount > 0) {
+            warnings.push(`일부 의존 유닛의 설명이 비어 있습니다 (${String(emptyDescCount)}개). 의존 계획서 파일의 제목에서 설명을 추출합니다.`);
+        }
         return { depends: result.data.deps, contextNotes: result.data.contextNotes };
     }
     // 의존성 추출 실패 — 빈 결과 + 경고

package/dist/core/parsers/subsection-extractor.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 서브섹션 추출기 — Layer 1 순수 함수
+ *
+ * 섹션 본문에서 특정 `###` 서브섹션 콘텐츠를 추출한다.
+ * `renderSection`의 보존 로직에서 기존 특별 요청사항을 추출하는 데 사용.
+ *
+ * @module
+ */
+/**
+ * 콘텐츠에서 지정된 서브헤딩의 콘텐츠를 추출한다
+ *
+ * 서브헤딩 라인 자체도 결과에 포함된다.
+ * 다음 동급 이상(### 이하 레벨) 헤딩 또는 콘텐츠 끝까지 추출한다.
+ *
+ * @param content - 검색 대상 콘텐츠
+ * @param subHeading - 찾을 서브헤딩 텍스트 (예: "### 특별 요청사항")
+ * @returns 서브헤딩 포함 콘텐츠 또는 null (미발견/빈 콘텐츠)
+ */
+export declare function extractSubsectionContent(content: string, subHeading: string): string | null;
+//# sourceMappingURL=subsection-extractor.d.ts.map

package/dist/core/parsers/subsection-extractor.js

@@ -0,0 +1,56 @@
+/**
+ * 서브섹션 추출기 — Layer 1 순수 함수
+ *
+ * 섹션 본문에서 특정 `###` 서브섹션 콘텐츠를 추출한다.
+ * `renderSection`의 보존 로직에서 기존 특별 요청사항을 추출하는 데 사용.
+ *
+ * @module
+ */
+import { normalizeLineEndings } from './md-utils.js';
+/**
+ * 콘텐츠에서 지정된 서브헤딩의 콘텐츠를 추출한다
+ *
+ * 서브헤딩 라인 자체도 결과에 포함된다.
+ * 다음 동급 이상(### 이하 레벨) 헤딩 또는 콘텐츠 끝까지 추출한다.
+ *
+ * @param content - 검색 대상 콘텐츠
+ * @param subHeading - 찾을 서브헤딩 텍스트 (예: "### 특별 요청사항")
+ * @returns 서브헤딩 포함 콘텐츠 또는 null (미발견/빈 콘텐츠)
+ */
+export function extractSubsectionContent(content, subHeading) {
+    if (!content.trim() || !subHeading.trim())
+        return null;
+    const normalized = normalizeLineEndings(content);
+    const lines = normalized.split('\n');
+    const needle = subHeading.trim();
+    const hashMatch = needle.match(/^(#+)\s/);
+    if (!hashMatch?.[1])
+        return null;
+    const level = hashMatch[1].length;
+    let startIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if ((lines[i] ?? '').trim() === needle) {
+            startIdx = i;
+            break;
+        }
+    }
+    if (startIdx === -1)
+        return null;
+    let endIdx = lines.length;
+    for (let i = startIdx + 1; i < lines.length; i++) {
+        const line = (lines[i] ?? '').trim();
+        const lineHashMatch = line.match(/^(#+)\s/);
+        if (lineHashMatch?.[1] && lineHashMatch[1].length <= level) {
+            endIdx = i;
+            break;
+        }
+    }
+    const extracted = lines.slice(startIdx, endIdx);
+    while (extracted.length > 0 && (extracted[extracted.length - 1] ?? '').trim() === '') {
+        extracted.pop();
+    }
+    if (extracted.length === 0)
+        return null;
+    return extracted.join('\n');
+}
+//# sourceMappingURL=subsection-extractor.js.map

package/dist/core/parsers/title-extractor.d.ts

@@ -33,4 +33,20 @@ import type { ToolResult } from '../../types/index.js';
  * ```
  */
 export declare function extractTitle(content: string, titleSource: string): ToolResult<string | undefined>;
+/**
+ * 마크다운 콘텐츠에서 H1 제목의 순수 작업명을 추출한다
+ *
+ * H1 형식 `# U-101[Mmp]: Ephemeral Token 발급`에서
+ * unitId prefix(`U-101[Mmp]:`)를 제거하고 순수 작업명만 반환.
+ *
+ * 지원 형식:
+ * - `# U-101[Mmp]: 작업명` → `작업명`
+ * - `# U-101: 작업명` → `작업명`
+ * - `# 작업명만` → `작업명만` (unitId prefix 없는 경우)
+ * - `# U-101[Mmp]: 작업명 — 부제목` → `작업명 — 부제목`
+ *
+ * @param content - 마크다운 전체 내용
+ * @returns 순수 작업명 문자열 (H1이 없으면 빈 문자열)
+ */
+export declare function extractTitleFromContent(content: string): string;
 //# sourceMappingURL=title-extractor.d.ts.map

package/dist/core/parsers/title-extractor.js

@@ -45,6 +45,32 @@ export function extractTitle(content, titleSource) {
     // 알 수 없는 소스 — undefined 반환 (Graceful Degradation)
     return ok(undefined);
 }
+/**
+ * 마크다운 콘텐츠에서 H1 제목의 순수 작업명을 추출한다
+ *
+ * H1 형식 `# U-101[Mmp]: Ephemeral Token 발급`에서
+ * unitId prefix(`U-101[Mmp]:`)를 제거하고 순수 작업명만 반환.
+ *
+ * 지원 형식:
+ * - `# U-101[Mmp]: 작업명` → `작업명`
+ * - `# U-101: 작업명` → `작업명`
+ * - `# 작업명만` → `작업명만` (unitId prefix 없는 경우)
+ * - `# U-101[Mmp]: 작업명 — 부제목` → `작업명 — 부제목`
+ *
+ * @param content - 마크다운 전체 내용
+ * @returns 순수 작업명 문자열 (H1이 없으면 빈 문자열)
+ */
+export function extractTitleFromContent(content) {
+    const normalized = normalizeLineEndings(content);
+    const h1 = extractH1Title(normalized);
+    if (!h1)
+        return '';
+    // `ID: 설명` 또는 `ID — 설명` 패턴에서 설명 부분만 추출
+    const prefixMatch = h1.match(/^[A-Za-z]+-\d+(?:-\w+)?(?:\[[^\]]*\])?\s*[:—-]\s*(.+)/);
+    if (prefixMatch?.[1])
+        return prefixMatch[1].trim();
+    return h1;
+}
 // ── 내부 헬퍼 ──
 /**
  * 첫 번째 H1 헤더에서 제목을 추출한다

package/dist/core/renderers/index.d.ts

@@ -8,6 +8,7 @@
 export { toShortId, toBareId, toSlug, buildTemplateVars, interpolatePattern, } from './interpolate.js';
 export { extractTitleOnly, buildSectionVars, interpolateTemplate } from './template-engine.js';
 export { renderSection } from './section-renderer.js';
+export type { RenderSectionOptions } from './section-renderer.js';
 export { updateSection, updateField } from './section-updater.js';
 export type { UpdateResult, MarkerOptions } from './section-updater.js';
 export { createBeginMarker, createEndMarker, findMarkerRange, isValidSectionKey, wrapWithMarkers, stripMarkers, } from './marker-utils.js';

package/dist/core/renderers/section-renderer.d.ts

@@ -12,6 +12,13 @@
  * @module
  */
 import type { CommandContext, UnitTypeConfig } from '../../types/index.js';
+/** renderSection 옵션 */
+export interface RenderSectionOptions {
+    /** 보존할 기존 특별 요청사항 콘텐츠 (헤딩 포함). truthy이면 설정 기반 렌더링 대신 사용 */
+    preservedSpecialRequests?: string;
+    /** 특별 요청사항 섹션 헤딩 (기본: "### 특별 요청사항") */
+    specialRequestsHeading?: string;
+}
 /**
  * 커맨드 파일 섹션을 렌더링한다
  *
@@ -25,7 +32,8 @@ import type { CommandContext, UnitTypeConfig } from '../../types/index.js';
  * @param context - 렌더링할 전체 컨텍스트 (유닛 메타 + 의존성 + 특별 요청)
  * @param unitTypeConfig - 유닛 유형 설정 (headerTemplate, collectDeps 등)
  * @param docPrefix - 문서 경로 앞에 붙일 프리픽스 (기본: "@")
+ * @param options - 추가 렌더링 옵션 (보존 콘텐츠, 커스텀 헤딩 등)
  * @returns 렌더링된 섹션 본문 문자열
  */
-export declare function renderSection(context: CommandContext, unitTypeConfig: UnitTypeConfig, docPrefix?: string): string;
+export declare function renderSection(context: CommandContext, unitTypeConfig: UnitTypeConfig, docPrefix?: string, options?: RenderSectionOptions): string;
 //# sourceMappingURL=section-renderer.d.ts.map

package/dist/core/renderers/section-renderer.js

@@ -16,6 +16,8 @@ import { interpolateTemplate } from './template-engine.js';
 const DEFAULT_DOC_PREFIX = '@';
 /** 빈 항목 표시 마커 */
 const EMPTY_MARKER = '-';
+/** 기본 특별 요청사항 헤딩 */
+const DEFAULT_SPECIAL_REQUESTS_HEADING = '### 특별 요청사항';
 /**
  * 커맨드 파일 섹션을 렌더링한다
  *
@@ -29,9 +31,10 @@ const EMPTY_MARKER = '-';
  * @param context - 렌더링할 전체 컨텍스트 (유닛 메타 + 의존성 + 특별 요청)
  * @param unitTypeConfig - 유닛 유형 설정 (headerTemplate, collectDeps 등)
  * @param docPrefix - 문서 경로 앞에 붙일 프리픽스 (기본: "@")
+ * @param options - 추가 렌더링 옵션 (보존 콘텐츠, 커스텀 헤딩 등)
  * @returns 렌더링된 섹션 본문 문자열
  */
-export function renderSection(context, unitTypeConfig, docPrefix = DEFAULT_DOC_PREFIX) {
+export function renderSection(context, unitTypeConfig, docPrefix = DEFAULT_DOC_PREFIX, options) {
     const lines = [];
     // 1. Header block (headerTemplate 변수 보간)
     const header = interpolateTemplate(unitTypeConfig.headerTemplate, context.unit);
@@ -42,8 +45,14 @@ export function renderSection(context, unitTypeConfig, docPrefix = DEFAULT_DOC_P
         renderDepDocs(lines, context, docPrefix);
         renderDepCommits(lines, context);
     }
-    // 3. 특별 요청사항 (항상 렌더링)
-    renderSpecialRequests(lines, context);
+    // 3. 특별 요청사항: 보존 콘텐츠가 있으면 그대로 사용, 없으면 설정에서 렌더링
+    if (options?.preservedSpecialRequests) {
+        lines.push('');
+        lines.push(...options.preservedSpecialRequests.split('\n'));
+    }
+    else {
+        renderSpecialRequests(lines, context, options?.specialRequestsHeading);
+    }
     return lines.join('\n');
 }
 /**
@@ -70,17 +79,24 @@ function renderDepUnits(lines, context) {
     }
 }
 /**
- * 의존성 문서 경로를 렌더링한다
+ * 의존성 문서 경로를 유닛별로 그룹핑하여 렌더링한다
  *
- * 형식: `- @{path}` (docPrefix 제어 가능)
+ * 각 의존 유닛의 계획서, 결과서, 런북 3종을 `- @{path}` 형식으로 한줄씩 렌더링.
+ * 유닛이 여러 개일 때 유닛 ID 주석으로 그룹 구분.
  */
 function renderDepDocs(lines, context, docPrefix) {
     lines.push('');
     lines.push('### 의존성 문서:');
-    const allDocs = context.depDocs.flatMap((d) => d.found);
-    if (allDocs.length > 0) {
-        for (const doc of allDocs) {
-            lines.push(`- ${docPrefix}${doc.path}`);
+    const nonEmptyGroups = context.depDocs.filter((d) => d.found.length > 0);
+    if (nonEmptyGroups.length > 0) {
+        const useGroupHeaders = nonEmptyGroups.length > 1;
+        for (const group of nonEmptyGroups) {
+            if (useGroupHeaders) {
+                lines.push(`<!-- ${group.unitId} -->`);
+            }
+            for (const doc of group.found) {
+                lines.push(`- ${docPrefix}${doc.path}`);
+            }
         }
     }
     else {
@@ -91,10 +107,11 @@ function renderDepDocs(lines, context, docPrefix) {
  * 의존성 커밋 SHA를 렌더링한다
  *
  * 형식: `- {sha}`
+ * 헤딩에 "(변경점 확인하여 맥락으로 사용)" 주석 포함
  */
 function renderDepCommits(lines, context) {
     lines.push('');
-    lines.push('### 의존성 Commits:');
+    lines.push('### 의존성 Commits (변경점 확인하여 맥락으로 사용):');
     if (context.depCommits.length > 0) {
         for (const sha of context.depCommits) {
             lines.push(`- ${sha}`);
@@ -113,9 +130,9 @@ function renderDepCommits(lines, context) {
  * 모든 미결정 질문이 답변되었으면 자동으로 ✅를 추가한다.
  * 답변된 페어링 질문은 특별 요청사항 뒤에 체크리스트 형태로 렌더링.
  */
-function renderSpecialRequests(lines, context) {
+function renderSpecialRequests(lines, context, heading) {
     lines.push('');
-    lines.push('### 특별 요청사항');
+    lines.push(heading ?? DEFAULT_SPECIAL_REQUESTS_HEADING);
     const allAnswered = areAllQuestionsAnswered(context);
     if (context.specialRequests.length > 0) {
         for (const req of context.specialRequests) {

package/dist/core/resolvers/backlog-resolver.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 백로그 분류 리졸버 — Layer 1 (Core)
+ *
+ * 파싱된 백로그 항목들을 필터링하고 상태별(ready/inProgress/blocked)로 분류한다.
+ *
+ * @module
+ */
+import type { BacklogEntry, ToolResult } from '../../types/index.js';
+/** 백로그 분류 옵션 */
+export interface BacklogFilterOptions {
+    phase?: string;
+    excludeCompleted?: boolean;
+}
+/** 백로그 분류 결과 */
+export interface ClassifiedBacklog {
+    total: number;
+    inProgress: BacklogEntry[];
+    ready: BacklogEntry[];
+    blocked: BacklogEntry[];
+    phase?: string;
+}
+/**
+ * 백로그 항목들을 분류한다 (Pure Function)
+ *
+ * @param entries - 파싱된 전체 백로그 항목
+ * @param options - 필터링 옵션
+ * @returns 분류된 결과
+ */
+export declare function classifyBacklog(entries: BacklogEntry[], options?: BacklogFilterOptions): ToolResult<ClassifiedBacklog>;
+/**
+ * 유닛 ID에서 phase 태그를 추출한다 (Pure Function)
+ *
+ * "U-016[Mvp]" → "Mvp"
+ * "CP-MVP-03" → null
+ */
+export declare function extractPhaseFromId(unitId: string): string | null;
+//# sourceMappingURL=backlog-resolver.d.ts.map

package/dist/core/resolvers/backlog-resolver.js

@@ -0,0 +1,50 @@
+/**
+ * 백로그 분류 리졸버 — Layer 1 (Core)
+ *
+ * 파싱된 백로그 항목들을 필터링하고 상태별(ready/inProgress/blocked)로 분류한다.
+ *
+ * @module
+ */
+import { ok } from '../../types/index.js';
+/**
+ * 백로그 항목들을 분류한다 (Pure Function)
+ *
+ * @param entries - 파싱된 전체 백로그 항목
+ * @param options - 필터링 옵션
+ * @returns 분류된 결과
+ */
+export function classifyBacklog(entries, options = {}) {
+    const { phase, excludeCompleted = true } = options;
+    // 1. 완료 항목 제외 (옵션에 따라)
+    let activeEntries = excludeCompleted ? entries.filter((e) => e.status !== 'completed') : entries;
+    // 2. phase 필터링 (대소문자 무시)
+    if (phase) {
+        const normalizedPhase = phase.toLowerCase();
+        activeEntries = activeEntries.filter((e) => {
+            const entryPhase = extractPhaseFromId(e.unitId);
+            return entryPhase !== null && entryPhase.toLowerCase() === normalizedPhase;
+        });
+    }
+    // 3. 상태별 분류
+    const inProgress = activeEntries.filter((e) => e.status === 'inProgress');
+    const ready = activeEntries.filter((e) => e.status === 'ready');
+    const blocked = activeEntries.filter((e) => e.status === 'blocked');
+    return ok({
+        total: activeEntries.length,
+        inProgress,
+        ready,
+        blocked,
+        ...(phase !== undefined && { phase }),
+    });
+}
+/**
+ * 유닛 ID에서 phase 태그를 추출한다 (Pure Function)
+ *
+ * "U-016[Mvp]" → "Mvp"
+ * "CP-MVP-03" → null
+ */
+export function extractPhaseFromId(unitId) {
+    const match = unitId.match(/\[([^\]]+)\]$/);
+    return match?.[1] ?? null;
+}
+//# sourceMappingURL=backlog-resolver.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-commander",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "description": "Unit-based vibe coding workflow automation CLI — automate context collection from unit ID to command file in 10 seconds",
   "license": "MIT",