therookie 0.4.37 → 0.4.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "therookie",
-  "version": "0.4.37",
+  "version": "0.4.38",
   "description": "Persistent memory for Claude Code and Codex CLI — teach your AI once and it remembers across sessions, tools, and machines. The AI new hire that remembers what you teach it.",
   "license": "MIT",
   "keywords": [

package/src/cli.js

@@ -18,9 +18,9 @@ import { runOrphanExtract } from './commands/orphan-extract.js'
 const HELP = `rookie — the Rookie Skill/Hook 설치 관리자
 
 사용:
-  rookie init [--local] [--force] [--yes] [--deep-scan]
-  rookie login [--local]
-  rookie update [--force]
+  rookie init [--local] [--force] [--yes] [--deep-scan] [--claude-md | --no-claude-md]
+  rookie login [--local] [--claude-md | --no-claude-md]
+  rookie update [--force] [--claude-md | --no-claude-md]
   rookie link [--local]
   rookie save [--file <body.json>] [--json]   # 또는 stdin. --json = 서버 raw 응답 출력
   rookie status
@@ -38,6 +38,8 @@ const HELP = `rookie — the Rookie Skill/Hook 설치 관리자
   --force       경고 무시, 재설치/덮어쓰기
   --yes         비대화형 자동 승인
   --deep-scan   홈 디렉토리에서 로컬 Skill 전수 스캔
+  --claude-md   글로벌 ~/.claude/CLAUDE.md 에 더루키 관리 블록을 넣는다(심링크·이미 같은 규칙이 있어도, update 에서도)
+  --no-claude-md  글로벌 CLAUDE.md 를 건드리지 않는다 (환경 변수 ROOKIE_NO_CLAUDE_MD=1 과 같다)
 
 명령:
   init             첫 설치. 비밀번호 입력 받아 PAT 발급 + Skill/Hook 배포.

package/src/commands/doctor.js

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { claudeMdStatusLine } from '../lib/claude-md-block.js'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { execSync } from 'node:child_process'
@@ -42,6 +43,8 @@ export async function runDoctor(flags) {
   const lSettings = join(process.cwd(), '.claude', 'settings.json')
   console.log(hasRookieHook(gSettings) ? '✓ 글로벌 hook 등록됨' : '✗ 글로벌 hook 없음')
   console.log(hasRookieHook(lSettings) ? '✓ 로컬 hook 등록됨' : '  로컬 hook 없음')
+  const claudeMdLine = claudeMdStatusLine()
+  if (claudeMdLine) console.log(claudeMdLine)
 
   if (g && l && g.version !== l.version) {
     console.log(`⚠ 버전 불일치: 글로벌 v${g.version} vs 로컬 v${l.version}`)

package/src/commands/init.js

@@ -12,6 +12,7 @@ import { apiGet, apiPostNoAuth } from '../api.js'
 import { applyToolSetup, pendingToolSetup } from '../lib/apply-tool-setup.js'
 import { renderDetected, renderConnectOutcome, toolName } from '../lib/connect-ui.js'
 import { resolveEndpoint } from '../lib/resolve-endpoint.js'
+import { runClaudeMdStep } from '../lib/claude-md-block.js'
 
 async function pickChoice(prompt, options, autoValue) {
   console.log(prompt)
@@ -172,4 +173,10 @@ export async function runInit(flags) {
     confirmWeak: (t) => confirm(`${toolName(t.id)} 디렉토리만 감지됨(CLI 미확인). 연결할까요?`, { defaultYes: true }),
   })
   for (const line of renderConnectOutcome(report, tools)) console.log(line)
+
+  // spec 2026-09-29 — 글로벌 CLAUDE.md 에 "더루키 먼저" 관리 블록(글로벌 설치·Claude 적용 시만).
+  if (scope === 'global' && report.applied.some((a) => a.id === 'claude')) {
+    const { lines } = await runClaudeMdStep({ mode: 'connect', flags, interactive, confirmFn: confirm })
+    for (const line of lines) console.log(line)
+  }
 }

package/src/commands/login.js

@@ -10,6 +10,7 @@ import { renderDetected, renderConnectOutcome, toolName } from '../lib/connect-u
 import { confirm } from '../prompt.js'
 import { resolveEndpoint } from '../lib/resolve-endpoint.js'
 import { accountLine, accountWarning } from '../lib/account-ui.js'
+import { runClaudeMdStep } from '../lib/claude-md-block.js'
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms))
 
@@ -157,4 +158,16 @@ export async function runLogin(flags) {
     confirmWeak: (t) => confirm(`${toolName(t.id)} 디렉토리만 감지됨(CLI 미확인). 연결할까요?`, { defaultYes: true }),
   })
   for (const line of renderConnectOutcome(report, tools, cfg.agent_name)) console.log(line)
+
+  // spec 2026-09-29 — 글로벌 CLAUDE.md 에 "더루키 먼저" 관리 블록. install.sh 의 비대화 login 도
+  //  여기를 지난다 — 처음 연결은 사용자가 설치를 고른 순간이라 기본 적용(끄기: ROOKIE_NO_CLAUDE_MD=1).
+  if (scope === 'global' && report.applied.some((a) => a.id === 'claude')) {
+    const { lines } = await runClaudeMdStep({
+      mode: 'connect',
+      flags,
+      interactive: !!process.stdin.isTTY && !flags.yes,
+      confirmFn: confirm,
+    })
+    for (const line of lines) console.log(line)
+  }
 }

package/src/commands/update.js

@@ -13,6 +13,8 @@ import { semverGt, fetchReleaseManifest, selfUpdateAndRerun, isNpmManagedInstall
 import { installSkill } from '../lib/skill-installer.js'
 import { claudeHookCommand, escapeJsonStringValue } from '../lib/hook-command.js'
 import { mergeHooks } from '../lib/merge-hooks.js'
+import { runClaudeMdStep } from '../lib/claude-md-block.js'
+import { confirm } from '../prompt.js'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -52,6 +54,19 @@ export async function runUpdate(flags) {
     }
   }
 
+  // spec 2026-09-29 — 글로벌 CLAUDE.md 더루키 블록 점검. 서버를 부르지 않는 로컬 단계라
+  //  manifest "최신" 조기 종료·서버 실패보다 앞에 둔다. 표식이 있으면 갱신, 없으면 대화형 확인 또는
+  //  --claude-md 일 때만 붙인다 — update 는 모델이 비대화로 돌리는 경로가 있다.
+  {
+    const { lines } = await runClaudeMdStep({
+      mode: 'update',
+      flags,
+      interactive: !!process.stdin.isTTY && !flags.yes,
+      confirmFn: confirm,
+    })
+    for (const line of lines) console.log(line)
+  }
+
   let serverManifest
   try {
     const status = await apiGet(cfg.endpoint, cfg.token, '/api/rookie/status')

package/src/lib/claude-md-block.js

@@ -0,0 +1,243 @@
+// 글로벌 ~/.claude/CLAUDE.md 에 "더루키 먼저" 관리 블록을 넣고 갱신한다.
+// spec docs/superpowers/specs/2026-09-29-claude-md-rookie-block.md
+//
+// 표식(<!-- rookie:begin vN --> … <!-- rookie:end -->) 사이만 관리하고 밖은 바이트 그대로 둔다.
+// 심링크는 끊지 않는다 — 실제 대상 파일(realpath)에 쓴다.
+import {
+  existsSync,
+  lstatSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+  writeFileSync,
+  renameSync,
+  copyFileSync,
+  chmodSync,
+  unlinkSync,
+} from 'node:fs'
+import { homedir } from 'node:os'
+import { join, dirname, basename } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+export const DEFAULT_TEMPLATE_PATH = join(__dirname, '..', '..', 'templates', 'claude-md', 'rookie-block.md')
+
+const BEGIN_RE = /<!-- rookie:begin v(\d+) -->/g
+const END_MARK = '<!-- rookie:end -->'
+// 더루키에만 있는 경로라 "같은 취지 규칙이 이미 있다" 판정에 쓴다(spec §3.1).
+export const SAME_INTENT_NEEDLE = '/api/rookie/recall'
+
+export function readTemplateBlock(templatePath = DEFAULT_TEMPLATE_PATH) {
+  const raw = readFileSync(templatePath, 'utf8')
+  const parsed = parseRookieBlock(raw)
+  if (parsed.state !== 'ok') throw new Error(`rookie-block 템플릿 표식 이상: ${parsed.state}`)
+  return { version: parsed.version, text: raw.slice(parsed.start, parsed.end) }
+}
+
+// { state: 'none' } | { state: 'malformed' } | { state: 'ok', version, start, end, text }
+//  start/end 는 begin 표식 첫 글자 ~ end 표식 마지막 글자 다음 위치.
+export function parseRookieBlock(content) {
+  const begins = [...content.matchAll(BEGIN_RE)]
+  const endCount = content.split(END_MARK).length - 1
+  if (begins.length === 0 && endCount === 0) return { state: 'none' }
+  if (begins.length !== 1 || endCount !== 1) return { state: 'malformed' }
+  const start = begins[0].index
+  const endIdx = content.indexOf(END_MARK)
+  if (endIdx < start) return { state: 'malformed' }
+  const end = endIdx + END_MARK.length
+  return { state: 'ok', version: Number(begins[0][1]), start, end, text: content.slice(start, end) }
+}
+
+// 순수 함수. 블록 밖 바이트는 그대로 둔다(append 도 기존 내용 뒤에 붙이기만 한다).
+export function upsertRookieBlock(content, blockText) {
+  const p = parseRookieBlock(content)
+  if (p.state === 'malformed') throw Object.assign(new Error('rookie 블록 표식 손상'), { code: 'MALFORMED_ROOKIE_BLOCK' })
+  if (p.state === 'ok') return content.slice(0, p.start) + blockText + content.slice(p.end)
+  if (content.length === 0) return blockText + '\n'
+  const sep = content.endsWith('\n') ? '\n' : '\n\n'
+  return content + sep + blockText + '\n'
+}
+
+// 무엇을 할지 정한다(쓰지 않는다). force = --claude-md.
+//  action: create | append | replace | noop | noop_edited | skip_same_intent |
+//          skip_symlink_unmanaged | skip_broken_symlink | skip_newer | malformed | no_claude_dir
+export function planClaudeMd({ home = homedir(), force = false, template } = {}) {
+  const tpl = template ?? readTemplateBlock()
+  const claudeDir = join(home, '.claude')
+  const path = join(claudeDir, 'CLAUDE.md')
+  const base = { path, target: path, isSymlink: false, template: tpl }
+  if (!existsSync(claudeDir)) return { ...base, action: 'no_claude_dir' }
+
+  let lst = null
+  try { lst = lstatSync(path) } catch { lst = null }
+  if (!lst) return { ...base, action: 'create' }
+
+  let target = path
+  const isSymlink = lst.isSymbolicLink()
+  if (isSymlink) {
+    try { target = realpathSync(path) } catch { return { ...base, isSymlink, action: 'skip_broken_symlink' } }
+  }
+  const content = readFileSync(target, 'utf8')
+  const p = parseRookieBlock(content)
+  const ctx = { ...base, target, isSymlink, content, existing: p }
+
+  if (p.state === 'malformed') return { ...ctx, action: 'malformed' }
+  if (p.state === 'ok') {
+    if (p.version > tpl.version) return { ...ctx, action: 'skip_newer' }
+    if (p.version < tpl.version) return { ...ctx, action: 'replace' }
+    if (p.text === tpl.text) return { ...ctx, action: 'noop' }
+    return { ...ctx, action: force ? 'replace' : 'noop_edited' }
+  }
+  // 표식 없음
+  if (isSymlink && !force) return { ...ctx, action: 'skip_symlink_unmanaged' }
+  if (content.includes(SAME_INTENT_NEEDLE) && !force) return { ...ctx, action: 'skip_same_intent' }
+  return { ...ctx, action: 'append' }
+}
+
+export const WRITING_ACTIONS = new Set(['create', 'append', 'replace'])
+
+// plan 대로 쓴다. 대상 파일 폴더에 임시 파일을 만들고 rename — 심링크 경로 자체는 건드리지 않는다.
+export function applyClaudeMd(plan) {
+  if (!WRITING_ACTIONS.has(plan.action)) return { written: false, action: plan.action }
+  const target = plan.target
+  const before = plan.action === 'create' ? '' : plan.content
+  const next = upsertRookieBlock(before, plan.template.text)
+  if (next === before) return { written: false, action: 'noop' }
+
+  let mode = null
+  if (plan.action !== 'create') {
+    mode = statSync(target).mode & 0o777
+    copyFileSync(target, join(dirname(target), `${basename(target)}.rookie-bak`))
+  }
+  const tmp = join(dirname(target), `.${basename(target)}.rookie-tmp-${process.pid}`)
+  try {
+    writeFileSync(tmp, next)
+    if (mode !== null) chmodSync(tmp, mode)
+    renameSync(tmp, target)
+  } catch (e) {
+    try { unlinkSync(tmp) } catch { /* 임시 파일이 없으면 그만 */ }
+    throw e
+  }
+  return { written: true, action: plan.action, target, backup: mode !== null ? `${target}.rookie-bak` : null }
+}
+
+// 명령(init·login·update)이 공유하는 한 단계. 출력 줄 목록을 돌려준다(테스트 가능하게).
+//  mode 'connect'(login·init): 기본 적용. 'update': 표식이 있을 때만 갱신, 없으면 대화형 확인 또는 --claude-md.
+export async function runClaudeMdStep({
+  mode,
+  flags = {},
+  env = process.env,
+  interactive = false,
+  confirmFn = async () => false,
+  home = homedir(),
+  template,
+} = {}) {
+  const lines = []
+  if (flags['no-claude-md'] || env.ROOKIE_NO_CLAUDE_MD === '1') return { lines, result: { written: false, action: 'opted_out' } }
+
+  const force = !!flags['claude-md']
+  let plan
+  try {
+    plan = planClaudeMd({ home, force, template })
+  } catch (e) {
+    lines.push(`⚠ 글로벌 CLAUDE.md 점검 실패: ${e.message}`)
+    return { lines, result: { written: false, action: 'error' } }
+  }
+  const where = plan.isSymlink ? `${plan.path} → ${plan.target}` : plan.path
+
+  switch (plan.action) {
+    case 'no_claude_dir':
+    case 'noop':
+      return { lines, result: { written: false, action: plan.action } }
+    case 'noop_edited':
+      lines.push(`  글로벌 CLAUDE.md 의 더루키 블록이 수정돼 있어 그대로 둡니다 — 템플릿으로 되돌리려면 rookie update --claude-md`)
+      return { lines, result: { written: false, action: plan.action } }
+    case 'skip_same_intent':
+      lines.push(`  글로벌 CLAUDE.md 에 더루키 회상 규칙이 이미 있어 블록을 넣지 않았습니다 — 관리 블록으로 두려면 --claude-md`)
+      return { lines, result: { written: false, action: plan.action } }
+    case 'skip_symlink_unmanaged':
+      lines.push(`  글로벌 CLAUDE.md 가 심링크라 블록을 넣지 않았습니다(${where}) — 넣으려면 --claude-md`)
+      return { lines, result: { written: false, action: plan.action } }
+    case 'skip_broken_symlink':
+      lines.push(`⚠ 글로벌 CLAUDE.md 심링크의 대상이 없습니다(${plan.path}) — 건드리지 않았습니다`)
+      return { lines, result: { written: false, action: plan.action } }
+    case 'skip_newer':
+      lines.push(`  글로벌 CLAUDE.md 의 더루키 블록(v${plan.existing.version})이 이 CLI(v${plan.template.version})보다 새 버전이라 그대로 둡니다`)
+      return { lines, result: { written: false, action: plan.action } }
+    case 'malformed':
+      lines.push(`⚠ 글로벌 CLAUDE.md 의 더루키 블록 표식이 손상돼 건드리지 않았습니다 — 수동 점검: ${plan.target}`)
+      return { lines, result: { written: false, action: plan.action } }
+    default:
+      break
+  }
+
+  // 여기부터 create·append·replace
+  const isNewBlock = plan.action === 'create' || plan.action === 'append'
+  if (mode === 'update' && isNewBlock && !force) {
+    if (!interactive) {
+      lines.push(`  글로벌 CLAUDE.md 에 더루키 블록이 없습니다 — 넣으려면 rookie update --claude-md (rookie doctor 로 확인)`)
+      return { lines, result: { written: false, action: 'needs_consent' } }
+    }
+    console.log(describePlan(plan))
+    if (!(await confirmFn('글로벌 CLAUDE.md 에 이 블록을 넣을까요?', { defaultYes: false }))) {
+      lines.push('  글로벌 CLAUDE.md 블록 추가를 건너뛰었습니다')
+      return { lines, result: { written: false, action: 'declined' } }
+    }
+  } else if (mode === 'connect' && isNewBlock && interactive) {
+    console.log(describePlan(plan))
+    if (!(await confirmFn('글로벌 CLAUDE.md 에 이 블록을 넣을까요?', { defaultYes: true }))) {
+      lines.push('  글로벌 CLAUDE.md 블록 추가를 건너뛰었습니다 (나중에: rookie update --claude-md)')
+      return { lines, result: { written: false, action: 'declined' } }
+    }
+  }
+
+  let result
+  try {
+    result = applyClaudeMd(plan)
+  } catch (e) {
+    lines.push(`⚠ 글로벌 CLAUDE.md 쓰기 실패(원본 보존): ${e.message}`)
+    return { lines, result: { written: false, action: 'error' } }
+  }
+  if (result.written) {
+    const verb = plan.action === 'replace' ? `갱신(v${plan.existing.version} → v${plan.template.version})` : `추가(v${plan.template.version})`
+    lines.push(`✓ 글로벌 CLAUDE.md 더루키 블록 ${verb}: ${where}`)
+    if (result.backup) lines.push(`  · 이전 본문 backup → ${result.backup}`)
+    if (mode === 'connect' && !interactive && isNewBlock) lines.push('  (넣지 않으려면 표식 사이를 지우고 ROOKIE_NO_CLAUDE_MD=1 로 두세요)')
+  }
+  return { lines, result }
+}
+
+// 쓰기 전에 보여 줄 설명.
+export function describePlan(plan) {
+  const where = plan.isSymlink ? `${plan.path} → ${plan.target}` : plan.path
+  const what = plan.action === 'create' ? '새 파일로 만들고' : plan.action === 'append' ? '파일 끝에' : '기존 블록을 바꿔'
+  return [
+    `\n글로벌 CLAUDE.md 에 더루키 관리 블록을 둡니다 — ${where}`,
+    `  ${what} 아래 블록을 넣습니다(표식 밖의 글은 건드리지 않습니다):`,
+    ...plan.template.text.split('\n').map((l) => `  | ${l}`),
+  ].join('\n')
+}
+
+// doctor 용 한 줄(읽기만).
+export function claudeMdStatusLine({ home = homedir(), template } = {}) {
+  let plan
+  try { plan = planClaudeMd({ home, force: false, template }) } catch (e) { return `⚠ 글로벌 CLAUDE.md 점검 실패: ${e.message}` }
+  const v = plan.template.version
+  switch (plan.action) {
+    case 'no_claude_dir': return null
+    case 'noop': return `✓ 글로벌 CLAUDE.md 더루키 블록 v${v}`
+    case 'replace': return `⚠ 글로벌 CLAUDE.md 더루키 블록 v${plan.existing.version} → v${v} — rookie update`
+    case 'noop_edited': return '⚠ 글로벌 CLAUDE.md 더루키 블록이 수정됨 — 되돌리려면 rookie update --claude-md'
+    case 'skip_newer': return `✓ 글로벌 CLAUDE.md 더루키 블록 v${plan.existing.version} (이 CLI 보다 새 버전)`
+    case 'skip_same_intent': return '✓ 글로벌 CLAUDE.md 에 더루키 회상 규칙 있음(관리 블록 아님)'
+    case 'skip_symlink_unmanaged':
+      return plan.content.includes(SAME_INTENT_NEEDLE)
+        ? '✓ 글로벌 CLAUDE.md(심링크)에 더루키 회상 규칙 있음(관리 블록 아님)'
+        : '⚠ 글로벌 CLAUDE.md(심링크)에 더루키 블록 없음 — rookie update --claude-md'
+    case 'skip_broken_symlink': return `⚠ 글로벌 CLAUDE.md 심링크 대상 없음 — ${plan.path}`
+    case 'malformed': return `✗ 글로벌 CLAUDE.md 더루키 블록 손상(begin/end 불일치) — 수동 점검: ${plan.target}`
+    case 'create': return '⚠ 글로벌 CLAUDE.md 없음 — rookie update --claude-md'
+    case 'append': return '⚠ 글로벌 CLAUDE.md 에 더루키 블록 없음 — rookie update --claude-md'
+    default: return null
+  }
+}

package/templates/claude-md/rookie-block.md

@@ -0,0 +1,7 @@
+<!-- rookie:begin v1 -->
+## 더루키(the Rookie) 기억 — 로컬보다 먼저
+- 전에 한 일·결정·맥락이 필요하면(어제·전에·이어서 같은 말이 없어도) 로컬 md·auto-memory 를 뒤지기 **전에** 더루키 회상(`GET /api/rookie/recall`)을 먼저 부른다. 로컬 파일은 보조다.
+- 새로 기억할 것(운영 사실·결정·규칙·취향)은 **더루키에 먼저** 저장하고(`rookie save`), 로컬 md 는 필요할 때만 보조로 남긴다.
+- 예외: 작업 폴더에 `.rookie-ignore` 가 있거나, `ROOKIE_DISABLED=1` 이거나, `~/.rookie/config.json` 이 없으면 위 두 줄을 따르지 않는다.
+- 세부 절차는 rookie Skill 과 세션 시작 주입이 정본이다 — 여기에 옮겨 적지 않는다.
+<!-- rookie:end -->

package/version.json

@@ -1,4 +1,4 @@
 {
-  "cli_version": "0.4.37",
+  "cli_version": "0.4.38",
   "skill_version": "1.40.1"
 }