leerness 1.9.375 → 1.9.377

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 1.9.377 — 2026-06-06 — UR-0025 모듈화: workspace reference guide 빌더 분리
+
+**🧩 워크스페이스 레퍼런스 가이드 빌더(~57줄)를 lib/pure-utils 로 분리.**
+
+### 구현
+1. **`_renderWorkspaceReferenceGuide(dirName, version, generatedAt)`**(pure-utils): 디렉토리 구조/자주 묻는 위치/마이그레이션 안내 가이드 빌더. version·timestamp 주입(순수).
+2. **harness `_buildWorkspaceReferenceGuide(root, dirName)`**: 얇은 래퍼(`_renderWorkspaceReferenceGuide(dirName, VERSION, new Date().toISOString())`).
+3. 전사 위험 회피: node 스크립트로 결정적 교체 + 출력 동일성(핵심 마커) 검증.
+
+### 검증 (회귀 0)
+- **selftest 122→123 PASS** (행위: 빌더가 dirName/version 반영 + 핵심 섹션 포함 + 래퍼 얇음 + 모듈 reference equality).
+- **E2E 321→322 PASS** (행위: lib/pure-utils 직접 호출로 가이드 빌더 출력 검증).
+
+## 1.9.376 — 2026-06-06 — UR-0073 Phase D: team deploy 2중 게이트 (에이전트 팀 umbrella 완결) 🎉
+
+**🧩 정의된 팀의 사용자 설정 배포 명령을 안전 게이트로 실행 — `leerness team deploy`. UR-0073 A~D 완결.**
+
+### 배경
+UR-0073 로드맵의 마지막·최고위험 단계(실제 외부 배포). 방향 설계 안전 원칙(opt-in/dry-run 기본/명시 승인) 엄격 적용. **Firebase/블로그를 하드코딩하지 않고**(offline-first/0-deps 유지) 사용자가 `deployCommand` 를 설정하면 leerness 가 게이트와 함께 오케스트레이션.
+
+### 구현
+1. **`team add --deploy "<명령>"`**: 팀에 사용자 설정 배포 명령(예: `firebase deploy --only hosting`, `npm run deploy`) 저장.
+2. **`team deploy <id> [--yes]`** + **`_teamDeployGate`**(순수, 4-mode): 
+   - **dry-run**(기본, --yes 없음): 명령 표시만, 실행 X.
+   - **gated**(--yes 만, env 없음): **거부** — `LEERNESS_TEAM_DEPLOY=1` 필요.
+   - **execute**(--yes + `LEERNESS_TEAM_DEPLOY=1`): shell-guard advisory 점검 후 팀 root 에서 spawn.
+   - no-command: deployCommand 미설정 안내.
+3. **2중 게이트 안전**: 실행은 명시 플래그(`--yes`) AND 명시 env opt-in(`LEERNESS_TEAM_DEPLOY=1`) 동시 충족 시에만. (전역 지침 "deploy 신중" 준수.)
+4. _renderTeamsMd/show + commands/help 에 deploy 반영.
+
+### 검증 (회귀 0)
+- **selftest 121→122 PASS** (행위: `_teamDeployGate` 4-mode no-command/dry-run/gated/execute).
+- **E2E 320→321 PASS** (행위: dry-run 실행 X marker 없음 · --yes만 거부 marker 없음 · --yes+env 실행 marker 생성).
+- 실측: 3개 게이트 경로 정확 + 배포 명령 spawn 검증.
+
+### 🎉 UR-0073 에이전트 팀 umbrella 완결
+A(정의 레지스트리)·B(preview dry-run)·C(스케줄 알림)·**D(배포 2중 게이트)** 전 단계 완료. 모두 opt-in/dry-run/게이트 안전 위에 구축.
+
 ## 1.9.375 — 2026-06-06 — UR-0084: 동시성 락 하드닝 (e2e flake 제거 + lost-update 창 축소)
 
 **🛠 고부하 시 간헐 flake 한 락 테스트 + `_withLock` fail-open 창 하드닝.**

package/README.md

@@ -3,7 +3,7 @@
 > **AI 코딩 에이전트의 거짓 완료·중복·망각·충돌을 막아주는 검수·기억·협업 CLI 하네스.**
 > **A CLI harness that stops AI coding agents from faking completion, duplicating work, forgetting context, and colliding.**
 
-[![npm](https://img.shields.io/badge/npm-leerness-blue)](https://www.npmjs.com/package/leerness) [![version](https://img.shields.io/badge/version-1.9.375-green)]() [![tests](https://img.shields.io/badge/e2e-320%2F320-success)]() [![selftest](https://img.shields.io/badge/selftest-121-success)]() [![mcp](https://img.shields.io/badge/MCP--tools-83-brightgreen)]() [![providers](https://img.shields.io/badge/AI_providers-10-brightgreen)]() [![license](https://img.shields.io/badge/license-MIT-lightgrey)]()
+[![npm](https://img.shields.io/badge/npm-leerness-blue)](https://www.npmjs.com/package/leerness) [![version](https://img.shields.io/badge/version-1.9.377-green)]() [![tests](https://img.shields.io/badge/e2e-322%2F322-success)]() [![selftest](https://img.shields.io/badge/selftest-123-success)]() [![mcp](https://img.shields.io/badge/MCP--tools-83-brightgreen)]() [![providers](https://img.shields.io/badge/AI_providers-10-brightgreen)]() [![license](https://img.shields.io/badge/license-MIT-lightgrey)]()
 
 ```
   ╔══════════════════════════════════════════════════════════════╗
@@ -471,7 +471,7 @@ MIT — © leerness contributors
 <!-- leerness:project-readme:start -->
 ## Leerness Project Harness
 
-이 프로젝트는 Leerness v1.9.375 하네스를 사용합니다. AI 에이전트는 작업 전 `leerness handoff`로 컨텍스트를 적재하고, 작업 후 `leerness check`/`leerness audit`/`leerness session close`를 수행해야 합니다.
+이 프로젝트는 Leerness v1.9.377 하네스를 사용합니다. AI 에이전트는 작업 전 `leerness handoff`로 컨텍스트를 적재하고, 작업 후 `leerness check`/`leerness audit`/`leerness session close`를 수행해야 합니다.
 
 ### 정체성 — AI 에이전트 운영 레이어 (UR-0030)
 
@@ -525,7 +525,7 @@ leerness memory restore decision <date|title>
 
 ### MCP server (외부 AI 통합)
 
-Leerness v1.9.375는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 **83개 도구**를 노출:
+Leerness v1.9.377는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 **83개 도구**를 노출:
 
 ```jsonc
 // 카테고리별
@@ -546,7 +546,7 @@ Leerness v1.9.375는 stdio JSON-RPC MCP server를 내장합니다 — Claude Cod
 `<<autonomous-loop-dynamic>>` 신호만 보내면 AI가:
 1) 다음 라운드 후보 선정 → 2) 코드 변경 → 3) stress-v* 신규 작성 + 누적 회귀 → 4) e2e 219/219 → 5) npm pack + git tag + GitHub release → 6) main 자동 push (1.9.140+) → 7) session close → 8) 다음 라운드 예약.
 
-현재 누적: **70 라운드 (1.9.40 → 1.9.375)** · 매 라운드 GitHub release/태그 생성 · _reports/는 비공개 보존.
+현재 누적: **70 라운드 (1.9.40 → 1.9.377)** · 매 라운드 GitHub release/태그 생성 · _reports/는 비공개 보존.
 
 ### 성능 가이드 (1.9.140 측정)
 
@@ -584,6 +584,6 @@ leerness release pack --close --auto-main-push
 - `.harness/session-handoff.md`: 다음 세션 인수인계 (자동 작성)
 - `.harness/lessons.md` / `decisions.md` / `rules.md`: 영구 메모리 (5 surface)
 
-Last synced by Leerness v1.9.375: 2026-06-06
+Last synced by Leerness v1.9.377: 2026-06-06
 <!-- leerness:project-readme:end -->
 

package/bin/harness.js

@@ -7,7 +7,7 @@ const cp = require('child_process');
 const os = require('os');  // 1.9.178: _publishToNpm 에서 os.tmpdir() 사용 (전역 import)
 const readline = require('readline');
 // 1.9.274 (UR-0025 1단계): 순수 유틸 함수 모듈 분리 (require-based, 비파괴). selftest 7종이 동작 검증.
-const { _isSecretKey, _isPlaceholderSecret, _looksSecretLike, _mergeLines, _mergeEnvLines, _mergeReadmeSection, _managedMerge, _parseSkillsValue, _parseArchiveBlocks, _parseSkillCatalog, _renderTeamsMd, _composeTeamPlan, _teamHandoffReminders, _cadenceAssessment, compareVer, parseHarnessVersion, _classifyCJK, _riskLabel, _detectSystemLang, _parseSlashFromHelp,
+const { _isSecretKey, _isPlaceholderSecret, _looksSecretLike, _mergeLines, _mergeEnvLines, _mergeReadmeSection, _managedMerge, _parseSkillsValue, _parseArchiveBlocks, _parseSkillCatalog, _renderTeamsMd, _composeTeamPlan, _teamHandoffReminders, _cadenceAssessment, _teamDeployGate, _renderWorkspaceReferenceGuide, compareVer, parseHarnessVersion, _classifyCJK, _riskLabel, _detectSystemLang, _parseSlashFromHelp,
   PERMISSION_TIERS, _tierRank, _requiredTier, _policyAllows, _resolveNpmTag, _mcpJsonContent, _newRunRecord,
   _htmlToText, _extractTitle, _extractLinks,
   _countDatedBlocks, _extractDecisionBlocks, _classifyIntent,
@@ -28,7 +28,7 @@ const { _evidenceQuality, _parseEvidenceStats, _shellGuardAnalyze, _claimFileInG
 // 1.9.295 (UR-0025 4단계): 정적 데이터 카탈로그 모듈 분리 (비파괴, require-based).
 const { CAPABILITY_SURFACE, POWERFUL_COMMANDS, ADAPTERS, REUSE_CATEGORIES, REUSE_CHECKLIST, _DEFAULT_PLATFORM_CONSTRAINTS, _DEFAULT_DOMAIN_CATALOG, _LSP_LANG_PATTERNS, OPTIMISM_PATTERNS, BUILT_IN_PERSONAS, STRINGS, BUILTIN_CATALOG, ROADMAP_STATUS_LABEL, ROADMAP_STATUS_COLOR, SECRET_PATTERNS, MERGE_OVERWRITE_FILES, MINIMAL_SKIP_KEYS, SKILL_CATALOG_PRESETS } = require('../lib/catalogs');  // 1.9.344/368/369 (UR-0025): catalog 분리 (MERGE_OVERWRITE_FILES/MINIMAL_SKIP_KEYS 포함)
 
-const VERSION = '1.9.375';
+const VERSION = '1.9.377';
 
 // 1.9.290 (UR-0037, Codex gpt-5.5 #4 수렴): CLI 전용 부작용은 require 시 실행하지 않는다.
 //   이전: warning listener 제거 / NODE_OPTIONS 변경 / chcp IIFE 가 top-level 즉시 실행 → require('harness') 시 호스트 프로세스 오염.
@@ -3012,6 +3012,8 @@ function _selfTestCases() {
     { name: 'UR-0073 Phase C: _teamHandoffReminders 스케줄 알림 (비-manual·active 만, 실행 트리거 아님) 행위 (1.9.373)', run: () => { const m = require('../lib/pure-utils'); if (typeof _teamHandoffReminders !== 'function' || m._teamHandoffReminders !== _teamHandoffReminders) return false; const r = _teamHandoffReminders([{ id: 'rev', schedule: 'every-session', status: 'active', members: ['a', 'b'] }, { id: 'man', schedule: 'manual', status: 'active' }, { id: 'paused', schedule: 'daily', status: 'paused' }]); return r.length === 1 && r[0].includes('rev') && r[0].includes('every-session') && r[0].includes('team preview rev') && !r.join('|').includes('man') && !r.join('|').includes('paused'); } },
     { name: 'UR-0074: _cadenceAssessment 릴리스 빈도 평가 (임계값) 행위 (1.9.374)', run: () => { const m = require('../lib/pure-utils'); if (typeof _cadenceAssessment !== 'function' || m._cadenceAssessment !== _cadenceAssessment || typeof releaseCadenceCmd !== 'function') return false; return _cadenceAssessment(7, 1, 1).level === 'very-high' && _cadenceAssessment(3, 1, 1).level === 'high' && _cadenceAssessment(1, 1, 1).level === 'moderate' && _cadenceAssessment(0.2, 1, 1).level === 'healthy' && _cadenceAssessment(7, 1, 1).recommendation.length > 0; } },
     { name: 'UR-0084: _withLock 획득/재진입/해제 + maxWaitMs 하드닝(10s) 행위 (1.9.375)', run: () => { if (typeof _withLock !== 'function') return false; const src = read(__filename); const hardened = /maxWaitMs = opts\.maxWaitMs \|\| 10000/.test(src); const tmp = fs.mkdtempSync(path.join(os.tmpdir(), '__leerness_lock_')); try { const target = path.join(tmp, 'f.md'); let reentrant = false; const lockSeen = _withLock(target, () => { const exists = fs.existsSync(target + '.lock'); reentrant = (_withLock(target, () => 42) === 42); return exists; }); const cleaned = !fs.existsSync(target + '.lock'); return hardened && lockSeen === true && reentrant === true && cleaned; } finally { try { fs.rmSync(tmp, { recursive: true, force: true }); } catch {} } } },
+    { name: 'UR-0073 Phase D: _teamDeployGate 이중 게이트 (dry-run 기본/env 게이트/실행) 행위 (1.9.376)', run: () => { const m = require('../lib/pure-utils'); if (typeof _teamDeployGate !== 'function' || m._teamDeployGate !== _teamDeployGate) return false; const team = { id: 'd', deployCommand: 'echo hi' }; const noCmd = _teamDeployGate({ id: 'x' }, { yes: true, envOn: true }).mode === 'no-command'; const dry = _teamDeployGate(team, { yes: false, envOn: true }).mode === 'dry-run'; const gated = _teamDeployGate(team, { yes: true, envOn: false }).mode === 'gated'; const exec = _teamDeployGate(team, { yes: true, envOn: true }).mode === 'execute'; return noCmd && dry && gated && exec; } },
+    { name: 'UR-0025: _renderWorkspaceReferenceGuide 모듈 분리 + 빌더 동작 (1.9.377)', run: () => { const m = require('../lib/pure-utils'); if (typeof _renderWorkspaceReferenceGuide !== 'function' || m._renderWorkspaceReferenceGuide !== _renderWorkspaceReferenceGuide) return false; const g = _renderWorkspaceReferenceGuide('.leerness', '9.9.9', '2026-01-01T00:00:00.000Z'); const wrapperThin = read(__filename).includes('return _renderWorkspaceReferenceGuide(dirName, VERSION, new Date().toISOString())'); return g.includes('.leerness/progress-tracker.md') && g.includes('9.9.9') && g.includes('자주 묻는 위치') && g.includes('마이그레이션 안내') && wrapperThin; } },
     { name: 'VERSION 형식 (x.y.z)', run: () => /^\d+\.\d+\.\d+$/.test(VERSION) }
   ];
 }
@@ -3651,7 +3653,7 @@ function commandsCmd(root) {
       { cmd: 'deploy auto', desc: '배포 자동화' },
       { cmd: 'runs list|show', desc: '실행 이력' },
       { cmd: 'whats-new [path]', desc: '최근 버전 변경 요약' },
-      { cmd: 'team list|add|show|remove|preview <id> [--name --purpose --personas --members --schedule --task]', desc: '에이전트 팀 정의 + preview(dry-run 실행계획) — UR-0073 Phase A/B, opt-in · 정의/미리보기 전용' }
+      { cmd: 'team list|add|show|remove|preview|deploy <id> [--name --purpose --personas --members --schedule --task --deploy --yes]', desc: '에이전트 팀 정의 + preview(dry-run) + deploy(2중 게이트) — UR-0073 A~D, opt-in · 배포는 --yes+LEERNESS_TEAM_DEPLOY=1' }
     ]
   };
   if (has('--json')) {
@@ -4234,66 +4236,9 @@ function _migrateWorkspaceDir(root, opts = {}) {
   return report;
 }
 // AI 참조 가이드 빌더 — 워크스페이스 디렉토리 구조 + 파일별 역할 매핑
+// 1.9.377 (UR-0025): 순수 코어 _renderWorkspaceReferenceGuide (lib/pure-utils) + 얇은 래퍼 (root 미사용, version/timestamp 주입).
 function _buildWorkspaceReferenceGuide(root, dirName) {
-  const lines = [];
-  lines.push(`# Leerness Workspace Reference Guide`);
-  lines.push('');
-  lines.push(`> AI 에이전트가 leerness 워크스페이스에서 어떤 파일을 어디서 찾는지 안내합니다 (1.9.211).`);
-  lines.push('');
-  lines.push(`Generated: ${new Date().toISOString()} by leerness ${VERSION}`);
-  lines.push(`Workspace dir: \`${dirName}/\``);
-  lines.push('');
-  lines.push(`## 📁 디렉토리 구조 (핵심)`);
-  lines.push('');
-  lines.push('```');
-  lines.push(`${dirName}/`);
-  lines.push(`├── plan.md                    ← 무엇을 할 것인가 (사용자 메모리)`);
-  lines.push(`├── progress-tracker.md        ← 무엇을 했는가 (증거 포함, 사용자 메모리)`);
-  lines.push(`├── decisions.md               ← 왜 그렇게 했는가 (사용자 메모리)`);
-  lines.push(`├── session-handoff.md         ← 다음 세션 인계 (사용자 메모리)`);
-  lines.push(`├── lessons.md                 ← 과거 교훈 (자동 fuzzy 회수)`);
-  lines.push(`├── rules.md                   ← 자연어 룰 (매 세션 자동 노출, R-XXXX)`);
-  lines.push(`├── task-log.md                ← in-progress / dropped task 이력`);
-  lines.push(`├── reuse-map.md               ← 워크스페이스 capability 매핑`);
-  lines.push(`├── skill-suggestions.md       ← skill rolling history`);
-  lines.push(`├── feature-graph.md           ← 기능 의존 그래프 (F-XXXX)`);
-  lines.push(`├── manifest.json              ← 워크스페이스 메타`);
-  lines.push(`├── leerness-config.json       ← 비시크릿 LEERNESS_* 설정 (1.9.187, AI 가시)`);
-  lines.push(`├── user-requests.json         ← 사용자 명시 요청 누적 (1.9.207)`);
-  lines.push(`├── active-wakeups.json        ← ScheduleWakeup 상태 (1.9.205)`);
-  lines.push(`├── pre-wake-report.json       ← sleep 전 sub-agent audit (1.9.209)`);
-  lines.push(`├── wakeup-history.json        ← adaptive wakeup 이력 (1.9.210)`);
-  lines.push(`├── platform-constraints.json  ← API 제약 catalog (1.9.208)`);
-  lines.push(`├── auto-resume-plan.json      ← 다음 라운드 plan (1.9.203)`);
-  lines.push(`├── next-action-queue.json     ← 다음 next-action 큐 (1.9.201)`);
-  lines.push(`├── last-handoff.json          ← 마지막 handoff timestamp`);
-  lines.push(`├── environment.json           ← 환경 변동 추적 (1.9.145)`);
-  lines.push(`├── skills/                    ← 설치된 skill 디렉토리`);
-  lines.push(`└── templates/                 ← 워크스페이스 템플릿`);
-  lines.push('```');
-  lines.push('');
-  lines.push(`## 🧭 자주 묻는 위치`);
-  lines.push('');
-  lines.push(`| 찾는 것 | 위치 |`);
-  lines.push(`|---|---|`);
-  lines.push(`| 현재 진행 중인 task | \`${dirName}/progress-tracker.md\` (status: in-progress) |`);
-  lines.push(`| 사용자가 명시한 영구 룰 | \`${dirName}/rules.md\` (active R-XXXX) |`);
-  lines.push(`| 직전 sleep 전 audit 결과 | \`${dirName}/pre-wake-report.json\` (1.9.209) |`);
-  lines.push(`| 미답 사용자 요청 | \`${dirName}/user-requests.json\` (status: open) |`);
-  lines.push(`| 다음 라운드 권장 단계 | \`${dirName}/auto-resume-plan.json\` (1.9.203) |`);
-  lines.push(`| API 제약 catalog | \`${dirName}/platform-constraints.json\` (1.9.208) |`);
-  lines.push(`| 자동 wakeup 권장 간격 | \`${dirName}/wakeup-history.json\` (1.9.210) |`);
-  lines.push('');
-  lines.push(`## 🔄 마이그레이션 안내`);
-  lines.push('');
-  lines.push(`이 워크스페이스는 \`.harness\` → \`.leerness\` 로 마이그레이션되었을 수 있습니다.`);
-  lines.push(`- \`.leerness/MIGRATED_FROM_HARNESS\` 존재 → 마이그레이션 완료, \`.leerness\` 우선 사용`);
-  lines.push(`- \`.harness/MIGRATED_TO_LEERNESS.md\` 존재 → \`.leerness/\` 로 가야 함`);
-  lines.push(`- 양쪽 모두 없음 → 기본 \`.harness\` 사용 중`);
-  lines.push('');
-  lines.push(`AI 에이전트는 \`leerness handoff .\` 결과를 신뢰하십시오 — 자동으로 올바른 디렉토리를 사용합니다.`);
-  lines.push('');
-  return lines.join('\n');
+  return _renderWorkspaceReferenceGuide(dirName, VERSION, new Date().toISOString());
 }
 
 // 1.9.213: intent inference + scope expansion 게이트 (사용자 명시)
@@ -5897,6 +5842,7 @@ function teamCmd(root, sub, id, opts = {}) {
       personas: splitCsv(arg('--personas', null)),
       members: splitCsv(arg('--members', null)),
       schedule: validSched.has(sched) ? sched : 'manual',
+      deployCommand: arg('--deploy', '') === true ? '' : arg('--deploy', ''),  // 1.9.376 (Phase D): 사용자 설정 배포 명령 (실행은 게이트)
       status: 'active',
       createdAt: now()
     };
@@ -5916,6 +5862,7 @@ function teamCmd(root, sub, id, opts = {}) {
     log(`  personas: ${(t.personas || []).join(', ') || '-'}`);
     log(`  members: ${(t.members || []).join(', ') || '-'}`);
     log(`  schedule: ${t.schedule || 'manual'}  ·  status: ${t.status || 'active'}`);
+    log(`  deploy: ${t.deployCommand || '-'}`);
     return;
   }
   if (sub === 'remove') {
@@ -5944,7 +5891,37 @@ function teamCmd(root, sub, id, opts = {}) {
     log(`\n  ⓘ dry-run — 실제 dispatch/배포 없음. 위 명령을 검토 후 직접 실행하거나, 향후 Phase C(스케줄)/D(배포)에서 게이트 적용.`);
     return;
   }
-  fail(`알 수 없는 team 하위명령: ${sub} (list|add|show|remove|preview)`);
+  // 1.9.376 (UR-0073 Phase D): team deploy — 사용자 설정 deployCommand 실행. 안전: dry-run 기본 + --yes + LEERNESS_TEAM_DEPLOY=1 이중 게이트 + shell-guard.
+  if (sub === 'deploy') {
+    const t = teams.find(x => x.id === id);
+    if (!t) { fail(`team 없음: ${id}`); return; }
+    const gate = _teamDeployGate(t, { yes: has('--yes'), envOn: process.env.LEERNESS_TEAM_DEPLOY === '1' });
+    if (json) { log(JSON.stringify({ version: VERSION, teamId: t.id, ...gate }, null, 2)); if (gate.mode !== 'execute') return; }
+    if (gate.mode === 'no-command') { fail(`team '${t.id}' deployCommand 미설정 — leerness team add ${t.id} --deploy "<배포 명령>"`); return; }
+    if (gate.mode === 'dry-run') {
+      log(`# team deploy ${t.id} (1.9.376, UR-0073 Phase D) — dry-run (실행 없음)`);
+      log(`  배포 명령: ${gate.command}`);
+      log(`  ⓘ ${gate.message}`);
+      log(`  실행: LEERNESS_TEAM_DEPLOY=1 leerness team deploy ${t.id} --yes  (셸 호환성 점검 후 실행)`);
+      return;
+    }
+    if (gate.mode === 'gated') { fail(`${gate.message} — dry-run 으로 먼저 검토: leerness team deploy ${t.id}`); return; }
+    // execute: shell-guard 정적 점검(advisory) 후 spawn
+    try {
+      const ctx = _detectShellCtx();
+      const guard = _shellGuardAnalyze ? _shellGuardAnalyze(gate.command, ctx) : null;
+      if (guard && guard.findings && guard.findings.length) {
+        warn(`shell-guard 경고 ${guard.findings.length}건 (배포 명령): ${guard.findings.map(f => f.rule || f.kind || f).join(', ')}`);
+      }
+    } catch {}
+    log(`# team deploy ${t.id} — 실행 (LEERNESS_TEAM_DEPLOY=1 + --yes)`);
+    log(`  $ ${gate.command}`);
+    const r = cp.spawnSync(gate.command, { cwd: root, shell: true, stdio: 'inherit', timeout: 600000 });
+    if (r.status === 0) ok(`team deploy 완료: ${t.id} (exit 0)`);
+    else { fail(`team deploy 실패: ${t.id} (exit ${r.status})`); }
+    return;
+  }
+  fail(`알 수 없는 team 하위명령: ${sub} (list|add|show|remove|preview|deploy)`);
 }
 
 // 1.9.112: 전용 lessons.md (Memory Write Surface 5번째)
@@ -21224,7 +21201,7 @@ function help() {
   leerness skill install <SKILL.md|dir|url> · leerness skill discover --preset vercel|anthropic   # 스킬 설치/탐색
   leerness release bump [--patch|--minor|--major]  # package.json 자동 bump (1.9.8)
   leerness release note "<내용>"               # CHANGELOG.md 자동 추가 (1.9.8)
-  leerness release publish [--dry-run] [--pack] [--git-push] [--gh-release] [--gh-pages] [--gh-pages-src file] [--npm-publish] [--auto]  # 통합 배포 (1.9.8 + 1.9.10)\n  leerness impact <target> [--all]           # 변경 전 영향 분석 (기본 strong, --all로 weak 포함)\n  leerness reuse find <query>                # 기존 자원 검색 (재귀 안내)\n  leerness reuse register <name> --where <p> --kind component|hook|util|api [--note ...]\n  leerness ui consistency [path] [--strict] [--fail-on-violation]\n  leerness graph [path] [--out <file>]       # mermaid 의존성 그래프\n  leerness guide [target]                    # impact + reuse + ui consistency 통합 가이드\n  leerness migrate audit|apply|plan [path] [--json] [--yes]   # 크로스버전 마이그레이션 진단/적용(canonical 백필)/플랜(임시폴더 비교) (UR-0075, 1.9.356~358)\n  leerness migrate --guide                    # AI 에이전트용 크로스버전 마이그레이션 가이드 (1.9.355)\n  leerness install-safety [--json]            # 설치 안전 프로필 — 0 런타임 deps / 0 install-script (1.9.359)\n  leerness capabilities [--json]              # 권한·보안 표면 공개 (1.9.272)\n  leerness feature add|link|impact|list|show  # 기능 그래프(feature-graph) 추적\n  leerness permissions list|set               # agent 권한 모드 (1.9.174)\n  leerness creds list|register|check|refresh  # 크리덴셜 메타 추적 (값 미저장)\n  leerness incident list|show|handle · webhook serve · deploy auto · runs list|show   # 운영(ops)\n  leerness whats-new [path]                   # 최근 버전 변경 요약\n  leerness team list|add|show|remove|preview <id> [--name --purpose --personas a,b --members claude,codex --schedule every-session --task "..."]   # 에이전트 팀 정의 + preview(dry-run 실행계획) — UR-0073 Phase A/B, opt-in · 정의/미리보기 전용(자동실행 X)\n  leerness release channel|cadence [path] [--json]   # 릴리스 채널 정책 + 빈도 진단 (UR-0074 케이던스 가시화, 1.9.275/374)\n  leerness commands [--json]                  # 전체 명령 전수 목록 (누락 없이 이 명령으로 확인)\n`);
+  leerness release publish [--dry-run] [--pack] [--git-push] [--gh-release] [--gh-pages] [--gh-pages-src file] [--npm-publish] [--auto]  # 통합 배포 (1.9.8 + 1.9.10)\n  leerness impact <target> [--all]           # 변경 전 영향 분석 (기본 strong, --all로 weak 포함)\n  leerness reuse find <query>                # 기존 자원 검색 (재귀 안내)\n  leerness reuse register <name> --where <p> --kind component|hook|util|api [--note ...]\n  leerness ui consistency [path] [--strict] [--fail-on-violation]\n  leerness graph [path] [--out <file>]       # mermaid 의존성 그래프\n  leerness guide [target]                    # impact + reuse + ui consistency 통합 가이드\n  leerness migrate audit|apply|plan [path] [--json] [--yes]   # 크로스버전 마이그레이션 진단/적용(canonical 백필)/플랜(임시폴더 비교) (UR-0075, 1.9.356~358)\n  leerness migrate --guide                    # AI 에이전트용 크로스버전 마이그레이션 가이드 (1.9.355)\n  leerness install-safety [--json]            # 설치 안전 프로필 — 0 런타임 deps / 0 install-script (1.9.359)\n  leerness capabilities [--json]              # 권한·보안 표면 공개 (1.9.272)\n  leerness feature add|link|impact|list|show  # 기능 그래프(feature-graph) 추적\n  leerness permissions list|set               # agent 권한 모드 (1.9.174)\n  leerness creds list|register|check|refresh  # 크리덴셜 메타 추적 (값 미저장)\n  leerness incident list|show|handle · webhook serve · deploy auto · runs list|show   # 운영(ops)\n  leerness whats-new [path]                   # 최근 버전 변경 요약\n  leerness team list|add|show|remove|preview|deploy <id> [--personas a,b --members claude,codex --schedule every-session --task "..." --deploy "<배포명령>" --yes]   # 에이전트 팀 정의/미리보기/배포 — UR-0073 A~D, opt-in · 배포는 2중게이트(--yes + LEERNESS_TEAM_DEPLOY=1)\n  leerness release channel|cadence [path] [--json]   # 릴리스 채널 정책 + 빈도 진단 (UR-0074 케이던스 가시화, 1.9.275/374)\n  leerness commands [--json]                  # 전체 명령 전수 목록 (누락 없이 이 명령으로 확인)\n`);
 }
 
 async function main() {

package/lib/pure-utils.js

@@ -743,6 +743,7 @@ function _renderTeamsMd(teams) {
       + `- Personas: ${(t.personas || []).join(', ')}\n`
       + `- Members: ${(t.members || []).join(', ')}\n`
       + `- Schedule: ${t.schedule || 'manual'}\n`
+      + `- Deploy: ${t.deployCommand || '-'}\n`
       + `- Status: ${t.status || 'active'}\n`;
   }).join('');
   return preamble + body;
@@ -780,11 +781,85 @@ function _cadenceAssessment(perDay, total, daysActive) {
   return { releasesPerDay: r, total: Number(total) || 0, daysActive: Number(daysActive) || 0, level, recommendation };
 }
 
+// 1.9.376 (UR-0073 Phase D): team 배포 실행 게이트 결정 (순수). 안전: dry-run 기본, 실행은 --yes + env 이중 게이트.
+//   mode: no-command(설정 없음) / dry-run(실행 안 함) / gated(env 미충족 거부) / execute(실행 허용).
+function _teamDeployGate(team, opts) {
+  const t = team || {}; opts = opts || {};
+  const command = (t.deployCommand && t.deployCommand !== true) ? String(t.deployCommand) : '';
+  if (!command) return { mode: 'no-command', command: '', message: 'deployCommand 미설정 — team add --deploy "<명령>" 으로 지정' };
+  if (!opts.yes) return { mode: 'dry-run', command, message: 'dry-run (실행 없음) — 실행하려면 --yes + LEERNESS_TEAM_DEPLOY=1' };
+  if (!opts.envOn) return { mode: 'gated', command, message: '실행 게이트 미충족 — LEERNESS_TEAM_DEPLOY=1 환경변수 필요 (의도적 opt-in)' };
+  return { mode: 'execute', command, message: '실행 허용 (--yes + env 게이트 충족)' };
+}
+
+// 1.9.377 (UR-0025): 워크스페이스 레퍼런스 가이드 빌더 (순수) — dirName/version/generatedAt 주입. harness 인라인(~57줄) 분리.
+function _renderWorkspaceReferenceGuide(dirName, version, generatedAt) {
+  const lines = [];
+  lines.push(`# Leerness Workspace Reference Guide`);
+  lines.push('');
+  lines.push(`> AI 에이전트가 leerness 워크스페이스에서 어떤 파일을 어디서 찾는지 안내합니다 (1.9.211).`);
+  lines.push('');
+  lines.push(`Generated: ${generatedAt} by leerness ${version}`);
+  lines.push(`Workspace dir: \`${dirName}/\``);
+  lines.push('');
+  lines.push(`## 📁 디렉토리 구조 (핵심)`);
+  lines.push('');
+  lines.push('```');
+  lines.push(`${dirName}/`);
+  lines.push(`├── plan.md                    ← 무엇을 할 것인가 (사용자 메모리)`);
+  lines.push(`├── progress-tracker.md        ← 무엇을 했는가 (증거 포함, 사용자 메모리)`);
+  lines.push(`├── decisions.md               ← 왜 그렇게 했는가 (사용자 메모리)`);
+  lines.push(`├── session-handoff.md         ← 다음 세션 인계 (사용자 메모리)`);
+  lines.push(`├── lessons.md                 ← 과거 교훈 (자동 fuzzy 회수)`);
+  lines.push(`├── rules.md                   ← 자연어 룰 (매 세션 자동 노출, R-XXXX)`);
+  lines.push(`├── task-log.md                ← in-progress / dropped task 이력`);
+  lines.push(`├── reuse-map.md               ← 워크스페이스 capability 매핑`);
+  lines.push(`├── skill-suggestions.md       ← skill rolling history`);
+  lines.push(`├── feature-graph.md           ← 기능 의존 그래프 (F-XXXX)`);
+  lines.push(`├── manifest.json              ← 워크스페이스 메타`);
+  lines.push(`├── leerness-config.json       ← 비시크릿 LEERNESS_* 설정 (1.9.187, AI 가시)`);
+  lines.push(`├── user-requests.json         ← 사용자 명시 요청 누적 (1.9.207)`);
+  lines.push(`├── active-wakeups.json        ← ScheduleWakeup 상태 (1.9.205)`);
+  lines.push(`├── pre-wake-report.json       ← sleep 전 sub-agent audit (1.9.209)`);
+  lines.push(`├── wakeup-history.json        ← adaptive wakeup 이력 (1.9.210)`);
+  lines.push(`├── platform-constraints.json  ← API 제약 catalog (1.9.208)`);
+  lines.push(`├── auto-resume-plan.json      ← 다음 라운드 plan (1.9.203)`);
+  lines.push(`├── next-action-queue.json     ← 다음 next-action 큐 (1.9.201)`);
+  lines.push(`├── last-handoff.json          ← 마지막 handoff timestamp`);
+  lines.push(`├── environment.json           ← 환경 변동 추적 (1.9.145)`);
+  lines.push(`├── skills/                    ← 설치된 skill 디렉토리`);
+  lines.push(`└── templates/                 ← 워크스페이스 템플릿`);
+  lines.push('```');
+  lines.push('');
+  lines.push(`## 🧭 자주 묻는 위치`);
+  lines.push('');
+  lines.push(`| 찾는 것 | 위치 |`);
+  lines.push(`|---|---|`);
+  lines.push(`| 현재 진행 중인 task | \`${dirName}/progress-tracker.md\` (status: in-progress) |`);
+  lines.push(`| 사용자가 명시한 영구 룰 | \`${dirName}/rules.md\` (active R-XXXX) |`);
+  lines.push(`| 직전 sleep 전 audit 결과 | \`${dirName}/pre-wake-report.json\` (1.9.209) |`);
+  lines.push(`| 미답 사용자 요청 | \`${dirName}/user-requests.json\` (status: open) |`);
+  lines.push(`| 다음 라운드 권장 단계 | \`${dirName}/auto-resume-plan.json\` (1.9.203) |`);
+  lines.push(`| API 제약 catalog | \`${dirName}/platform-constraints.json\` (1.9.208) |`);
+  lines.push(`| 자동 wakeup 권장 간격 | \`${dirName}/wakeup-history.json\` (1.9.210) |`);
+  lines.push('');
+  lines.push(`## 🔄 마이그레이션 안내`);
+  lines.push('');
+  lines.push(`이 워크스페이스는 \`.harness\` → \`.leerness\` 로 마이그레이션되었을 수 있습니다.`);
+  lines.push(`- \`.leerness/MIGRATED_FROM_HARNESS\` 존재 → 마이그레이션 완료, \`.leerness\` 우선 사용`);
+  lines.push(`- \`.harness/MIGRATED_TO_LEERNESS.md\` 존재 → \`.leerness/\` 로 가야 함`);
+  lines.push(`- 양쪽 모두 없음 → 기본 \`.harness\` 사용 중`);
+  lines.push('');
+  lines.push(`AI 에이전트는 \`leerness handoff .\` 결과를 신뢰하십시오 — 자동으로 올바른 디렉토리를 사용합니다.`);
+  lines.push('');
+  return lines.join('\n');
+}
+
 module.exports = {
   _isSecretKey, compareVer, parseHarnessVersion,
   _isPlaceholderSecret, _looksSecretLike,
   _mergeLines, _mergeEnvLines, _mergeReadmeSection, _managedMerge, _parseSkillsValue,
-  _parseArchiveBlocks, _parseSkillCatalog, _renderTeamsMd, _composeTeamPlan, _teamHandoffReminders, _cadenceAssessment,
+  _parseArchiveBlocks, _parseSkillCatalog, _renderTeamsMd, _composeTeamPlan, _teamHandoffReminders, _cadenceAssessment, _teamDeployGate, _renderWorkspaceReferenceGuide,
   _classifyCJK, _riskLabel, _detectSystemLang, _parseSlashFromHelp,
   // 1.9.283 (UR-0025 2단계)
   PERMISSION_TIERS, _tierRank, _requiredTier, _policyAllows, _resolveNpmTag, _mcpJsonContent, _newRunRecord,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leerness",
-  "version": "1.9.375",
+  "version": "1.9.377",
   "description": "Leerness: 비파괴 마이그레이션, 자동 버전 감지·업데이트, 계획/진행/핸드오프 자동화, 게으름·시크릿·인코딩 자동 가드, Claude Code 슬래시 통합을 갖춘 한국어 우선 AI 개발 하네스.",
   "keywords": [
     "leerness",

package/scripts/e2e.js

@@ -5170,5 +5170,44 @@ total++;
   if (!ok) failed++;
 }
 
+// 1.9.376 회귀 (UR-0073 Phase D): team deploy 2중 게이트 — dry-run 실행안함 · --yes만이면 거부 · --yes+env 만 실행
+total++;
+{
+  let ok = false;
+  try {
+    const d = fs.mkdtempSync(path.join(os.tmpdir(), 'leerness-tdep-'));
+    cp.spawnSync(process.execPath, [CLI, 'init', d, '--yes', '--language', 'ko'], { encoding: 'utf8', timeout: 30000 });
+    const marker = path.join(d, 'DEPLOYED.txt');
+    cp.spawnSync(process.execPath, [CLI, 'team', 'add', 'dep', '--members', 'claude', '--deploy', 'node -e "require(\'fs\').writeFileSync(\'DEPLOYED.txt\',\'ok\')"', '--path', d], { encoding: 'utf8', timeout: 15000 });
+    // 1) dry-run (no --yes) → 실행 안 함
+    cp.spawnSync(process.execPath, [CLI, 'team', 'deploy', 'dep', '--path', d], { encoding: 'utf8', timeout: 15000 });
+    const dryNoExec = !fs.existsSync(marker);
+    // 2) --yes 인데 env 없음 → 거부 (실행 안 함)
+    cp.spawnSync(process.execPath, [CLI, 'team', 'deploy', 'dep', '--yes', '--path', d], { encoding: 'utf8', timeout: 15000 });
+    const gateRefuse = !fs.existsSync(marker);
+    // 3) --yes + LEERNESS_TEAM_DEPLOY=1 → 실행 (marker 생성)
+    cp.spawnSync(process.execPath, [CLI, 'team', 'deploy', 'dep', '--yes', '--path', d], { cwd: d, encoding: 'utf8', timeout: 20000, env: { ...process.env, LEERNESS_TEAM_DEPLOY: '1' } });
+    const executed = fs.existsSync(marker);
+    fs.rmSync(d, { recursive: true, force: true });
+    ok = dryNoExec && gateRefuse && executed;
+  } catch {}
+  console.log(ok ? '✓ B(1.9.376) UR-0073 Phase D: team deploy 2중 게이트 (dry-run 실행X / env거부 / --yes+env 실행)' : '✗ team deploy 게이트 실패');
+  if (!ok) failed++;
+}
+
+// 1.9.377 회귀 (UR-0025): _renderWorkspaceReferenceGuide 모듈 분리 — 빌더가 dirName/version 반영 + 핵심 섹션 포함 (출력 동일성)
+total++;
+{
+  let ok = false;
+  try {
+    const pu = require(path.resolve(__dirname, '..', 'lib', 'pure-utils'));
+    const g = pu._renderWorkspaceReferenceGuide('.harness', '1.2.3', '2026-01-01T00:00:00.000Z');
+    ok = typeof g === 'string' && g.includes('.harness/progress-tracker.md') && g.includes('by leerness 1.2.3')
+      && g.includes('## 📁 디렉토리 구조 (핵심)') && g.includes('## 🧭 자주 묻는 위치') && g.includes('## 🔄 마이그레이션 안내') && g.includes('plan.md');
+  } catch {}
+  console.log(ok ? '✓ B(1.9.377) UR-0025: _renderWorkspaceReferenceGuide 모듈 분리 (빌더 동작 + 핵심 섹션)' : '✗ workspace guide 빌더 실패');
+  if (!ok) failed++;
+}
+
 console.log(`\nE2E result: ${total - failed}/${total} passed · ${((Date.now() - _e2eStart) / 1000).toFixed(0)}s`);
 if (failed > 0) process.exit(1);