vibe-commander 0.2.0 → 0.2.2

package/dist/config/schema.js

@@ -12,27 +12,43 @@ import { z } from 'zod';
 /** 기본 경로 설정 스키마 */
 export const pathsSchema = z.object({
     /** 커맨드 파일 경로 (프로젝트 루트 기준) */
-    commands: z.string().default('commands.md'),
+    commands: z
+        .string()
+        .default('commands.md')
+        .describe('Command file path where unit context sections are managed'),
     /** 로드맵 파일 경로. null이면 list-units 비활성화 */
-    roadmap: z.string().nullable().default('roadmap.md'),
+    roadmap: z
+        .string()
+        .nullable()
+        .default('roadmap.md')
+        .describe('Roadmap/backlog file path. Set to null to disable list-units command'),
     /** 역할별 문서 루트 디렉토리 (키: 역할명, 값: 상대 경로) */
-    docRoots: z.record(z.string(), z.string()).default({
+    docRoots: z
+        .record(z.string(), z.string())
+        .default({
         plan: 'unit-plans',
         result: 'unit-results',
         runbook: 'unit-runbooks',
-    }),
+    })
+        .describe('Document root directories by role (key: role name, value: relative path)'),
     /** 리팩토링 서브유닛 디렉토리. null이면 서브유닛 미사용 */
-    refactorSubDir: z.string().nullable().default(null),
+    refactorSubDir: z
+        .string()
+        .nullable()
+        .default(null)
+        .describe('Refactoring sub-unit directory. Set to null if sub-units are not used'),
 });
 // ── 유닛 유형 ──
 /** 유닛 유형 정의 스키마 */
 export const unitTypeSchema = z.object({
     /** 유형 키 (예: "implement", "refactor") */
-    key: z.string(),
+    key: z.string().describe("Unique type key (e.g. 'implement', 'refactor', 'feature')"),
     /** 표시 이름 (예: "유닛 구현"). 미제공 시 key 값 활용 */
-    displayName: z.string().optional(),
+    displayName: z.string().optional().describe('Human-readable display name for this type'),
     /** 유닛 ID 매칭 정규식 패턴 (예: "^(U-\\d+|CP-).*") */
-    idPattern: z.string().refine((val) => {
+    idPattern: z
+        .string()
+        .refine((val) => {
         try {
             new RegExp(val);
             return true;
@@ -40,46 +56,83 @@ export const unitTypeSchema = z.object({
         catch {
             return false;
         }
-    }, { message: '유효한 정규식 문자열이어야 합니다' }),
+    }, { message: '유효한 정규식 문자열이어야 합니다' })
+        .describe("Regex pattern to match unit IDs (e.g. '^U-\\\\d+.*', '^FEAT-\\\\d+$')"),
     /** 계획서 디렉토리 (paths.docRoots 키 참조) */
-    planDir: z.string(),
+    planDir: z.string().describe('Document root key (from paths.docRoots) where plans are stored'),
     /** 커맨드 파일 내 대상 섹션 헤더 (예: "# 유닛 구현") */
-    commandSection: z.string(),
+    commandSection: z
+        .string()
+        .describe("Target section header in the command file (e.g. '# Unit Implementation')"),
     /** 의존성 수집 여부 */
-    collectDeps: z.boolean(),
+    collectDeps: z
+        .boolean()
+        .describe('Whether to collect dependency documents and commits for this type'),
     /** 섹션 헤더 템플릿. {{unitId}}, {{title}} 등 변수 치환 지원 */
-    headerTemplate: z.string(),
+    headerTemplate: z
+        .string()
+        .describe('Section header template with variable interpolation: {{unitId}}, {{title}}, {{titleOnly}}, {{planPath}}, {{shortId}}'),
 });
 // ── 문서 탐색 ──
 /** 개별 문서 역할의 탐색 규칙 스키마 */
 export const docDiscoveryRuleSchema = z.object({
     /** 파일 탐색 패턴 (예: "{{unitId}}.md") */
-    pattern: z.string(),
+    pattern: z
+        .string()
+        .describe('File search pattern. Supports {{unitId}} and {{shortId}} variables'),
     /** glob 패턴 사용 여부 (기본: false) */
-    glob: z.boolean().optional().default(false),
+    glob: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Whether to use glob matching (true) or exact match (false)'),
 });
 /** 문서 탐색 설정 스키마 (역할별 규칙 맵) */
-export const docDiscoverySchema = z.record(z.string(), docDiscoveryRuleSchema);
+export const docDiscoverySchema = z
+    .record(z.string(), docDiscoveryRuleSchema)
+    .describe('Document discovery rules by role. Defines file name patterns for finding unit documents');
 // ── 계획서 파싱 ──
 /** 메타데이터 테이블 파싱 설정 스키마 */
 export const metadataTableSchema = z.object({
     /** ID 필드명 */
-    idField: z.string().default('Unit ID'),
+    idField: z
+        .string()
+        .default('Unit ID')
+        .describe('Field name for the unit ID in the metadata table'),
     /** Phase 필드명 */
-    phaseField: z.string().default('Phase'),
+    phaseField: z
+        .string()
+        .default('Phase')
+        .describe('Field name for the phase in the metadata table'),
     /** 의존성 필드명 */
-    dependsField: z.string().default('의존성'),
+    dependsField: z
+        .string()
+        .default('의존성')
+        .describe('Field name for dependencies in the metadata table'),
 });
 /** 계획서 파싱 설정 스키마 */
 export const planParsingSchema = z.object({
     /** 제목 추출 소스 ("h1" | "frontmatter:title") */
-    titleSource: z.enum(['h1', 'frontmatter:title']).default('h1'),
+    titleSource: z
+        .enum(['h1', 'frontmatter:title'])
+        .default('h1')
+        .describe("How to extract the unit title: 'h1' from first heading, 'frontmatter:title' from YAML frontmatter"),
     /** 의존성 추출 소스 ("section" | "frontmatter" | "metadata-table") */
-    dependsSource: z.enum(['section', 'frontmatter', 'metadata-table']).default('section'),
+    dependsSource: z
+        .enum(['section', 'frontmatter', 'metadata-table'])
+        .default('section')
+        .describe("How to extract dependencies: 'section' from markdown section, 'frontmatter' from YAML, 'metadata-table' from 2-column table"),
     /** 의존성 섹션 헤더명. null이면 섹션 기반 추출 비활성화 */
-    dependsSectionName: z.string().nullable().default('이전 작업에서 가져올 것'),
+    dependsSectionName: z
+        .string()
+        .nullable()
+        .default('이전 작업에서 가져올 것')
+        .describe('Dependency section header name. Set to null to disable section-based extraction'),
     /** 페어링 질문 섹션 헤더명 */
-    pairingQuestionSection: z.string().default('페어링 질문'),
+    pairingQuestionSection: z
+        .string()
+        .default('페어링 질문')
+        .describe('Section header name for pairing questions (checkbox items)'),
     /** 메타데이터 테이블 파싱 설정 */
     metadataTable: metadataTableSchema.prefault({}),
 });
@@ -87,24 +140,28 @@ export const planParsingSchema = z.object({
 /** 상태 표시 매핑 스키마 */
 export const statusMapSchema = z.object({
     /** 대기 상태 표시 */
-    ready: z.string().default('⏸️'),
+    ready: z.string().default('⏸️').describe('Ready/waiting status indicator'),
     /** 진행중 상태 표시 */
-    inProgress: z.string().default('🚧'),
+    inProgress: z.string().default('🚧').describe('In-progress status indicator'),
     /** 완료 상태 표시 */
-    completed: z.string().default('✅'),
+    completed: z.string().default('✅').describe('Completed status indicator'),
     /** 차단 상태 표시 */
-    blocked: z.string().default('❌'),
+    blocked: z.string().default('❌').describe('Blocked status indicator'),
 });
 /** 백로그(로드맵) 파싱 설정 스키마 */
 export const backlogParsingSchema = z.object({
     /** 백로그 섹션 시작 헤더 */
-    sectionHeader: z.string().default('## 작업 백로그'),
+    sectionHeader: z
+        .string()
+        .default('## 작업 백로그')
+        .describe('Backlog section start header in the roadmap file'),
     /** 백로그 항목 매칭 정규식 (named group 지원) */
     entryPattern: z
         .string()
-        .default('ID=\\[(?<id>.+?)\\]\\((?<path>[^)]+)\\)\\s*\\|\\s*(?<title>[^|]+)\\|\\s*Depends=(?<deps>[^|]*)\\|\\s*(?<status>.+)'),
+        .default('ID=\\[(?<id>.+?)\\]\\((?<path>[^)]+)\\)\\s*\\|\\s*(?<title>[^|]+)\\|\\s*Depends=(?<deps>[^|]*)\\|\\s*(?<status>.+)')
+        .describe('Regex pattern with named groups (id, path, title, deps, status) to match backlog entries'),
     /** 완료된 유닛 섹션 헤더 */
-    completedSection: z.string().default('### 완료'),
+    completedSection: z.string().default('### 완료').describe('Section header for completed units'),
     /** 상태 문자열 ↔ 내부 상태 키 매핑 */
     statusMap: statusMapSchema.prefault({}),
 });
@@ -112,40 +169,69 @@ export const backlogParsingSchema = z.object({
 /** 커밋 탐색 설정 스키마 */
 export const commitSearchSchema = z.object({
     /** 탐색 전략 ("git-log-grep" | "conventional-commit" | "disabled") */
-    strategy: z.string().default('git-log-grep'),
+    strategy: z
+        .string()
+        .default('git-log-grep')
+        .describe("Search strategy: 'git-log-grep', 'conventional-commit', or 'disabled'"),
     /** grep에 사용할 ID 변환 방식 (예: "shortId") */
-    extractId: z.string().default('shortId'),
+    extractId: z
+        .string()
+        .default('shortId')
+        .describe("ID transformation for grep: 'shortId' removes phase tag (e.g. U-001[Mvp] → U-001)"),
     /** 최대 결과 수 */
-    maxResults: z.number().default(5),
+    maxResults: z.number().default(5).describe('Maximum number of commits to return per dependency'),
     /**
      * 제외할 경로 glob 패턴 목록.
      * 변경 파일이 모두 이 패턴에 매칭되는 커밋은 필터링됨 (문서 전용 커밋 제거).
      * 기본값 [] → 필터 미적용
      */
-    excludePaths: z.array(z.string()).default([]),
+    excludePaths: z
+        .array(z.string())
+        .default([])
+        .describe("Glob patterns for paths to exclude (e.g. 'docs/**' to filter doc-only commits)"),
     /**
      * 필수 포함 경로 glob 패턴 목록.
      * 변경 파일 중 하나라도 이 패턴에 매칭되어야 통과 (소스 코드 커밋만 허용).
      * 기본값 [] → 필터 미적용
      */
-    requirePaths: z.array(z.string()).default([]),
+    requirePaths: z
+        .array(z.string())
+        .default([])
+        .describe("Glob patterns that at least one changed file must match (e.g. 'src/**' for source-only commits)"),
 });
 // ── 커맨드 파일 섹션 ──
 /** 커맨드 파일 섹션 설정 스키마 */
 export const commandSectionsSchema = z.object({
     /** 섹션 구분자 문자열 */
-    separator: z.string().default('---------------------------------------------------'),
+    separator: z
+        .string()
+        .default('---------------------------------------------------')
+        .describe('Section separator string in the command file'),
     /** 다른 섹션 보존 여부 */
-    preserveOtherSections: z.boolean().default(true),
+    preserveOtherSections: z
+        .boolean()
+        .default(true)
+        .describe('Whether to preserve sections not managed by the current unit type'),
     /** Commit SHA를 기록할 필드 키워드 (기본: "Commit") */
-    commitFieldName: z.string().default('Commit'),
+    commitFieldName: z
+        .string()
+        .default('Commit')
+        .describe('Field keyword for recording commit SHA in the command file'),
     /**
      * HTML 주석 마커 사용 여부.
      * true이면 섹션 경계에 `<!-- vc:begin:{key} -->` / `<!-- vc:end:{key} -->` 마커를 삽입하고,
      * 섹션 탐색 시 마커를 우선 사용한다 (Fallback으로 기존 헤더 기반 탐색).
      * 기본값 false로 기존 프로젝트 하위 호환 보장.
      */
-    useMarkers: z.boolean().default(false),
+    useMarkers: z
+        .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'),
 });
 // ── 최상위 설정 ──
 /** 기본 문서 탐색 설정 */
@@ -157,13 +243,16 @@ export const DEFAULT_DOC_DISCOVERY = {
 /** 프로젝트 설정 스키마 (vibe-commander.config.json) */
 export const projectConfigSchema = z.object({
     /** JSON Schema URL (IDE 자동완성용) */
-    $schema: z.string().optional(),
+    $schema: z.string().optional().describe('JSON Schema URL for IDE autocomplete and validation'),
     /** 설정 파일 버전 (현재 1 고정) */
-    version: z.literal(1),
+    version: z.literal(1).describe('Configuration file version (currently 1)'),
     /** 기본 경로 설정 */
     paths: pathsSchema.prefault({}),
     /** 유닛 유형 정의 배열 (순서 = ID 매칭 우선순위, 최소 1개 필수) */
-    unitTypes: z.array(unitTypeSchema).min(1),
+    unitTypes: z
+        .array(unitTypeSchema)
+        .min(1)
+        .describe('Unit type definitions. Array order determines ID matching priority (first match wins)'),
     /** 문서 탐색 규칙 (역할별) */
     docDiscovery: docDiscoverySchema.default(DEFAULT_DOC_DISCOVERY),
     /** 계획서 파싱 규칙 */
@@ -175,23 +264,21 @@ export const projectConfigSchema = z.object({
     /** 커맨드 파일 섹션 설정 */
     commandSections: commandSectionsSchema.prefault({}),
     /** 기본 특별 요청사항 목록 */
-    defaultSpecialRequests: z.array(z.string()).default([]),
+    defaultSpecialRequests: z
+        .array(z.string())
+        .default([])
+        .describe('Default special request strings appended to every unit context'),
     /** 유닛 유형별 추가 특별 요청사항 (키: unitType.key) */
-    specialRequestsByType: z.record(z.string(), z.array(z.string())).default({}),
+    specialRequestsByType: z
+        .record(z.string(), z.array(z.string()))
+        .default({})
+        .describe('Additional special requests per unit type (key: unitType.key, value: string array)'),
     /** 키 기반 선택적 특별 요청사항 (--request 옵션용, 키: 사용자 정의 식별자, 값: 텍스트) */
-    customRequests: z.record(z.string(), z.string()).default({}),
+    customRequests: z
+        .record(z.string(), z.string())
+        .default({})
+        .describe('Named special requests selectable via --request option (key: identifier, value: text)'),
 });
 /** 설정 파일명 */
 export const CONFIG_FILENAME = 'vibe-commander.config.json';
-/**
- * 프로젝트 설정 스키마를 JSON Schema (Draft 2020-12) 형식으로 반환한다
- *
- * Zod 4의 z.toJSONSchema() 내장 기능을 활용하여 변환.
- * 에이전트가 설정 파일 구조를 런타임에 조회할 수 있도록 한다.
- *
- * @returns JSON Schema 호환 객체
- */
-export function getConfigJsonSchema() {
-    return z.toJSONSchema(projectConfigSchema);
-}
 //# sourceMappingURL=schema.js.map

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,10 +8,11 @@
 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';
 export type { MarkerRange } from './marker-utils.js';
-export { COMMAND_REGISTRY, SCHEMA_SUBCOMMANDS, renderCommandsSchema, renderTypesSchema, } from './schema-renderer.js';
+export { COMMAND_REGISTRY, SCHEMA_SUBCOMMANDS, renderConfigSchema, renderCommandsSchema, renderTypesSchema, } from './schema-renderer.js';
 export type { ArgSchema, FlagSchema, CommandSchema, TypeSchemaEntry, SchemaSubcommandInfo, SchemaResult, } from './schema-renderer.js';
 //# sourceMappingURL=index.d.ts.map