@su-record/vibe 3.2.18 → 3.2.19

package/dist/tools/spec/validateSpecDocument.js

@@ -0,0 +1,201 @@
+/**
+ * SPEC 문서 Code Guard — `vibe.spec` 산출물이 하류로 넘어가기 전에 검사한다.
+ *
+ * 배경: vibe 의 결정론 게이트는 전부 파이프라인 **끝**(JUDGE — run-ledger·테스트·RTM)에
+ * 몰려 있었다. 중간 노드에는 가드가 없어, 게이트로 쓸 수 없는 SPEC 이 run 까지
+ * 흘러간 뒤 verify 단계에서야 걸렸다. 실패를 늦게 발견할수록 비싸다.
+ *
+ * 여기서 검사하는 것은 취향이 아니라 **하류가 실제로 요구하는 것**이다:
+ *  - RTM 은 `REQ-{feature}-NNN` 이 없으면 `status: 'empty'` 를 내고, 그건 통과가 아니라
+ *    판정불가다 (traceabilityMatrix.ts). 커버리지 게이트가 통째로 죽는다.
+ *  - `Stakes:` 는 디스패처가 파이프라인 깊이를 정하는 입력이다.
+ *  - Done Criteria 는 JUDGE 의 입력이다 — 없으면 판정할 것이 없다.
+ *  - 채워지지 않은 placeholder 는 직역 하네스가 실데이터로 넣는다
+ *    (dual-harness-doctrine 운영 규칙 2).
+ */
+import path from 'path';
+const REQ_ID = /\bREQ-([a-z0-9-]+)-(\d{3})\b/g;
+const STAKES_LINE = /^\s*[-*]?\s*\*{0,2}Stakes\*{0,2}\s*[:：]\s*(.+)$/im;
+const VALID_STAKES = ['demo', 'prototype', 'production'];
+/**
+ * 코드 구간(펜스 + 인라인 코드)을 공백으로 지운다 — 줄 번호는 보존한다.
+ *
+ * SPEC 은 경로 패턴(`styles/{feature}/`), 데이터 모양(`{r,g,b,a}`), 셸 brace
+ * expansion(`hooks/{a,b}.js`)을 인라인 코드로 정상적으로 쓴다. 원문을 그대로 훑으면
+ * 그것들이 전부 미치환 placeholder 로 잡힌다 (실측: 오탐 28건).
+ */
+function stripCodeSpans(content) {
+    const blank = (block) => block.replace(/[^\n]/g, ' ');
+    return content
+        .replace(/```[\s\S]*?```/g, blank)
+        .replace(/`[^`\n]*`/g, blank);
+}
+function lineOf(content, index) {
+    return content.slice(0, index).split('\n').length;
+}
+/** 파일명에서 feature 슬러그를 뽑는다 (분할 SPEC 은 디렉토리명) */
+export function featureSlugFromPath(specPath) {
+    const base = path.basename(specPath, '.md');
+    return base === '_index' ? path.basename(path.dirname(specPath)) : base;
+}
+function collectRequirementIds(content) {
+    const out = [];
+    for (const m of content.matchAll(REQ_ID)) {
+        out.push({ id: m[0], slug: m[1], index: m.index ?? 0 });
+    }
+    return out;
+}
+function checkRequirements(content, featureSlug, findings) {
+    const found = collectRequirementIds(content);
+    if (found.length === 0) {
+        findings.push({
+            severity: 'P1',
+            code: 'no-requirement-ids',
+            message: 'REQ-* ID 가 하나도 없다 — RTM 이 status:"empty" 를 내고 커버리지 게이트가 판정불가가 된다. '
+                + '모든 기능 요구사항에 REQ-{feature}-NNN 을 붙여라.',
+        });
+        return [];
+    }
+    // 파일명과 다른 슬러그는 게이트를 깨지는 않는다 — RTM 은 featureName 을 파일 탐색에만
+    // 쓰고 REQ 는 슬러그와 무관하게 전부 파싱한다(traceabilityMatrix.ts extractRequirements).
+    // 다만 ID 규약은 REQ-{feature}-NNN 이고(requirementId.ts), 어긋나면 여러 feature 의
+    // ID 가 한 문서에서 섞여 추적이 흐려진다 — 그래서 P2 로 알린다.
+    if (featureSlug) {
+        const mismatched = found.filter(f => f.slug !== featureSlug);
+        if (mismatched.length > 0) {
+            const slugs = [...new Set(mismatched.map(f => f.slug))];
+            findings.push({
+                severity: 'P2',
+                code: 'requirement-id-slug-mismatch',
+                message: `REQ 슬러그(${slugs.join(', ')})가 파일명(${featureSlug})과 다르다 — ${mismatched.length}건. `
+                    + 'RTM 집계에는 포함되지만 ID 규약(REQ-{feature}-NNN)에서 벗어나 추적이 흐려진다.',
+                line: lineOf(content, mismatched[0].index),
+            });
+        }
+    }
+    return [...new Set(found.map(f => f.id))];
+}
+function checkStakes(content, findings) {
+    const m = content.match(STAKES_LINE);
+    if (!m) {
+        findings.push({
+            severity: 'P1',
+            code: 'no-stakes',
+            message: 'Stakes 필드가 없다 — 디스패처가 파이프라인 깊이를 정할 입력이 없다 (demo | prototype | production).',
+        });
+        return;
+    }
+    const value = m[1].toLowerCase();
+    if (!VALID_STAKES.some(s => value.includes(s))) {
+        findings.push({
+            severity: 'P1',
+            code: 'invalid-stakes',
+            message: `Stakes 값을 알 수 없다: "${m[1].trim()}" — demo | prototype | production 중 하나여야 한다.`,
+        });
+    }
+}
+function checkDoneCriteria(content, findings) {
+    const heading = content.match(/^#{1,3}\s*\d*\.?\s*Done Criteria.*$/im);
+    if (!heading) {
+        findings.push({
+            severity: 'P1',
+            code: 'no-done-criteria',
+            message: 'Done Criteria 섹션이 없다 — JUDGE 가 판정할 입력이 없다.',
+        });
+        return;
+    }
+    // 섹션 본문에 D1 같은 기준 항목이 실제로 있는지
+    const after = content.slice((heading.index ?? 0) + heading[0].length);
+    const body = after.split(/^#{1,3}\s/m)[0];
+    if (!/\bD\d+\b/.test(body)) {
+        findings.push({
+            severity: 'P1',
+            code: 'empty-done-criteria',
+            message: 'Done Criteria 섹션에 기준 항목(D1, D2 …)이 없다 — 제목만 있고 판정 기준이 비었다.',
+            line: lineOf(content, heading.index ?? 0),
+        });
+    }
+}
+/**
+ * 템플릿에서 온 미치환 placeholder — 직역 하네스가 실데이터로 넣는다.
+ *
+ * 좁게 잡는다. 중괄호 하나만으로는 판단할 수 없다 — 경로 패턴·데이터 모양·brace
+ * expansion 이 전부 중괄호를 쓴다. 템플릿 placeholder 는 **산문**이라는 점이
+ * 구분점이다: `{Observable functional requirement}` 처럼 공백을 포함한다.
+ * 반면 `{feature}` · `{token}` · `{r,g,b,a}` 는 공백이 없다.
+ *
+ * `<예시>` 는 검사하지 않는다 — dual-harness-doctrine 이 **권장하는** 예시 표기이지
+ * 채워야 할 자리가 아니다. `<채워넣을 값>` 만 미치환으로 본다.
+ */
+function checkPlaceholders(content, findings) {
+    const scannable = stripCodeSpans(content);
+    const patterns = [
+        { re: /\{\{[^}\n]+\}\}/g, code: 'unresolved-template-var', label: '템플릿 변수' },
+        { re: /\{[^}\n]*\s[^}\n]*\}/g, code: 'unfilled-placeholder', label: 'placeholder' },
+        { re: /<채워넣을 값>/g, code: 'unfilled-placeholder', label: 'placeholder' },
+    ];
+    const seen = new Set();
+    for (const { re, code, label } of patterns) {
+        for (const m of scannable.matchAll(re)) {
+            const line = lineOf(scannable, m.index ?? 0);
+            if (seen.has(line))
+                continue;
+            seen.add(line);
+            findings.push({
+                severity: 'P1',
+                code,
+                message: `미치환 ${label}: ${m[0].slice(0, 60)} — 직역 하네스는 이 텍스트를 실데이터로 넣는다.`,
+                line,
+            });
+        }
+    }
+}
+function checkScenarios(content, findings) {
+    if (!/^#{1,3}\s*\d*\.?\s*Scenarios/im.test(content)) {
+        findings.push({
+            severity: 'P2',
+            code: 'no-scenarios',
+            message: 'Scenarios 섹션이 없다 — vibe.run 의 시나리오 루프가 분해할 단위가 없다.',
+        });
+    }
+}
+/**
+ * SPEC 문서를 검사한다.
+ *
+ * @param content SPEC 마크다운 원문
+ * @param options.specPath 파일 경로 — 주면 REQ 슬러그와 파일명 일치까지 검사한다
+ * @returns P1 이 없으면 valid
+ */
+export function validateSpecDocument(content, options = {}) {
+    const findings = [];
+    if (content.trim().length === 0) {
+        return {
+            valid: false,
+            findings: [{ severity: 'P1', code: 'empty-spec', message: 'SPEC 이 비어 있다.' }],
+            requirementIds: [],
+        };
+    }
+    const featureSlug = options.specPath ? featureSlugFromPath(options.specPath) : undefined;
+    const requirementIds = checkRequirements(content, featureSlug, findings);
+    checkStakes(content, findings);
+    checkDoneCriteria(content, findings);
+    checkPlaceholders(content, findings);
+    checkScenarios(content, findings);
+    return {
+        valid: !findings.some(f => f.severity === 'P1'),
+        findings,
+        requirementIds,
+    };
+}
+/** 사람이 읽는 한 줄 요약 — 스킬이 그대로 출력한다 */
+export function formatSpecValidation(result) {
+    if (result.valid && result.findings.length === 0) {
+        return `✅ SPEC guard 통과 — REQ ${result.requirementIds.length}건`;
+    }
+    const lines = result.findings.map(f => `  ${f.severity} ${f.code}${f.line ? ` (line ${f.line})` : ''}: ${f.message}`);
+    const head = result.valid
+        ? `⚠️ SPEC guard 통과 (P2 ${result.findings.length}건) — REQ ${result.requirementIds.length}건`
+        : `❌ SPEC guard 실패 — P1 ${result.findings.filter(f => f.severity === 'P1').length}건`;
+    return [head, ...lines].join('\n');
+}
+//# sourceMappingURL=validateSpecDocument.js.map

package/dist/tools/spec/validateSpecDocument.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@su-record/vibe",
-  "version": "3.2.18",
+  "version": "3.2.19",
   "description": "AI Coding Framework for Claude Code — 7+ agents, 52 skills, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",

package/skills/vibe/SKILL.md

@@ -103,12 +103,25 @@ user-invocable: true
 
 ### Phase 2: Smart Resume 감지
 
+**파일 존재 검사는 눈으로 하지 않는다 — 명령이 확정한다.** Phase 0 의 URL·첨부 분류와
+stakes 의 결정론 신호(config 유무·임시 디렉토리·git 여부)도 이 한 번의 호출로 함께 받는다:
+
+```bash
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => { console.log(JSON.stringify(t.collectDispatchSignals(process.cwd(), {urls: [], attachments: [], feature: undefined}), null, 2)); })"
 ```
-.vibe/.last-feature 존재 → 직전 feature 이름 추출
-.vibe/specs/{feature}/ 또는 .vibe/specs/{feature}.md 존재 → spec 단계 완료
-.vibe/features/{feature}/ 또는 .vibe/features/{feature}.feature 존재 → feature 단계 완료
-.vibe/plans/{feature}.md · .vibe/interviews/{feature}.md 존재 → 레거시 아티팩트 (구버전) — spec 패스의 입력 컨텍스트로만 사용, 재생성 금지
-```
+
+반환값을 **사실로 받는다**:
+
+| 필드 | 의미 |
+|---|---|
+| `resume.resumeFrom` | `run`(SPEC 있음) / `none`(처음부터) |
+| `resume.specPath` · `featurePath` | 실제 경로 (분할 SPEC `_index.md` 포함) |
+| `resume.legacyArtifacts` | 구버전 plans/interviews — **입력 컨텍스트로만** 쓰고 재생성 금지 |
+| `stakes.hasVibeConfig` · `isTempDir` · `isGitRepo` | Phase 1-b 의 결정론 신호 (언어 신호는 모델 판단으로 남는다) |
+| `urls[].kind` | `figma` / `github` / `youtube` / `web` |
+| `attachments[].kind` · `exists` | `spec` / `feature` / `document` / `image` / `code` |
+
+> 의도 분류(Phase 1)는 그대로 모델이 한다 — 애매한 판단은 모델, 파일 존재·도메인·확장자는 코드다.
 
 감지된 진행 상태가 있으면 사용자에게 명시:
 

package/skills/vibe.image/SKILL.md

@@ -34,6 +34,14 @@ Generate images using the Antigravity image backend.
 **Step 0: Script path:**
 - `[LLM_SCRIPT]` = `{{VIBE_PATH}}/hooks/scripts/llm-orchestrate.js`
 
+**Step 0-b: 비용 게이트 (생성 전 의무)** — 이미지 생성은 되돌릴 수 없는 지출이다. SSOT: `vibe/rules/loop-contract.md` 비용 게이트 절.
+
+```bash
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => { const op={kind:'paid-generation',provider:'antigravity',label:'이미지 {N}장 생성'}; console.log(t.formatCostGate(op, t.evaluateCostGate(op))); })"
+```
+
+`ask` 면 생성 전에 무엇을 몇 장 만들지 제시하고 확인받는다. `autonomous` 면 묻지 않고 인박스에 기록한 뒤 진행한다. `.vibe/config.json` 의 `costGate.paidGenerationRequiresApproval: false` 로 끌 수 있다.
+
 **General image generation (Antigravity fast image):**
 ```bash
 node "[LLM_SCRIPT]" antigravity image "IMAGE_DESCRIPTION" --output "OUTPUT_PATH"

package/skills/vibe.review/SKILL.md

@@ -124,6 +124,14 @@ Detect project tech stack FIRST before launching reviewers.
 
 **Spawn one reviewer per focus, as concurrently as the harness allows** — a `code-reviewer` instance per focus plus `security-reviewer`, each scoped to the changed files.
 
+**스폰 직전 비용 게이트** (SSOT: `vibe/rules/loop-contract.md` 비용 게이트 절). 위 표대로 정한 리뷰어 수를 그대로 넣는다:
+
+```bash
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => { const op={kind:'agent-fanout',agentCount:{N},label:'리뷰어 {N}종 병렬'}; console.log(t.formatCostGate(op, t.evaluateCostGate(op))); })"
+```
+
+기본 임계값(12)에서 demo 2종·prototype 3종·production 8종은 전부 **통과**한다 — 평상시 규모는 멈추지 않는다. `ask` 가 나오면 스폰 전에 사용자에게 확인하고, `record` (autonomous) 면 묻지 않고 인박스에 남긴 뒤 진행한다.
+
 호출 계약(하네스 무관): "에이전트 `{agent}` 를 인자 `Review {FILES} — focus: {focus}` 로 실행한다"
 
 ```

package/skills/vibe.spec/SKILL.md

@@ -35,6 +35,8 @@ Input 분석 + Smart Resume
     ↓
 Execute the bundled implementation below — 단일 패스: 컨텍스트 수집 → (필요시) 인라인 질문 → SPEC + Feature 작성 → 셀프 리뷰 1회
     ↓
+SPEC Code Guard (아래) — P1 이 있으면 승인으로 가지 않고 SPEC 작성으로 되돌아간다
+    ↓
 SPEC 승인 (1회 — automationLevel: autonomous 면 생략)
     ↓
 /vibe.run "{feature-name}"
@@ -65,6 +67,25 @@ Legacy `.vibe/interviews/` or `.vibe/plans/` artifacts가 실제로 감지된
 - 개인 작업 포인터이므로 git 커밋 금지 (`.gitignore` 에 `.vibe/.last-feature`).
 - 워크플로 완주(verify 통과) 시 삭제.
 
+## SPEC Code Guard (승인 전 의무)
+
+SPEC 을 쓴 직후, **승인을 요청하기 전에** 실행한다. 셀프 리뷰가 아니라 코드 판정이다:
+
+```bash
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => { const fs=require('fs'); const p='.vibe/specs/{feature-name}.md'; const r=t.validateSpecDocument(fs.readFileSync(p,'utf-8'),{specPath:p}); console.log(t.formatSpecValidation(r)); process.exitCode = r.valid ? 0 : 1; })"
+```
+
+| 검사 | 심각도 | 왜 하류가 깨지는가 |
+|---|---|---|
+| REQ-* ID 부재 | P1 | RTM 이 `status:"empty"` — 커버리지 게이트가 판정불가가 된다 |
+| Stakes 부재/오값 | P1 | 디스패처가 파이프라인 깊이를 정할 입력이 없다 |
+| Done Criteria 부재/빈 섹션 | P1 | JUDGE 가 판정할 기준이 없다 |
+| 미치환 placeholder | P1 | 직역 하네스가 예시 텍스트를 실데이터로 넣는다 |
+| Scenarios 부재 | P2 | `vibe.run` 시나리오 루프의 분해 단위가 없다 |
+| REQ 슬러그 ≠ 파일명 | P2 | 게이트는 통과하나 ID 규약 이탈로 추적이 흐려진다 |
+
+**P1 이 하나라도 있으면 승인 요청으로 넘어가지 않는다** — SPEC 작성으로 되돌아가 고치고 다시 검사한다 (backward edge). 2회 연속 같은 findings 면 stuck 으로 처리한다 (SSOT: `vibe/rules/loop-contract.md`). P2 는 통과를 막지 않고 승인 메시지에 함께 표시한다.
+
 ## 승인과 루프
 
 SPEC 승인이 `vibe/rules/loop-contract.md` 가 정의하는 **유일한 의무적 사람 개입**이다. 승인 후에는 ANCHOR→ACT→JUDGE→RECORD 루프가 게이트 통과까지 자동 반복한다 (`/vibe.run` → `/vibe.verify`). 별도의 파이프라인 승인·단계별 stop gate 는 없다.

package/vibe/rules/loop-contract.md

@@ -62,6 +62,37 @@ node "$HOOKS_DIR/loop-ledger.js" anchor [feature]
 
 > `autonomous` 의 "계속" 은 **stuck 난 루프를 더 돌린다는 뜻이 아니다** — 2회 연속 동일 발견은 정의상 재시도가 무의미하다. 같은 목표를 붙잡지 않고 다음 단위로 넘어간다는 뜻이며, 미달은 TODO/인박스에 남는다. 미달 상태를 **완료로 기록하지 않는다.**
 
+### 비용 게이트 — 사람은 시작점에만 서지 않는다
+
+SPEC 승인은 **유일한 의무 게이트**로 남는다. 다만 승인 이후 max_iterations 까지 무인이라, 그 안의 되돌릴 수 없는 지출과 이상 규모 팬아웃을 아무도 보지 못했다. 비용 게이트는 그 둘만 잡는다 — 평상시 규모는 그대로 통과시킨다.
+
+```bash
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => { const d=t.evaluateCostGate({kind:'agent-fanout',agentCount:N}); console.log(t.formatCostGate({kind:'agent-fanout',agentCount:N}, d)); })"
+```
+
+| 작업 | 기본 판정 | 근거 |
+|---|---|---|
+| `paid-generation` | **묻는다** | 되돌릴 수 없는 지출 |
+| `agent-fanout` > 12 | **묻는다** | 위임마다 컨텍스트 재주입 — 비용이 개수에 비례 |
+| `agent-fanout` ≤ 12 | 통과 | production 기본 리뷰어 셋(8종)+조건부는 평상시 규모다 |
+
+- 임계값을 기본 셋 아래로 두면 매 리뷰가 멈춘다 — **의례가 된 게이트는 무시당한다.** 조정은 `.vibe/config.json` 의 `costGate.{enabled, maxAgentsWithoutApproval, paidGenerationRequiresApproval}`.
+- `autonomous` 는 **묻지 않는다.** 대신 결정을 인박스에 기록한다 (`loop-ledger.js inbox`) — stuck 처리와 같은 원칙: 비대화형이라고 판정을 없애지 않고, 사람이 볼 자리로 옮긴다.
+
+### 노드 가드 — 게이트를 끝에만 두지 않는다
+
+결정론 게이트가 전부 JUDGE(파이프라인 끝)에만 있으면, 쓸 수 없는 산출물이 체인을 끝까지 타고 간 뒤에야 걸린다. 실패는 **만들어진 노드에서** 잡는 것이 싸다.
+
+- 산출물을 내는 노드는 그 산출물이 **하류가 요구하는 형태인지** 코드로 검사한다. 취향이 아니라 계약을 검사한다 — "이게 없으면 하류의 무엇이 깨지는가"로 항목을 정한다.
+- 실패하면 다음 노드로 가지 않고 **그 노드로 되돌아간다** (backward edge). 루프 전체를 재시작하지 않는다.
+- 되돌린 뒤에도 같은 findings 가 2회 연속이면 stuck 이다 (위 stuck 절).
+
+| 노드 | 가드 | 검사 근거 |
+|---|---|---|
+| `vibe.spec` | `validateSpecDocument` | RTM 이 게이트로 동작할 REQ-* / JUDGE 입력인 Done Criteria / 디스패처 입력인 Stakes / 직역 하네스가 실데이터로 넣는 placeholder |
+| `vibe.run` | 테스트 exit code · run-ledger | 기존 JUDGE |
+| `vibe.clone` · `vibe.figma` | pixelmatch diffRatio · computed CSS delta | 측정된 P1 (위 Judge 권한 경계 표) |
+
 ### 실행 실패 (error) — stuck 과 다른 종료 사유
 
 stuck 은 **같은 발견이 반복되는** 상태다. 스킬이 로드되지 않거나, 도구가 없거나, 파일이 없거나, 명령이 비정상 종료하는 것은 stuck 이 아니라 **실행 실패**이며 해시 비교로는 잡히지 않는다. 재시도 대상도 아니다 — 환경이 바뀌지 않는 한 결과가 같다.

package/dist/infra/lib/OrchestrateWorkflow.d.ts

@@ -1,88 +0,0 @@
-/**
- * Orchestrate Workflow Pattern
- * Intent Gate → Assessment → Delegation → Verification
- */
-export type CodebaseMaturity = 'disciplined' | 'transitional' | 'legacy' | 'greenfield';
-export interface IntentGateResult {
-    hasMatchingSkill: boolean;
-    skillName?: string;
-    shouldDelegate: boolean;
-    reason: string;
-}
-export interface CodebaseAssessment {
-    maturity: CodebaseMaturity;
-    patterns: string[];
-    techStack: string[];
-    testCoverage: 'high' | 'medium' | 'low' | 'none';
-    documentationLevel: 'comprehensive' | 'partial' | 'minimal' | 'none';
-    risks: string[];
-}
-export interface DelegationPlan {
-    phases: DelegationPhase[];
-    totalAgents: number;
-    estimatedComplexity: 'low' | 'medium' | 'high';
-    requiredVerifications: string[];
-}
-export interface DelegationPhase {
-    name: string;
-    agents: AgentTask[];
-    dependencies: string[];
-    verificationCriteria: string[];
-}
-export interface AgentTask {
-    agentType: string;
-    model: 'haiku' | 'sonnet' | 'opus';
-    prompt: string;
-    background: boolean;
-    timeout?: number;
-}
-export interface VerificationResult {
-    passed: boolean;
-    evidence: Evidence[];
-    issues: string[];
-    architectReview?: string;
-}
-export interface Evidence {
-    type: 'build' | 'test' | 'lint' | 'typecheck' | 'manual';
-    command?: string;
-    exitCode?: number;
-    output?: string;
-    passed: boolean;
-}
-/**
- * Phase 0: Intent Gate
- * Check if there's a matching skill BEFORE doing any work
- */
-export declare function checkIntentGate(prompt: string): IntentGateResult;
-/**
- * Phase 1: Codebase Assessment
- * Classify codebase maturity and characteristics
- */
-export declare function assessCodebase(signals: {
-    hasTests: boolean;
-    hasLinting: boolean;
-    hasTypescript: boolean;
-    hasCICD: boolean;
-    hasDocumentation: boolean;
-    fileCount: number;
-    techStack: string[];
-}): CodebaseAssessment;
-/**
- * Phase 2: Create Delegation Plan
- * Plan how to delegate work to sub-agents
- */
-export declare function createDelegationPlan(task: string, assessment: CodebaseAssessment, phaseCount?: number): DelegationPlan;
-/**
- * Phase 3: Verification with Evidence
- * Collect evidence of completion
- */
-export declare function createVerificationChecklist(plan: DelegationPlan): Evidence[];
-/**
- * Format orchestration status
- */
-export declare function formatOrchestrationStatus(phase: string, assessment: CodebaseAssessment, plan: DelegationPlan): string;
-/**
- * Background task rules
- */
-export declare function shouldRunInBackground(command: string): boolean;
-//# sourceMappingURL=OrchestrateWorkflow.d.ts.map

package/dist/infra/lib/OrchestrateWorkflow.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"OrchestrateWorkflow.d.ts","sourceRoot":"","sources":["../../../src/infra/lib/OrchestrateWorkflow.ts"],"names":[],"mappings":"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"}