@rch4com/agent-setup 1.0.0 → 1.1.0

package/lib/bootstrap/apply.mjs

@@ -4,6 +4,9 @@ import { lstatSync, mkdirSync, writeFileSync, readFileSync, appendFileSync } fro
 import { dirname } from 'node:path'
 import { repoPath, repoPathStrict } from '../context.mjs'
 import { ensureGitignoreEntries } from '../gitignore.mjs'
+import { hashBody, normalizeBody } from './text.mjs'
+import { BEGIN_MARKER, END_MARKER, extractBlock, managedKey } from './record.mjs'
+import { configureAdapter } from './adapter.mjs'
 
 // existsSync는 깨진 심볼릭 링크에 false를 반환한다. 그대로 쓰면 사용자가 만든
 // 링크를 덮어쓰게 되므로 lstat으로 "항목이 있는가"를 본다.
@@ -16,12 +19,9 @@ export function pathExists(target) {
   }
 }
 
-// 두 OS가 같은 파일을 만들도록 항상 LF + 끝 개행 1개로 정규화한다.
-// writeText(새 파일)와 ensureBlocks의 덧붙이기(기존 파일) 양쪽에서 쓴다 —
-// 덧붙이기도 이 정규화를 거치지 않으면 CRLF가 LF 파일에 새어 들어간다.
-function normalizeBody(text) {
-  return text.replace(/\r\n/g, '\n').trim() + '\n'
-}
+// normalizeBody는 text.mjs가 단일 출처다 — writeText(새 파일)와 ensureBlocks의
+// 덧붙이기(기존 파일)가 쓰는 정규화와 해시 판정이 갈리면, 갓 쓴 파일조차
+// 드리프트로 보고된다.
 
 function writeText(file, text) {
   const body = normalizeBody(text)
@@ -57,8 +57,6 @@ export function ensureFiles(root, files, { dryRun = false, log }) {
   })
 }
 
-const BEGIN_MARKER = '<!-- agent-kit:begin -->'
-
 export function ensureBlocks(root, blocks, { dryRun = false, log }) {
   return blocks.map(({ path: rel, block }) => {
     // 존재 확인은 어휘적 경로로 한다 — 만들지 않을 것이면 지켜야 할 쓰기도 없다.
@@ -267,3 +265,115 @@ export function ensureJsonKeys(root, entries, { dryRun = false, log }) {
     return { ok: true, action: 'insert', path: rel }
   })
 }
+
+// flow.mjs와 update.mjs가 같은 실패 격리를 쓴다 — 어댑터 하나가 실패해도
+// 나머지를 계속해야 한다.
+export function configureAdapterSafe(root, entry, ctx) {
+  try {
+    return configureAdapter(root, entry, ctx)
+  } catch (err) {
+    return { ok: false, action: 'link', path: entry.path, message: err.message }
+  }
+}
+
+// 갱신 경로. 생성 경로(ensureFiles·ensureBlocks)와 분리한 이유는 계약이
+// 반대이기 때문이다 — 생성은 "있으면 손대지 않는다", 갱신은 "우리가 쓴
+// 그대로면 바꾼다". 한 함수에 두 계약을 넣으면 어느 쪽도 읽히지 않는다.
+//
+// managed[key]가 우리가 마지막으로 쓴 내용의 해시다.
+//   현재 == managed  → 우리가 쓴 그대로 → 교체
+//   현재 != managed  → 사용자가 고쳤다 → 건드리지 않는다(force면 교체)
+//   managed 없음/null → 출처 불명 → 건드리지 않는다(force면 교체)
+//   파일 없음         → 생성 (새 도구 지원이 이 경로로 들어온다)
+function decide(current, recorded, force) {
+  if (current === null) return 'create'
+  if (recorded && hashBody(current) === recorded) return 'update'
+  return force ? 'update' : 'drift'
+}
+
+function readOrNull(target) {
+  try {
+    return readFileSync(target, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+export function updateFiles(root, files, { managed = {}, dryRun = false, force = false, log }) {
+  return files.map(({ path: rel, template }) => {
+    const lexical = repoPath(root, rel)
+    const exists = pathExists(lexical)
+    const current = exists ? readOrNull(lexical) : null
+    if (exists && current === null) {
+      log(`경고: ${rel}을 읽을 수 없어 건너뜁니다`)
+      return { ok: true, action: 'warn', path: rel, message: '읽기 실패' }
+    }
+
+    const wanted = hashBody(template)
+    // 이미 새 템플릿과 같으면 쓰지 않는다 — 무의미한 mtime 변경과
+    // "갱신 N건" 과대 보고를 막는다.
+    if (current !== null && hashBody(current) === wanted) {
+      return { ok: true, action: 'skip', path: rel, hash: wanted }
+    }
+
+    const verdict = decide(current, managed[rel], force)
+    if (verdict === 'drift') {
+      log(`사용자 수정 — 건드리지 않음: ${rel}`)
+      return { ok: true, action: 'drift', path: rel }
+    }
+
+    // 검사가 던지면 하지 않은 동작을 보고하지 않도록 로그보다 먼저 수행한다.
+    const target = repoPathStrict(root, rel)
+    log(verdict === 'create' ? `파일 생성: ${rel}` : `파일 갱신: ${rel}`)
+    if (!dryRun) writeText(target, template)
+    return { ok: true, action: verdict, path: rel, hash: wanted }
+  })
+}
+
+export function updateBlocks(root, blocks, { managed = {}, dryRun = false, force = false, log }) {
+  return blocks.map(({ path: rel, block }) => {
+    const key = managedKey(rel, true)
+    const wanted = hashBody(extractBlock(block) ?? block)
+
+    if (!pathExists(repoPath(root, rel))) {
+      const target = repoPathStrict(root, rel)
+      log(`파일 생성: ${rel}`)
+      if (!dryRun) writeText(target, block)
+      return { ok: true, action: 'create', path: rel, hash: wanted }
+    }
+
+    const text = readOrNull(repoPath(root, rel))
+    if (text === null) {
+      log(`경고: ${rel}을 읽을 수 없어 건너뜁니다`)
+      return { ok: true, action: 'warn', path: rel, message: '읽기 실패' }
+    }
+
+    const current = extractBlock(text)
+    // 마커가 없는 기존 파일은 갱신 대상이 아니다. 블록을 처음 붙이는 것은
+    // 생성 경로(ensureBlocks)의 일이고, 갱신이 append까지 하면 사용자가
+    // 일부러 지운 블록을 되살리게 된다.
+    if (current === null) {
+      log(`관리 블록 없음 — 건드리지 않음: ${rel}`)
+      return { ok: true, action: 'drift', path: rel, message: '관리 블록 없음' }
+    }
+
+    if (hashBody(current) === wanted) return { ok: true, action: 'skip', path: rel, hash: wanted }
+
+    if (hashBody(current) !== managed[key] && !force) {
+      log(`블록 사용자 수정 — 건드리지 않음: ${rel}`)
+      return { ok: true, action: 'drift', path: rel }
+    }
+
+    const target = repoPathStrict(root, rel)
+    log(`관리 블록 갱신: ${rel}`)
+    if (!dryRun) {
+      // 마커를 포함한 구간을 통째로 새 블록으로 바꾼다. 앞뒤 사용자 본문은
+      // 손대지 않으므로 줄바꿈 스타일도 그대로 남는다.
+      const begin = text.indexOf(BEGIN_MARKER)
+      const end = text.indexOf(END_MARKER, begin) + END_MARKER.length
+      const next = text.slice(0, begin) + normalizeBody(block).trimEnd() + text.slice(end)
+      writeFileSync(target, next, { encoding: 'utf8' })
+    }
+    return { ok: true, action: 'update', path: rel, hash: wanted }
+  })
+}

package/lib/bootstrap/flow.mjs

@@ -1,13 +1,15 @@
 // 부트스트랩 진입점 — 순서와 보고만 담당한다.
 // 무엇을 만들지는 manifest.mjs가, 어떻게 만들지는 apply.mjs·adapter.mjs가 안다.
 import { MANIFEST } from './manifest.mjs'
-import { ensureBlocks, ensureDirs, ensureFiles, ensureIgnore, ensureJsonKeys } from './apply.mjs'
-import { configureAdapter } from './adapter.mjs'
+import {
+  configureAdapterSafe, ensureBlocks, ensureDirs, ensureFiles, ensureIgnore, ensureJsonKeys,
+} from './apply.mjs'
+import { RECORD_REL, collectManaged, emptyRecord, readRecord, writeRecord } from './record.mjs'
 
 const SKILL_MODES = ['auto', 'link', 'copy']
 
 export function runBootstrap(root, opts = {}) {
-  const { dryRun = false, skillMode = 'auto', log = console.log, manifest = MANIFEST } = opts
+  const { dryRun = false, skillMode = 'auto', adopt = false, log = console.log, manifest = MANIFEST } = opts
 
   if (!SKILL_MODES.includes(skillMode)) {
     throw new Error(`--skill-mode는 ${SKILL_MODES.join(', ')} 중 하나여야 합니다: ${skillMode}`)
@@ -19,23 +21,36 @@ export function runBootstrap(root, opts = {}) {
   say(`저장소 루트: ${root}`)
   say('글로벌 설정 경로는 읽거나 수정하지 않습니다.')
 
-  const results = [
+  // --adopt는 이미 있는 저장소를 기록 체계로 끌어오는 용도라 파일을 만들지
+  // 않는다. 설치기를 복사해 쓰던 저장소가 여기로 들어온다.
+  const results = adopt ? [] : [
     ...ensureDirs(root, manifest.dirs, ctx),
     ...ensureFiles(root, manifest.files, ctx),
     ...ensureJsonKeys(root, manifest.settings ?? [], ctx),
     ...ensureBlocks(root, manifest.blocks, ctx),
   ]
 
-  // 어댑터는 항목별로 실패를 격리한다 — 하나가 실패해도 나머지를 계속한다.
-  for (const entry of manifest.adapters) {
-    try {
-      results.push(configureAdapter(root, entry, { ...ctx, skillMode }))
-    } catch (err) {
-      results.push({ ok: false, action: 'link', path: entry.path, message: err.message })
+  if (!adopt) {
+    // 어댑터는 항목별로 실패를 격리한다 — 하나가 실패해도 나머지를 계속한다.
+    // update.mjs도 같은 격리를 써야 하므로 apply.mjs가 단일 출처다.
+    for (const entry of manifest.adapters) {
+      results.push(configureAdapterSafe(root, entry, { ...ctx, skillMode }))
     }
+
+    results.push(...ensureIgnore(root, manifest.ignore, ctx))
   }
 
-  results.push(...ensureIgnore(root, manifest.ignore, ctx))
+  // 기존 기록의 items·design은 보존한다 — 부트스트랩은 배선만 다루므로
+  // 사용자가 고른 설치 항목을 지울 권한이 없다. dry-run에서는 읽지 않는다:
+  // 깨진 기록이 "무엇이 바뀔지 확인"까지 막을 이유가 없다.
+  const previous = dryRun ? null : readRecord(root)
+  const record = {
+    ...emptyRecord({ skillMode }),
+    items: previous?.items ?? [],
+    design: previous?.design ?? [],
+    managed: collectManaged(root, manifest),
+  }
+  results.push(writeRecord(root, record, ctx))
 
   const failed = results.filter((r) => !r.ok)
   log('')
@@ -49,6 +64,7 @@ export function runBootstrap(root, opts = {}) {
   say(`적용 도구: ${manifest.tools.join(', ')}`)
   say('도구별 설정은 모두 현재 저장소 안에만 생성되었습니다.')
   say('기존 설정 파일은 덮어쓰지 않았습니다.')
+  say(`설치 기록: ${RECORD_REL}`)
 
-  return { results, failed }
+  return { results, failed, record }
 }

package/lib/bootstrap/record.mjs

@@ -0,0 +1,142 @@
+// 저장소에 커밋되는 설치 기록.
+//
+// 이 파일은 "의도"다 — 실제 상태의 근거는 여전히 스캔이다. 기록이 더하는
+// 것은 재현성(팀원이 같은 결과를 얻는다)과 버전 고정, 그리고 "우리가 쓴
+// 그대로인가"를 판정할 해시다.
+//
+// 설치기 안의 manifest.mjs(무엇을 생성할지 선언)와 이름이 겹치지 않게
+// 저장소 쪽 파일은 '설치 기록'이라 부른다.
+//
+// 부트스트랩 그래프에 속하므로 node: 내장 모듈만 쓴다.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { repoPath, repoPathStrict } from '../context.mjs'
+import { hashBody, normalizeBody } from './text.mjs'
+
+export const RECORD_REL = '.agent-kit/agent-setup.json'
+export const FORMAT_VERSION = 1
+
+// 발행된 패키지에도 package.json은 항상 들어간다(npm이 무조건 포함한다).
+// createRequire 대신 URL로 읽어 의존성 0을 유지한다.
+let cachedVersion
+export function toolVersion() {
+  if (!cachedVersion) {
+    const url = new URL('../../package.json', import.meta.url)
+    cachedVersion = JSON.parse(readFileSync(url, 'utf8')).version
+  }
+  return cachedVersion
+}
+
+export function emptyRecord({ skillMode = 'auto' } = {}) {
+  return {
+    formatVersion: FORMAT_VERSION,
+    pinnedVersion: toolVersion(),
+    skillMode,
+    items: [],
+    design: [],
+    managed: {},
+  }
+}
+
+// 없으면 null. 있으면 필드를 채워 돌려준다 — 손으로 편집해 필드가 빠져도
+// 죽지 않아야 한다. 형식 버전이 다르면 추측하지 않고 던진다.
+export function readRecord(root) {
+  const target = repoPath(root, RECORD_REL)
+  let text
+  try {
+    text = readFileSync(target, 'utf8')
+  } catch (err) {
+    if (err.code === 'ENOENT') return null
+    throw new Error(`${RECORD_REL}을 읽을 수 없습니다 (${err.code ?? err.message})`)
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(text)
+  } catch (err) {
+    throw new Error(`${RECORD_REL}을 읽을 수 없습니다 — JSON이 아닙니다 (${err.message})`)
+  }
+
+  if (parsed.formatVersion !== FORMAT_VERSION) {
+    throw new Error(
+      `${RECORD_REL}의 형식 버전이 ${parsed.formatVersion}입니다. ` +
+      `이 도구는 ${FORMAT_VERSION}을 씁니다 — 도구를 올리거나 기록을 다시 만드세요.`,
+    )
+  }
+
+  return {
+    formatVersion: parsed.formatVersion,
+    pinnedVersion: parsed.pinnedVersion ?? null,
+    skillMode: parsed.skillMode ?? 'auto',
+    items: Array.isArray(parsed.items) ? parsed.items : [],
+    design: Array.isArray(parsed.design) ? parsed.design : [],
+    managed: parsed.managed && typeof parsed.managed === 'object' ? parsed.managed : {},
+  }
+}
+
+// pinnedVersion은 여기서 실행 중 버전으로 맞춘다 — 기록을 쓰는 명령만
+// 버전을 옮길 수 있어야 고정이 거짓말하지 않는다.
+export function writeRecord(root, record, { dryRun = false, log } = {}) {
+  const target = repoPathStrict(root, RECORD_REL)
+  const body = `${JSON.stringify({ ...record, pinnedVersion: toolVersion() }, null, 2)}\n`
+  log?.(`설치 기록 기록: ${RECORD_REL}`)
+  if (!dryRun) {
+    mkdirSync(dirname(target), { recursive: true })
+    writeFileSync(target, body, { encoding: 'utf8' })
+  }
+  return { ok: true, action: dryRun ? 'skip' : 'write', path: RECORD_REL }
+}
+
+// 마커는 apply.mjs의 ensureBlocks(생성)와 updateBlocks(갱신), 그리고 여기의
+// extractBlock(판정)이 함께 쓴다. 정의가 둘로 갈리면 한쪽만 고치는 회귀가
+// 생기므로 이 모듈이 단일 출처가 되고 apply.mjs가 import한다.
+export const BEGIN_MARKER = '<!-- agent-kit:begin -->'
+export const END_MARKER = '<!-- agent-kit:end -->'
+
+// 블록은 파일 전체가 아니라 마커 사이 본문만 관리 대상이다. 파일 전체 해시와
+// 섞이지 않게 키에 접미사를 붙인다.
+export const BLOCK_SUFFIX = '#agent-kit'
+
+export function managedKey(rel, isBlock) {
+  return isBlock ? `${rel}${BLOCK_SUFFIX}` : rel
+}
+
+// 마커 사이 본문을 정규화해 돌려준다. 마커가 없거나 순서가 뒤집혀 있으면 null.
+export function extractBlock(text) {
+  const begin = text.indexOf(BEGIN_MARKER)
+  if (begin === -1) return null
+  const end = text.indexOf(END_MARKER, begin + BEGIN_MARKER.length)
+  if (end === -1) return null
+  return normalizeBody(text.slice(begin + BEGIN_MARKER.length, end))
+}
+
+function readOrNull(root, rel) {
+  try {
+    return readFileSync(repoPath(root, rel), 'utf8')
+  } catch {
+    return null
+  }
+}
+
+// 채택 규칙: 현재 내용이 이 버전의 템플릿과 정규화 후 일치하는 것만 해시를
+// 남긴다. 그러지 않으면 사용자가 이미 고쳐 둔 파일이 "우리가 쓴 그대로"로
+// 위장되어 다음 update에 날아간다. 값이 null인 키는 update가 절대 덮어쓰지
+// 않으며, 없는 파일도 키를 남겨 update의 생성 분기가 집어간다.
+export function collectManaged(root, manifest) {
+  const managed = {}
+
+  for (const { path: rel, template } of manifest.files ?? []) {
+    const text = readOrNull(root, rel)
+    const wanted = hashBody(template)
+    managed[rel] = text !== null && hashBody(text) === wanted ? wanted : null
+  }
+
+  for (const { path: rel, block } of manifest.blocks ?? []) {
+    const text = readOrNull(root, rel)
+    const wanted = hashBody(extractBlock(block) ?? block)
+    const current = text === null ? null : extractBlock(text)
+    managed[managedKey(rel, true)] = current !== null && hashBody(current) === wanted ? wanted : null
+  }
+
+  return managed
+}

package/lib/bootstrap/text.mjs

@@ -0,0 +1,19 @@
+// 정규화와 해시의 단일 출처.
+//
+// 파일을 쓸 때와 "우리가 쓴 그대로인가"를 판정할 때 같은 정규화를 써야 한다.
+// 둘이 갈리면 갓 쓴 파일조차 드리프트로 보고된다. 그래서 이 모듈을 최하위에
+// 두고 apply.mjs(쓰기)와 record.mjs(판정)가 함께 import한다 — 한쪽에만
+// 정규화 규칙을 두면 두 모듈이 서로를 import하는 순환이 생긴다.
+//
+// 부트스트랩 그래프에 속하므로 node: 내장 모듈만 쓴다.
+import { createHash } from 'node:crypto'
+
+// 두 OS가 같은 파일을 만들도록 항상 LF + 끝 개행 1개로 정규화한다.
+export function normalizeBody(text) {
+  return text.replace(/\r\n/g, '\n').trim() + '\n'
+}
+
+// 정규화한 내용의 해시. 워킹트리 줄바꿈이 CRLF든 LF든 같은 값이 나온다.
+export function hashBody(text) {
+  return `sha256:${createHash('sha256').update(normalizeBody(text), 'utf8').digest('hex')}`
+}

package/lib/status.mjs

@@ -0,0 +1,92 @@
+// status — 의도(설치 기록) / 실제(스캔) / 가용(최신 패키지)을 나란히 보여준다.
+//
+// 실제 상태의 근거는 여전히 스캔이다. 기록은 의도일 뿐이므로 둘이 어긋나면
+// 어느 쪽에만 있는지 갈라 보여준다 — 수동 설치·제거를 그대로 잡는다는
+// 기존 강점을 기록이 가리지 않게 한다.
+import { MANIFEST } from './bootstrap/manifest.mjs'
+import { updateBlocks, updateFiles } from './bootstrap/apply.mjs'
+import { readRecord, toolVersion } from './bootstrap/record.mjs'
+
+export async function collectStatus(root, { manifest = MANIFEST, items = [], latest } = {}) {
+  const record = readRecord(root)
+
+  // dry-run으로 갱신 판정만 얻는다 — 판정 로직을 두 벌 두면 status와 update가
+  // 다른 답을 내는 순간이 온다.
+  const silent = () => {}
+  const verdicts = record
+    ? [
+        ...updateFiles(root, manifest.files, { managed: record.managed, dryRun: true, log: silent }),
+        ...updateBlocks(root, manifest.blocks, { managed: record.managed, dryRun: true, log: silent }),
+      ]
+    : []
+
+  const count = (action) => verdicts.filter((v) => v.action === action).length
+
+  const states = []
+  for (const item of items) {
+    try {
+      const r = await item.detect({ root })
+      states.push({ id: item.id, status: r.status })
+    } catch {
+      // 감지 실패로 status 전체가 죽으면 진단 도구가 아니다.
+      states.push({ id: item.id, status: 'absent' })
+    }
+  }
+  const installed = states.filter((s) => s.status !== 'absent').map((s) => s.id)
+  const intended = new Set(record?.items ?? [])
+
+  return {
+    hasRecord: Boolean(record),
+    tool: {
+      pinned: record?.pinnedVersion ?? null,
+      running: toolVersion(),
+      latest: latest ?? null,
+    },
+    files: {
+      total: verdicts.length,
+      current: count('skip'),
+      pending: count('update') + count('create'),
+      drift: count('drift'),
+    },
+    items: {
+      installed,
+      recordOnly: [...intended].filter((id) => !installed.includes(id)),
+      repoOnly: installed.filter((id) => !intended.has(id)),
+    },
+  }
+}
+
+export function formatStatus(report) {
+  const lines = []
+  const { tool, files, items } = report
+
+  if (!report.hasRecord) {
+    lines.push('설치 기록이 없습니다.')
+    lines.push('  이 저장소를 기록 체계로 끌어오려면 bootstrap --adopt 를 실행하세요.')
+    lines.push('  파일을 만들지 않고, 템플릿과 같은 파일만 관리 대상으로 기록합니다.')
+    return lines.join('\n')
+  }
+
+  const version = tool.latest && tool.latest !== tool.running
+    ? `${tool.pinned} 고정 · 실행 중 ${tool.running} · 최신 ${tool.latest}`
+    : `${tool.pinned} 고정 · 실행 중 ${tool.running}`
+  lines.push(`도구        ${version}`)
+  if (tool.pinned !== tool.running) lines.push('            → update로 고정 버전을 옮길 수 있습니다')
+
+  lines.push(`관리 파일   ${files.total}개 중 ${files.current} 최신 · ${files.pending} 갱신 대기 · ${files.drift} 사용자 수정`)
+  if (files.pending > 0) lines.push('            → update')
+  if (files.drift > 0) lines.push('            → 사용자 수정 파일은 update가 건드리지 않습니다')
+
+  lines.push(`항목        설치됨     ${items.installed.join(', ') || '(없음)'}`)
+  if (items.recordOnly.length) lines.push(`            기록에만   ${items.recordOnly.join(', ')}`)
+  if (items.repoOnly.length) lines.push(`            저장소에만 ${items.repoOnly.join(', ')}`)
+
+  return lines.join('\n')
+}
+
+export async function runStatus(root, { json = false, log = console.log } = {}) {
+  const { loadItems } = await import('./catalog.mjs')
+  const report = await collectStatus(root, { items: await loadItems() })
+  log(json ? JSON.stringify(report, null, 2) : formatStatus(report))
+  return report
+}

package/lib/update.mjs

@@ -0,0 +1,85 @@
+// update 흐름 — 관리 파일을 최신 템플릿으로 옮기고 드리프트를 보고한다.
+//
+// 갱신 판정은 apply.mjs의 updateFiles·updateBlocks가 하고, 여기는 순서와
+// 보고, 그리고 기록 갱신만 담당한다. flow.mjs가 생성 쪽에서 하는 역할과 같다.
+import { execFileSync } from 'node:child_process'
+import { MANIFEST } from './bootstrap/manifest.mjs'
+import {
+  configureAdapterSafe, ensureIgnore, ensureJsonKeys, updateBlocks, updateFiles,
+} from './bootstrap/apply.mjs'
+import { RECORD_REL, managedKey, readRecord, toolVersion, writeRecord } from './bootstrap/record.mjs'
+
+// git이 유일한 되돌리기 수단이다. 커밋되지 않은 변경 위에 덮어쓰면 사용자가
+// 잃은 것을 복구할 방법이 없다.
+function assertCleanWorktree(root) {
+  const out = execFileSync('git', ['-C', root, 'status', '--porcelain'], { encoding: 'utf8' })
+  if (out.trim()) {
+    throw new Error(
+      '--force는 워킹트리가 깨끗할 때만 쓸 수 있습니다. ' +
+      'git이 유일한 되돌리기 수단이라 커밋되지 않은 변경 위에 덮어쓰면 복구할 수 없습니다.',
+    )
+  }
+}
+
+export async function runUpdate(root, opts = {}) {
+  const { dryRun = false, force = false, log = console.log, manifest = MANIFEST } = opts
+  const say = (message) => log(`[agent-setup] ${message}`)
+
+  const record = readRecord(root)
+  if (!record) {
+    throw new Error(
+      `${RECORD_REL}이 없습니다. 이 저장소를 기록 체계로 끌어오려면 먼저 ` +
+      '`bootstrap --adopt`를 실행하세요 — 파일을 만들지 않고 기록만 만듭니다.',
+    )
+  }
+
+  if (force) assertCleanWorktree(root)
+
+  // 2단계에서는 버전 차이를 보고만 한다. 여기서 중단시키면 기존 사용자의
+  // 실행이 오류로 죽어 파괴적 변경이 된다. 엄격 검사는 apply와 함께 3단계다.
+  const running = toolVersion()
+  if (record.pinnedVersion && record.pinnedVersion !== running) {
+    say(`고정 ${record.pinnedVersion} → 실행 중 ${running}`)
+  }
+
+  const ctx = { dryRun, force, log: say, managed: record.managed }
+  const results = [
+    ...updateFiles(root, manifest.files, ctx),
+    ...updateBlocks(root, manifest.blocks, ctx),
+    // 키 보장과 gitignore 항목 추가는 원래 멱등이라 그대로 재실행한다.
+    ...ensureJsonKeys(root, manifest.settings ?? [], { dryRun, log: say }),
+    ...ensureIgnore(root, manifest.ignore, { dryRun, log: say }),
+  ]
+
+  // 어댑터는 링크가 끊겼을 수 있어 재검증한다. 항목별로 실패를 격리한다.
+  for (const entry of manifest.adapters) {
+    results.push(configureAdapterSafe(root, entry, {
+      dryRun, log: say, skillMode: record.skillMode,
+    }))
+  }
+
+  // 성공한 것만 기록에 옮긴다. 드리프트는 hash를 담지 않으므로 옛 해시가
+  // 남아, 사용자가 원복하면 다음 update가 다시 집어간다.
+  const managed = { ...record.managed }
+  for (const r of results) {
+    if (!r.hash) continue
+    const isBlock = manifest.blocks.some((b) => b.path === r.path)
+    managed[managedKey(r.path, isBlock)] = r.hash
+  }
+
+  const drift = results.filter((r) => r.action === 'drift')
+  const updated = results.filter((r) => r.action === 'update')
+  const created = results.filter((r) => r.action === 'create')
+
+  if (!dryRun) writeRecord(root, { ...record, managed }, { dryRun, log: say })
+
+  log('')
+  say(`갱신 ${updated.length}건 · 신규 ${created.length}건 · 드리프트 ${drift.length}건`)
+  if (drift.length > 0) {
+    say('드리프트 (건드리지 않았습니다)')
+    for (const d of drift) say(`  ${d.path}${d.message ? ` — ${d.message}` : ''}`)
+    say('최신 템플릿을 반영하려면 update --force (워킹트리가 깨끗해야 합니다)')
+  }
+
+  return { results, drift, record: { ...record, managed } }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rch4com/agent-setup",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "여러 코딩 에이전트 CLI를 한 저장소에서 함께 쓰기 위한 저장소 범위 부트스트랩과 선택 항목 설치기",
   "keywords": [
     "agents-md",

package/lib/items/.omc/state/sessions/a859aff7-59d9-4ff6-afc6-8cafe4471dc4/pre-tool-advisory-throttle.json

@@ -1,14 +0,0 @@
-{
-  "version": 1,
-  "entries": {
-    "79a93d4a2f8f50b95f852280616242fee1855dc99a3c75211917f55e72e95fae": {
-      "last_emitted_at_ms": 1785327065269,
-      "message": "Use parallel execution for independent tasks. Use run_in_background for long operations (npm install, builds, tests)."
-    },
-    "466399dafa2d20f60587180bad0a07358eb7f2bce724df0ff682f038ad33f5ad": {
-      "last_emitted_at_ms": 1785327034117,
-      "message": "Read multiple files in parallel when possible for faster analysis."
-    }
-  },
-  "updated_at": "2026-07-29T12:11:05.269Z"
-}