mega-framework 0.1.7 → 0.1.9

package/src/adapters/mega-cache-adapter.js

@@ -5,10 +5,15 @@
  * `ctx.cache(key)` 가 본 베이스 인스턴스를 반환. 구체: `MegaRedisAdapter` /
  * `MegaFileAdapter` (ADR-082).
  *
- * ⚠️ **키 네임스페이스(ADR-064)**: ADR-064 가 `mega:cache:<appName>:<key>` 자동 prefix 를 *결정*했으나
- * **현재 코어에 미구현**이다(get/set/del 이 raw `key` 를 그대로 사용). 멀티앱이 같은 redis 를 공유하면
- * 키 충돌 위험이 있으니, **현재는 사용자가 키에 앱별 네임스페이스를 직접 붙여야 한다**. 자동 prefix 구현은
- * 후속 과제(ADR-064 open). 단일앱(현 sample)에선 무관.
+ * **키 네임스페이스(ADR-064, 옵트인 — ADR-216 구현)**: `services.caches.<key>.namespace: '<name>'`
+ * 을 주면 get/set/del/has 의 키에 `mega:cache:<name>:` 가 자동 prefix 된다 — 멀티앱이 같은 redis 를
+ * 공유할 때의 키 충돌·상호 evict 차단(세션 `mega:sess:`·roster `ws:roster:` 와 대칭). 미지정 시
+ * 기존과 동일하게 raw key(하위 호환 — 기본 ON 전환은 메이저에서 재평가).
+ *
+ * **디폴트 TTL(ADR-216)**: `defaultTtlSec: <초>` 를 주면 `set` 의 ttl 미지정 호출에 적용된다 —
+ * 동적 키에 ttl 을 빠뜨려 무한 증가하는 풋건 방어. `defaultTtlSec: 0` = 무한 저장을 의식적으로
+ * 선택(경고 없음). 둘 다 미지정인 채 ttl 없는 set 이 호출되면 **인스턴스당 1회** process.emitWarning
+ * 으로 표면화한다(동작은 기존과 동일 — 무한 저장).
  *
  * @module adapters/mega-cache-adapter
  */
@@ -16,8 +21,21 @@ import { MegaInternalError, MegaValidationError } from '../errors/http-errors.js
 import { MegaAdapter } from './mega-adapter.js'
 
 export class MegaCacheAdapter extends MegaAdapter {
+  /** @type {string | null} ADR-064 자동 prefix (`mega:cache:<namespace>:`) — 미지정이면 null(raw key). */
+  #keyPrefix = null
+
+  /** @type {number | null} set 의 ttl 미지정 시 적용할 디폴트(초). null = 미설정. */
+  #defaultTtlSec = null
+
+  /** @type {boolean} `defaultTtlSec: 0` — 무한 저장 의식적 옵트인(경고 억제). */
+  #isInfiniteTtlOptIn = false
+
+  /** @type {boolean} 무기한 set 경고를 인스턴스당 1회로 제한. */
+  #hasWarnedNoTtl = false
+
   /**
-   * @param {object} [config]
+   * @param {{ namespace?: string, defaultTtlSec?: number } & Record<string, any>} [config]
+   * @throws {MegaValidationError} `adapter.invalid_option` - namespace/defaultTtlSec 형식 오류.
    */
   constructor(config) {
     super(config)
@@ -28,6 +46,65 @@ export class MegaCacheAdapter extends MegaAdapter {
         { details: { class: 'MegaCacheAdapter' } },
       )
     }
+    const ns = config?.namespace
+    if (ns !== undefined) {
+      // 콜론·공백은 prefix 구조(`mega:cache:<ns>:<key>`)의 구분자 혼동을 만든다 — 명시 거부.
+      if (typeof ns !== 'string' || ns.length === 0 || /[\s:]/.test(ns)) {
+        throw new MegaValidationError(
+          'adapter.invalid_option',
+          `cache "namespace" must be a non-empty string without spaces/colons (got ${JSON.stringify(ns)}).`,
+          { details: { namespace: ns ?? null } },
+        )
+      }
+      this.#keyPrefix = `mega:cache:${ns}:`
+    }
+    const ttl = config?.defaultTtlSec
+    if (ttl !== undefined) {
+      if (ttl === 0) {
+        this.#isInfiniteTtlOptIn = true
+      } else if (!Number.isInteger(ttl) || ttl < 0) {
+        throw new MegaValidationError(
+          'adapter.invalid_option',
+          `cache "defaultTtlSec" must be a non-negative integer (0 = 무한 저장 옵트인, got ${JSON.stringify(ttl)}).`,
+          { details: { defaultTtlSec: ttl } },
+        )
+      } else {
+        this.#defaultTtlSec = ttl
+      }
+    }
+  }
+
+  /**
+   * 네임스페이스 적용 키 — 구체 어댑터의 get/set/del/has 가 저장소 접근 직전에 경유한다(ADR-064).
+   * @protected
+   * @param {string} key
+   * @returns {string}
+   */
+  _cacheKey(key) {
+    return this.#keyPrefix === null ? key : this.#keyPrefix + key
+  }
+
+  /**
+   * `set` 의 유효 TTL 해석 — 명시 ttl 우선, 없으면 defaultTtlSec. 둘 다 없으면 무한 저장이며
+   * `defaultTtlSec: 0` 옵트인이 아닌 한 인스턴스당 1회 경고를 낸다(키 무한 증가 풋건 표면화 —
+   * 동작은 기존과 동일, ADR-216).
+   * @protected
+   * @param {number} [ttl] - 호출자가 명시한 ttl(초).
+   * @param {string} [key] - 경고 메시지용 예시 키.
+   * @returns {number | undefined} 적용할 ttl(초) — undefined 면 무한.
+   */
+  _resolveTtl(ttl, key) {
+    if (ttl !== undefined) return ttl
+    if (this.#defaultTtlSec !== null) return this.#defaultTtlSec
+    if (!this.#isInfiniteTtlOptIn && !this.#hasWarnedNoTtl) {
+      this.#hasWarnedNoTtl = true
+      process.emitWarning(
+        `cache.set("${key ?? '?'}") without ttl and no defaultTtlSec configured — keys never expire and can grow unbounded. ` +
+          `Set services.caches.<key>.defaultTtlSec (or pass { ttl }), or defaultTtlSec: 0 to opt in to unbounded storage.`,
+        { code: 'MEGA_CACHE_NO_TTL' },
+      )
+    }
+    return undefined
   }
 
   /**
@@ -41,7 +118,7 @@ export class MegaCacheAdapter extends MegaAdapter {
   /**
    * @param {string} _key
    * @param {any} _value
-   * @param {{ ttl?: number }} [_opts] - `ttl` 미지정 시 무한 (초 단위).
+   * @param {{ ttl?: number }} [_opts] - `ttl` 미지정 시 defaultTtlSec, 그것도 없으면 무한(초 단위, ADR-216).
    * @returns {Promise<void>}
    */
   async set(_key, _value, _opts = {}) {

package/src/adapters/mega-db-adapter.js

@@ -30,7 +30,10 @@ export class MegaDbAdapter extends MegaAdapter {
    * driver 별 구현 (postgres `BEGIN/COMMIT/ROLLBACK`, MongoDB `session.withTransaction`).
    * nested 호출은 driver 별 (postgres SAVEPOINT, MongoDB throw `adapter.nested_transaction_unsupported`).
    *
-   * `opts.isolation`(ADR-190) — SQL 격리수준 옵트인. 미지정이면 driver 디폴트. driver 별 지원:
+   * `opts.isolation`(ADR-190) — SQL 격리수준 옵트인. **미지정이면 driver 디폴트가 적용되며 그
+   * 디폴트는 driver 마다 다르다**(ADR-216 G2 M-2): postgres = READ COMMITTED,
+   * mariadb(InnoDB) = REPEATABLE READ — 같은 `withTransaction(fn)` 코드가 driver 에 따라 다른
+   * 동시성 의미를 가진다. 이식성 있는 동시성 가정이 필요하면 isolation 을 명시할 것. driver 별 지원:
    * postgres/maria 는 top-level 트랜잭션에 `SET TRANSACTION ISOLATION LEVEL` 로 반영(nested 엔 불가 —
    * `adapter.nested_isolation_unsupported`), sqlite 는 항상 SERIALIZABLE 동작이라 'serializable' 만 수용,
    * mongodb 는 SQL 격리수준 개념이 없어 지정 시 `adapter.invalid_option`.

package/src/adapters/mongo-adapter.js

@@ -137,6 +137,7 @@ function buildMongoUri({ host, port, user, password }) {
  * @typedef {object} PoolCounters
  * @property {number} created @property {number} closed
  * @property {number} checkedOut @property {number} checkedIn
+ * @property {number} checkOutStarted @property {number} checkOutFailed
  */
 
 export class MegaMongoAdapter extends MegaDbAdapter {
@@ -162,7 +163,7 @@ export class MegaMongoAdapter extends MegaDbAdapter {
    */
   #txContext = new AsyncLocalStorage()
   /** @type {PoolCounters} CMAP 이벤트 누적 풀 카운터. */
-  #pool = { created: 0, closed: 0, checkedOut: 0, checkedIn: 0 }
+  #pool = { created: 0, closed: 0, checkedOut: 0, checkedIn: 0, checkOutStarted: 0, checkOutFailed: 0 }
   /**
    * 등록한 CMAP 리스너 — disconnect 시 정확히 제거하기 위해 보관(누수·재연결 시 중복 방지).
    * @type {Array<[string, (...args: any[]) => void]>}
@@ -296,23 +297,33 @@ export class MegaMongoAdapter extends MegaDbAdapter {
   }
 
   /**
-   * 누적 통계 + mongo 특화(driver/dbName + CMAP 풀 카운터). 연결 전이면 카운터는 0.
-   * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, dbName: string, pool: { created: number, closed: number, checkedOut: number, checkedIn: number, open: number, inUse: number } }}
+   * 누적 통계 + mongo 특화(driver/dbName + CMAP 풀 카운터). 공통 코어 키
+   * `{ total, active, idle, waiting }` 은 4 driver 동일 형태(ADR-216 G2 H-2 — CMAP 누적
+   * 카운터에서 파생: total=created-closed, active=checkedOut-checkedIn,
+   * waiting=checkOutStarted-(checkedOut+checkOutFailed)). 누적 원본도 유지(하위 호환).
+   * 연결 전이면 전부 0.
+   * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, dbName: string, pool: { total: number, active: number, idle: number, waiting: number, created: number, closed: number, checkedOut: number, checkedIn: number, open: number, inUse: number } }}
    */
   getStats() {
-    const { created, closed, checkedOut, checkedIn } = this.#pool
+    const { created, closed, checkedOut, checkedIn, checkOutStarted, checkOutFailed } = this.#pool
+    const total = created - closed
+    const active = checkedOut - checkedIn
     return {
       ...super.getStats(),
       driver: 'mongodb',
       dbName: this.#dbName,
       pool: {
+        total,
+        active,
+        idle: total - active,
+        waiting: checkOutStarted - checkedOut - checkOutFailed,
         created,
         closed,
         checkedOut,
         checkedIn,
-        // 파생값 — open=살아있는 연결 수, inUse=현재 체크아웃된(작업 중) 연결 수.
-        open: created - closed,
-        inUse: checkedOut - checkedIn,
+        // 파생값(기존 표면 유지) — open=살아있는 연결 수, inUse=현재 체크아웃된(작업 중) 연결 수.
+        open: total,
+        inUse: active,
       },
     }
   }
@@ -389,6 +400,9 @@ export class MegaMongoAdapter extends MegaDbAdapter {
       ['connectionClosed', () => (this.#pool.closed += 1)],
       ['connectionCheckedOut', () => (this.#pool.checkedOut += 1)],
       ['connectionCheckedIn', () => (this.#pool.checkedIn += 1)],
+      // 공통 풀 키의 waiting 파생용(ADR-216) — started - (out + failed) = 현재 대기 수.
+      ['connectionCheckOutStarted', () => (this.#pool.checkOutStarted += 1)],
+      ['connectionCheckOutFailed', () => (this.#pool.checkOutFailed += 1)],
     ]
     for (const [event, handler] of listeners) {
       client.on(event, handler)

package/src/adapters/postgres-adapter.js

@@ -216,17 +216,21 @@ export class MegaPostgresAdapter extends MegaDbAdapter {
   }
 
   /**
-   * 누적 통계 + 풀 통계(total/idle/waiting). 연결 전이면 풀 통계는 0.
-   * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, pool: { total: number, idle: number, waiting: number } }}
+   * 누적 통계 + 풀 통계 — 공통 코어 키 `{ total, active, idle, waiting }` 은 4 driver 동일
+   * 형태(ADR-216 G2 H-2: 운영 대시보드가 driver 무관 코드로 "풀 포화" 를 묻게). 연결 전이면 0.
+   * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, pool: { total: number, active: number, idle: number, waiting: number } }}
    */
   getStats() {
     const pool = this.#pool
+    const total = pool?.totalCount ?? 0
+    const idle = pool?.idleCount ?? 0
     return {
       ...super.getStats(),
       driver: 'postgres',
       pool: {
-        total: pool?.totalCount ?? 0,
-        idle: pool?.idleCount ?? 0,
+        total,
+        active: total - idle,
+        idle,
         waiting: pool?.waitingCount ?? 0,
       },
     }

package/src/adapters/redis-adapter.js

@@ -61,6 +61,8 @@ import * as Registry from './registry.js'
  * @property {string} [host] @property {number} [port] @property {string} [user] @property {string} [password]
  * @property {number} [db] - 논리 DB 번호 0~15 (connection 과 별개 축, url path 보다 우선).
  * @property {any} [pool] - 미지원 — 지정 시 `adapter.invalid_option` throw (Redis 는 풀 모델 아님, ADR-110).
+ * @property {string} [namespace] - 캐시 키 자동 prefix `mega:cache:<namespace>:` (ADR-064/213 — 멀티앱 충돌 차단, 옵트인).
+ * @property {number} [defaultTtlSec] - `set` 의 ttl 미지정 시 적용할 디폴트(초). 0 = 무한 저장 옵트인(경고 억제). (ADR-216)
  * @property {Record<string, any>} [options] - ioredis passthrough (keyPrefix, commandTimeout, tls, retryStrategy, keepAlive, …).
  */
 
@@ -267,7 +269,7 @@ export class MegaRedisAdapter extends MegaCacheAdapter {
    */
   async get(key) {
     return this._instrument('get', { key }, async () => {
-      const raw = await /** @type {import('ioredis').Redis} */ (this.#client).get(key)
+      const raw = await /** @type {import('ioredis').Redis} */ (this.#client).get(this._cacheKey(key))
       if (raw === null) return null // miss
       return JSON.parse(raw)
     })
@@ -287,6 +289,8 @@ export class MegaRedisAdapter extends MegaCacheAdapter {
     // I/O·hook·stats 누적 이전에 fail-fast 로 거부하는 게 맞다(인자 오류는 어댑터 "호출"이 아니라
     // 프로그래밍 오류 — instrumented 호출 통계에 섞이면 안 됨). 정상 경로의 실제 I/O 만 _instrument 가 감싼다.
     this._assertTtl(ttl)
+    ttl = this._resolveTtl(ttl, key) // 미지정 → defaultTtlSec(ADR-216). 디폴트 값은 생성자에서 검증됨.
+    key = this._cacheKey(key)
     const raw = JSON.stringify(value)
     if (raw === undefined) {
       // JSON.stringify(undefined/함수/심볼) === undefined — 저장 시 silent 손상 대신 명시 거부.
@@ -309,7 +313,7 @@ export class MegaRedisAdapter extends MegaCacheAdapter {
    */
   async del(key) {
     return this._instrument('del', { key }, async () => {
-      await /** @type {import('ioredis').Redis} */ (this.#client).del(key)
+      await /** @type {import('ioredis').Redis} */ (this.#client).del(this._cacheKey(key))
     })
   }
 
@@ -320,7 +324,7 @@ export class MegaRedisAdapter extends MegaCacheAdapter {
    */
   async has(key) {
     return this._instrument('has', { key }, async () => {
-      const n = await /** @type {import('ioredis').Redis} */ (this.#client).exists(key)
+      const n = await /** @type {import('ioredis').Redis} */ (this.#client).exists(this._cacheKey(key))
       return n === 1
     })
   }

package/src/adapters/sqlite-adapter.js

@@ -219,10 +219,11 @@ export class MegaSqliteAdapter extends MegaDbAdapter {
   }
 
   /**
-   * 누적 통계 + sqlite 특화 필드.
-   * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, filename: string, inMemory: boolean, readonly: boolean, journalMode: string | undefined }}
+   * 누적 통계 + sqlite 특화 필드 + 공통 풀 코어 키(합성 — 단일 연결, ADR-216).
+   * @returns {ReturnType<import('./mega-adapter.js').MegaAdapter['getStats']> & { driver: string, filename: string, inMemory: boolean, readonly: boolean, journalMode: string | undefined, pool: { total: number, active: number, idle: number, waiting: number } }}
    */
   getStats() {
+    const connected = this.state === 'connected'
     return {
       ...super.getStats(),
       driver: 'sqlite',
@@ -231,6 +232,9 @@ export class MegaSqliteAdapter extends MegaDbAdapter {
       readonly: this.#openOptions.readonly,
       // _connect() 에서 캐시한 불변값 사용 — 미연결이면 undefined(매 호출 PRAGMA 실행 제거, L-4).
       journalMode: this.#journalMode,
+      // 공통 풀 코어 키(ADR-216 G2 H-2) — sqlite 는 connection-per-Database 단일 동기 연결이라
+      // 풀이 없다. 쿼리가 동기라 stats 를 읽는 시점엔 항상 유휴(active 0/waiting 0) — 합성 값.
+      pool: connected ? { total: 1, active: 0, idle: 1, waiting: 0 } : { total: 0, active: 0, idle: 0, waiting: 0 },
     }
   }
 

package/src/cli/commands/console-cmd.js

@@ -9,7 +9,6 @@
  * @module cli/commands/console-cmd
  */
 import repl from 'node:repl'
-import { prepareRuntime } from '../../core/boot.js'
 import { MegaShutdown } from '../../lib/mega-shutdown.js'
 
 /**
@@ -38,6 +37,9 @@ export async function startConsole(
   projectRoot,
   { logger, replFactory = defaultReplFactory, out = console.log, shutdown = () => MegaShutdown.now(), setupSignals = (opts) => MegaShutdown.setupSignals(opts) } = {},
 ) {
+  // boot 그래프(fastify·OTel·pino 등)는 콘솔 기동 시점에만 로드 — scaffold.js 가 본 모듈을 정적
+  // import 하므로, 여기서 정적 import 하면 `mega help`/`g` 까지 전체 그래프를 지불하게 된다.
+  const { prepareRuntime } = await import('../../core/boot.js')
   const { global, host, ctx } = await prepareRuntime(projectRoot, { ping: false, logger })
   out('mega: console ready — globals: ctx, config, mega')
   // prepareRuntime 이 어댑터/워커/wsHub 를 connect 하고 각자 MegaShutdown hook 을 자기등록한다. 정리 없이

package/src/cli/commands/scaffold.js

@@ -13,7 +13,9 @@ import { Command } from 'commander'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
-import { generate, generateFromScaffoldDef, GENERATOR_KINDS } from '../generators/index.js'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { generate, generateFromScaffoldDef, nextAdrNumber, GENERATOR_KINDS } from '../generators/index.js'
 import { scaffoldProject } from './new.js'
 import { runRoutesCommand } from './routes.js'
 import { runTestCommand } from './test-cmd.js'
@@ -31,6 +33,36 @@ function reportFiles(out, r, root) {
   for (const f of r.skipped) out(`  skip    ${f.startsWith(root) ? f.slice(root.length + 1) : f} (exists — use --force)`)
 }
 
+const execFileAsync = promisify(execFile)
+
+/**
+ * `g adr` 의 다음 번호를 **원격 포함**으로 해석한다(ADR-218 — 병렬 task 번호 충돌 회피).
+ * `git fetch origin` 후 `origin/main` 의 `docs/adr/` 파일명에서 번호를 모아 로컬 스캔
+ * ({@link nextAdrNumber})과 합산한다 — 형제 task 가 방금 push 한 ADR 이 로컬 작업트리에 없어도
+ * 번호가 건너뛰어진다. git 부재/오프라인/비-repo 는 로컬 스캔만으로 폴백(경고 1줄 — 스캐폴드는
+ * 어디서든 동작해야 하므로 fail 아님).
+ *
+ * @param {string} projectRoot
+ * @param {(msg: string) => void} out
+ * @returns {Promise<number>}
+ */
+async function resolveAdrNumberWithRemote(projectRoot, out) {
+  /** @type {number[]} */
+  const remote = []
+  try {
+    await execFileAsync('git', ['fetch', 'origin', '--quiet'], { cwd: projectRoot })
+    const { stdout } = await execFileAsync('git', ['ls-tree', '--name-only', 'origin/main', 'docs/adr/'], { cwd: projectRoot })
+    for (const line of stdout.split('\n')) {
+      const m = line.match(/(\d{1,4})-[^/]+\.md$/)
+      if (m) remote.push(Number(m[1]))
+    }
+  } catch (err) {
+    // 오프라인/비-repo/origin 부재 — 로컬 스캔만으로 진행하되 충돌 가능성을 알린다(silent 금지).
+    out(`mega: 원격 ADR 번호 확인 실패(${/** @type {any} */ (err).message?.split('\n')[0] ?? err}) — 로컬 기준으로 번호를 할당합니다.`)
+  }
+  return nextAdrNumber(projectRoot, remote)
+}
+
 /**
  * `g model --adapter <key>` 의 adapter 키/driver 해석 — mega.config.js 의 services.databases 를
  * best-effort 로 읽는다(스캐폴드는 config 가 아직 없는 초기 프로젝트에서도 돌아야 하므로 로드
@@ -109,10 +141,14 @@ export function registerScaffoldCommands(program, { out, projectRoot, logger, re
         /** @type {{ key: string, driver: string | undefined }} */
         let modelAdapter = { key: 'primary', driver: undefined }
         if (kind === 'model') modelAdapter = await resolveModelAdapter(projectRoot, opts.adapter, out)
+        // adr 은 번호를 원격 포함으로 해석한다(병렬 task 충돌 회피, ADR-218).
+        /** @type {number | undefined} */
+        let adrNumber
+        if (kind === 'adr') adrNumber = await resolveAdrNumberWithRemote(projectRoot, out)
         r = generate(
           kind,
           name,
-          { app: opts.app, version: opts.version, kind: opts.kind, lng: opts.lng, force: opts.force === true, adapter: modelAdapter.key, adapterDriver: modelAdapter.driver },
+          { app: opts.app, version: opts.version, kind: opts.kind, lng: opts.lng, force: opts.force === true, adapter: modelAdapter.key, adapterDriver: modelAdapter.driver, adrNumber },
           projectRoot,
         )
       } else {

package/src/cli/generators/index.js

@@ -13,7 +13,7 @@
  *
  * @module cli/generators
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join, relative, resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { nameVariants, renderTemplate } from '../template-engine.js'
@@ -36,6 +36,7 @@ export const GENERATOR_KINDS = /** @type {const} */ ([
   'locale',
   'adapter',
   'migration',
+  'adr',
 ])
 
 /**
@@ -185,11 +186,67 @@ export function planArtifacts(kind, rawName, opts, projectRoot) {
     case 'app':
       return planApp(v, projectRoot, base)
 
+    case 'adr':
+      return planAdr(v, opts, projectRoot)
+
     default:
       throw new Error(`Unknown generator kind '${kind}'. Supported: ${GENERATOR_KINDS.join(', ')}.`)
   }
 }
 
+/**
+ * 다음 ADR 번호를 해석한다 — `docs/adr/NNNN-*.md` 파일명 + 레거시 `docs/09` 헤딩(`### ADR-N:`) +
+ * 호출측이 모은 추가 번호(예: `git ls-tree origin/main` 의 원격 파일 — 병렬 task 충돌 회피)의
+ * 최댓값 + 1. 아무 ADR 도 없으면 1.
+ *
+ * @param {string} projectRoot
+ * @param {number[]} [extraNumbers] - 로컬 밖에서 관측한 번호(원격 스캔 등).
+ * @returns {number}
+ */
+export function nextAdrNumber(projectRoot, extraNumbers = []) {
+  let max = 0
+  const adrDir = join(projectRoot, 'docs/adr')
+  if (existsSync(adrDir)) {
+    for (const f of readdirSync(adrDir)) {
+      const m = f.match(/^(\d{1,4})-.+\.md$/)
+      if (m) max = Math.max(max, Number(m[1]))
+    }
+  }
+  const legacy = join(projectRoot, 'docs/09-decisions-and-open-questions.md')
+  if (existsSync(legacy)) {
+    for (const m of readFileSync(legacy, 'utf8').matchAll(/^### ADR-(\d+)/gm)) {
+      max = Math.max(max, Number(m[1]))
+    }
+  }
+  for (const n of extraNumbers) {
+    if (Number.isInteger(n)) max = Math.max(max, n)
+  }
+  return max + 1
+}
+
+/** adr — `docs/adr/NNNN-<name>.md` 1개(코드/테스트 쌍 아님 — 프로젝트 결정 기록 문서, ADR-218).
+ * 번호는 opts.adrNumber(호출측이 원격 포함 해석) 우선, 미지정 시 로컬 스캔({@link nextAdrNumber}).
+ * @param {Variants} v @param {Record<string, any>} opts @param {string} projectRoot
+ * @returns {Artifact[]} */
+function planAdr(v, opts, projectRoot) {
+  const number = Number.isInteger(opts.adrNumber) && opts.adrNumber > 0 ? opts.adrNumber : nextAdrNumber(projectRoot)
+  const padded = String(number).padStart(4, '0')
+  const d = new Date()
+  const p = (/** @type {number} */ n) => String(n).padStart(2, '0')
+  const vars = {
+    number: String(number),
+    title: v.words.join(' '),
+    date: `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`,
+  }
+  return [
+    {
+      outAbs: join(projectRoot, `docs/adr/${padded}-${v.kebab}.md`),
+      role: 'code',
+      content: renderTemplate(readTpl('adr', 'code.tpl'), vars),
+    },
+  ]
+}
+
 /**
  * @typedef {{ kebab: string, pascal: string, camel: string, snake: string, words: string[] }} Variants
  * @typedef {Record<string, string>} BaseVars