@kaydash9999/banker-plugins 0.16.1 → 0.16.3

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude Code skills + commands — QA, audit, docs, architecture, dependency setup, and wiki; the banker plugin marketplace.",
-    "version": "0.16.1"
+    "version": "0.16.3"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "banker",
-  "version": "0.16.1",
+  "version": "0.16.3",
   "description": "Claude Code plugin: QA/audit/docs/architecture skills + commands, a /banker:setup installer for OS dependencies (playwright, etc.), and wiki compaction.",
   "author": {
     "name": "smallOpenSource",

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.16.3] - 2026-10-12
+
+### Fixed
+- **`/progress` 패널에 계획이 보인다.** Claude Code 2.1.296 은 Claude 5 모델에 작업 목록 도구(TaskCreate, TaskUpdate, TodoWrite)를 주지 않아, 패널은 요청 단위 단계만 보였다.\
+  이제 세션이 쓰거나 읽은 마지막 계획 파일의 단계를 맨 위에 보인다. 읽는 파일은 `.omc/plans/*.md`, `docs/superpowers/plans/*.md`, `~/.claude/plans/*.md`, ralph `prd.json`, ultragoal `goals.json` 이다. PRD 의 `passes`, goals 의 `status`, 계획의 체크박스가 있으면 완료와 진행 중을 표시한다. 파일은 그 파일을 고친 도구 호출이 끝날 때와 턴의 시작과 끝에 다시 읽는다. 세션이 만지지 않은 파일은 보이지 않는다.
+- 계획 문서의 단계는 다음 순서로 고른다. superpowers 의 `### Task N:` 제목, 같은 수준의 `Phase N` 이나 `N단계` 제목 묶음, 맨 위 수준의 체크박스, 이름이 단계인 구역(작업 순서, 구현 단계, Implementation Steps 등)의 번호 목록이나 하위 제목. 코드 블록 안의 줄과 수용 기준 구역의 체크박스는 단계가 아니다.
+- 계획 폴더의 검토 문서(이름이 `-critic.md`, `-architect-r2.md`, `-review.md`, `-verdict.md` 처럼 끝나는 파일)와 `open-questions.md` 는 계획으로 보지 않는다. 하위 에이전트가 계획을 읽기만 하면 패널의 계획이 바뀌지 않는다. 단계가 없는 문서는 단계가 있는 계획을 대신하지 않는다.
+- 슬래시 명령의 단계 제목이 `<command-message>` 태그 원문이 아니라 `/명령 인자` 로 보인다. 그 밖의 하네스 태그(`<system-reminder>` 등)도 제목과 설명에서 지운다.
+- 백그라운드 작업이 끝났다는 알림(`<task-notification>`)과 팀원 메시지가 단계를 새로 만들지 않는다. 직전 요청의 단계 아래에 한 줄로 붙고, 그동안 그 단계를 진행 중으로 보이되 원래 결과와 걸린 시간은 그대로 둔다. 실패한 작업은 실패 행으로 보인다. 다른 세션에서 온 메시지는 `[다른 세션]` 단계가 된다.
+- 긴 제목은 패널 폭에 맞춰 자른다(한글과 기본이 이모지인 문자는 2칸). 상태 글자가 다음 줄로 넘어가지 않는다.
+
+## [0.16.2] - 2026-10-11
+
+### Security
+- **3d-intro 가 프로젝트 폴더에 든 파일로 실행할 프로그램을 정하지 않는다.** 0.16.1 까지는 남이 만든 저장소에서 3d-intro-build 를 돌리면, 그 저장소가 커밋해 둔 파일이 실행될 수 있었다.\
+  프로젝트 키 파일(`.env.3d-intro.local`)의 `FFMPEG_PATH` 를 ffmpeg 로 실행했다. 이제 그 값은 읽지 않고 이름만 알린다. 독립 검증(`verify-intro.mjs`)은 프로젝트의 `node_modules/playwright` 를 먼저 불러왔다. 이제 `--playwright-from-project` 를 줄 때만 읽는다. Windows 에서는 `npm root -g` 를 프로젝트 폴더에서 돌려 그 폴더의 `npm.cmd` 가 먼저 실행될 수 있었다. 이제 홈 폴더에서 돌린다.
+- ffmpeg 는 셸의 `FFMPEG_PATH`, 홈 설정 파일 `~/.config/banker/3d-intro/settings.env`, 예전 판이 홈 키 파일에 남긴 값, `PATH` 의 절대 경로 항목, `ffmpeg-static` 순으로 찾는다. 경로는 절대 경로만 받고, `PATH` 의 `.` 같은 상대 항목은 건너뛴다. 설정 파일에는 키를 두지 않는다.
+- 키 파일에 줄바꿈이 든 값이나 변수 이름이 아닌 키를 쓰지 않는다. 0.16.1 까지는 콘솔 샘플의 여러 줄 값이 홈 키 파일에 `FFMPEG_PATH` 나 두 번째 endpoint 줄을 심을 수 있었다.
+- `3d-intro-setup` 의 `ffmpeg-static` 폴백은 프로젝트가 아니라 홈의 전용 폴더(`~/.config/banker/3d-intro/tools`)에 설치한다. 프로젝트의 `.npmrc` 와 스크립트가 끼어들지 않는다. 새로 만드는 설정 폴더는 0700 이다.
+
+### Notes
+- 예전 판이 프로젝트 키 파일에만 ffmpeg 경로를 남겼고 `PATH` 에 ffmpeg 가 없다면, 3d-intro-build 가 "ffmpeg not found" 로 멈춘다. 셸에서 `export FFMPEG_PATH=<절대 경로>` 한 뒤 `3d-intro-setup` §2 를 한 번 다시 돌리면 홈 설정 파일에 남는다.
+- 프로젝트에만 playwright 를 설치했다면 독립 검증에 `--playwright-from-project` 를 준다.
+
 ## [0.16.1] - 2026-10-11
 
 ### Security

package/README.md

@@ -59,7 +59,7 @@ Claude Code는 `/banker:<이름>`, Codex는 `banker-<이름>` 으로 호출합
 | `cleansing-memory` | 프로젝트가 장기화될 때 | 메모리 최적화 |
 | `ready-compact` | 컨텍스트를 compact 하거나 새 세션을 대비할 때 | 이어갈 프롬프트만 출력(`/copy` 한 번이면 복사), `--hand-off` = 새 세션에서 이어가기 |
 | `/graceful-pause` | 작업 도중 방향을 바꾸거나 끼어들고 싶을 때 | 작업 중에 입력해도 바로 전달. 실행 중인 도구 호출이 끝나면 그 단계까지만 마무리하고 멈춘 뒤 지시를 기다림 (Claude Code) |
-| `/progress` | 지금 작업이 어디까지 왔는지 보고 싶을 때 | 진행 단계 목록 패널을 켜고 끔. 단계를 누르면 설명, 화살표를 누르면 그 단계가 진행 중일 때 한 도구 호출이 펼쳐짐 (Claude Code) |
+| `/progress` | 지금 작업이 어디까지 왔는지 보고 싶을 때 | 진행 상황 패널을 켜고 끔. 세션이 쓰거나 읽은 계획 파일의 단계가 위에, 요청과 그 도구 호출이 아래에 보임. 단계를 누르면 설명, 화살표를 누르면 펼쳐짐 (Claude Code) |
 | `tone-compact` | 답변을 짧은 한글 개조식으로 받고 싶을 때 | 문체 규칙을 켜 두면 끌 때까지 모든 세션에 적용 |
 | `omc-patch` | OMC 자동 업데이트 뒤 훅이 느려지거나 훅 프로세스가 쌓일 때 | 사라진 훅 패치를 다시 적용하고 OMC 자동 업데이트를 고정 |
 | `remains` | 작업 뒤에 남은 버그, 하자, 미검증 항목을 한눈에 보고 싶을 때 | 남은 항목을 표로 정리하고, 등록한 테스트박스에서 시험까지 돌림 |
@@ -74,7 +74,9 @@ Claude Code는 `/banker:<이름>`, Codex는 `banker-<이름>` 으로 호출합
 | `/banker:front-qa` | 스펙(note) 기반 프론트엔드 구현 + parity QA |
 | `/banker:setup` | 구성요소·의존성 설치 오케스트레이터 (multi-select) |
 | `/graceful-pause` | 작업 중에도 바로 실행되는 정지 요청. 지금 단계만 끝내고 멈춘 뒤 보고하고 지시를 기다림 (Claude Code 2.1.289 이상, mod. Codex 미지원) |
-| `/progress` | 진행 상황 패널을 켜고 끔(`show` 기본 토글, `on`, `off`). 단계는 Claude 의 작업 목록, 없으면 이 세션의 요청이고, 하위 목록은 그 단계가 진행 중일 때 한 도구 호출 한 단계까지. 작업 중에도 바로 실행됨(2.1.289 이상에서 확인) (mod. Codex 미지원) |
+| `/progress` | 진행 상황 패널을 켜고 끔(`show` 기본 토글, `on`, `off`). 맨 위는 이 세션이 쓰거나 읽은 마지막 계획 파일(`.omc/plans/*.md`, `docs/superpowers/plans/*.md`, `~/.claude/plans/*.md`, ralph `prd.json`, ultragoal `goals.json`)의 단계. 그 아래 단계는 Claude 의 작업 목록, 없으면 이 세션의 요청이고, 하위 목록은 그 단계가 진행 중일 때 한 도구 호출 한 단계까지. 작업 중에도 바로 실행됨(2.1.289 이상에서 확인) (mod. Codex 미지원) |
+
+Claude Code 2.1.296 은 Claude 5 모델(Opus 5.5 등)에 작업 목록 도구(TaskCreate, TodoWrite)를 주지 않습니다. 그래서 `/progress` 의 단계는 보통 요청 단위이고, 계획은 계획 파일로 보입니다. 작업 목록을 쓰려면 `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` 을 설정합니다.
 
 `/graceful-pause` 와 `/progress` 는 Claude Code 의 mod(Claude Mods, 얼리 액세스 이름 function hooks, `hooks/register.mjs`)로 등록되는 명령이라 구성요소 수에 넣지 않습니다. `commands/progress.md` 도 넣지 않습니다. 이 파일은 mod 가 없는 Claude Code 에서 `/progress` 를 받아 "mod 를 지원하지않는 claude code 버전입니다" 만 보여 주는 대체 명령이고, mod 가 있으면 mod 가 대신 처리합니다.
 

package/hooks/progress-plan.mjs

@@ -0,0 +1,328 @@
+/**
+ * What banker's /progress pane (progress.mjs) reads from text: a prompt as the person wrote it, and
+ * a plan file as steps. Plain functions of strings; the pane reads the files itself.
+ *
+ * A turn's text comes with the harness's tags: a slash command arrives as `<command-name>` and
+ * `<command-args>`, a background task's end as `<task-notification>`, a shell command as
+ * `<bash-input>`. Claude 5 models get no task list tool in Claude Code 2.1.296, so the plan a
+ * session writes (ralplan's, superpowers', ralph's PRD, ultragoal's goals) is what shows the work
+ * ahead.
+ *
+ * Every mod shares the engine's one hooks worker, and a plan may come from a cloned repository, so
+ * no step here takes more than linear time: a markdown plan is read to its first 256 Ki characters
+ * and each line to its first 1 Ki, a JSON plan's fields and a prompt's text are cut before they are
+ * cleaned, tags are found with indexOf, and no pattern backtracks over a line.
+ */
+
+// ── text on the pane ─────────────────────────────────────────────────────────
+
+// Characters a terminal draws two cells wide: Hangul, CJK, fullwidth forms, and emoji shown as
+// emoji by default. Combining marks, joiners and variation selectors take none.
+const WIDE = /[\u1100-\u115F\u2E80-\u303E\u3041-\u33FF\u3400-\u4DBF\u4E00-\u9FFF\uA000-\uA4CF\uAC00-\uD7A3\uF900-\uFAFF\uFE30-\uFE4F\uFF00-\uFF60\uFFE0-\uFFE6\u{20000}-\u{3FFFD}]|\p{Emoji_Presentation}/u;
+const NONE = /[\p{Mn}\p{Me}\u200B-\u200D\uFE0E\uFE0F]/u;
+const width = (c) => (NONE.test(c) ? 0 : WIDE.test(c) ? 2 : 1);
+
+// The cells a line of text takes on a terminal.
+export const cells = (text) => [...String(text)].reduce((n, c) => n + width(c), 0);
+
+// A line cut to `n` cells, its end an ellipsis where it was cut.
+export function fit(text, n) {
+  if (cells(text) <= n) return text;
+  if (n <= 0) return '';
+  let out = '';
+  let used = 0;
+  for (const c of text) {
+    if (used + width(c) > n - 1) break;
+    out += c;
+    used += width(c);
+  }
+  return `${out}…`;
+}
+
+// One line of plain text, cut to `n` characters. Control characters and lone surrogates go too: the
+// engine refuses a drawing that holds either. A long text is cut first, so cleaning it stays cheap.
+export const clip = (text, n) => {
+  const raw = String(text ?? '').slice(0, n * 4 + 1024);
+  const s = (raw.toWellFormed?.() ?? raw).replace(/\p{Cc}+/gu, ' ').replace(/\s+/g, ' ').trim();
+  const chars = [];
+  for (const c of s) {
+    chars.push(c);
+    if (chars.length > n) break;
+  }
+  return chars.length > n ? `${chars.slice(0, n - 1).join('')}…` : s;
+};
+
+// ── a prompt's text ──────────────────────────────────────────────────────────
+
+// Past this a prompt, its tags taken out, has nothing more for a title or a description.
+const PROMPT_CAP = 65536;
+
+// Tags the harness wraps around what it adds to a prompt: they go with what they hold.
+const HARNESS = ['system-reminder', 'local-command-caveat', 'local-command-stdout', 'local-command-stderr',
+  'bash-stdout', 'bash-stderr', 'command-message', 'command-name', 'command-args', 'bash-input'];
+
+// Messages the harness wraps in a tag with attributes: another session's, a teammate's.
+const WRAPPER = /^\s*<(cross-session-message|teammate-message)\b[^>]*>/;
+
+// The first `open … close` pair from `from` on, or null where there is none.
+function pair(text, open, close, from = 0) {
+  const start = text.indexOf(open, from);
+  if (start < 0) return null;
+  const stop = text.indexOf(close, start + open.length);
+  return stop < 0 ? null : { start, inner: text.slice(start + open.length, stop), end: stop + close.length };
+}
+
+const inner = (text, tag) => pair(text, `<${tag}>`, `</${tag}>`)?.inner.trim() ?? '';
+
+// The text with each pair of a harness tag taken out, with what it holds; an unclosed tag stays.
+function strip(text) {
+  let s = text;
+  for (const tag of HARNESS) {
+    let out = '';
+    let at = 0;
+    let m = pair(s, `<${tag}>`, `</${tag}>`);
+    while (m) {
+      out += `${s.slice(at, m.start)} `;
+      at = m.end;
+      m = pair(s, `<${tag}>`, `</${tag}>`, at);
+    }
+    s = out + s.slice(at);
+  }
+  return s;
+}
+
+// Another session's message is a prompt from there; a teammate's joins the work at hand.
+function message(text, m) {
+  const rest = text.slice(m[0].length);
+  const stop = rest.indexOf(`</${m[1]}>`);
+  const body = (stop < 0 ? rest : rest.slice(0, stop)).replace(/\s+/g, ' ').trim();
+  if (m[1] === 'teammate-message') return { kind: 'notice', text: clip(body, 200), status: 'message' };
+  return { kind: 'prompt', text: `[다른 세션] ${body}`.trim() };
+}
+
+// What a turn's text says: a notice (a background task's end, with its summary and status, or a
+// teammate's message), or a prompt, a slash command as `/name args` and a shell command as `! command`.
+export function readPrompt(raw) {
+  const text = String(raw ?? '');
+  if (/^\s*<task-notification>/.test(text)) {
+    return { kind: 'notice', text: clip(inner(text, 'summary'), 200), status: inner(text, 'status') };
+  }
+  const wrapped = WRAPPER.exec(text);
+  if (wrapped) return message(text, wrapped);
+  const command = inner(text, 'command-name');
+  const shell = inner(text, 'bash-input');
+  const lead = command ? `${command} ${inner(text, 'command-args')}` : shell ? `! ${shell}` : '';
+  return { kind: 'prompt', text: `${lead} ${strip(text)}`.slice(0, PROMPT_CAP).replace(/\s+/g, ' ').trim() };
+}
+
+// ── which files are plans ────────────────────────────────────────────────────
+
+const PLAN_PATHS = [
+  /\/\.omc\/plans\/[^/]+\.md$/,
+  /\/docs\/superpowers\/plans\/[^/]+\.md$/,
+  /\/\.claude\/plans\/[^/]+\.md$/,
+  /\/\.omc\/(?:state\/(?:[^/]+\/)*)?prd\.json$/,
+  /\/\.omc\/ultragoal\/goals\.json$/,
+];
+// Plan folders keep a plan's review rounds beside it (ralplan's `<plan>-critic-r2.md`,
+// `architect-review-r1.md`) and OMC's open questions: a name that ends so is no plan.
+const NOT_A_PLAN = [/(?:^|[-_])(?:critic|architect|review|verdict|feedback)(?:-r\d+)?\.md$/i, /^open-questions\.md$/i];
+
+export const isPlanPath = (path) => {
+  const p = String(path ?? '').replaceAll('\\', '/');
+  const name = p.split('/').at(-1);
+  return PLAN_PATHS.some((re) => re.test(p)) && !NOT_A_PLAN.some((re) => re.test(name));
+};
+
+// ── a plan file ──────────────────────────────────────────────────────────────
+
+const PLAN_CAP = 256 * 1024;
+const LINE_CAP = 1024;
+const MAX_PLAN_STEPS = 50;
+const BOM = /^\uFEFF/;
+const fileName = (path) => String(path).split(/[\\/]/).filter(Boolean).at(-1) ?? '';
+// Markdown's marks off a line: a link to its text, code spans' backticks, bold's asterisks.
+const plain = (line) => line.replace(/\[([^[\]]*)\]\([^()]*\)/g, '$1').replace(/\*\*|`/g, '');
+const step = (title, text, status) => ({
+  title: clip(plain(clip(title, 400)), 60), text: clip(plain(clip(text || title, 400)), 200), status,
+});
+
+const str = (v) => (typeof v === 'string' ? v : typeof v === 'number' ? String(v) : '');
+// A map's own entry: a key like `constructor` finds nothing.
+export const pick = (map, key) => (Object.hasOwn(map, key) ? map[key] : undefined);
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+// ultragoal's states, and the ones like them; one it does not know shows no state.
+const GOAL_STATUS = { complete: 'completed', completed: 'completed', in_progress: 'in_progress', active: 'in_progress',
+  pending: 'pending', failed: 'failed', review_blocked: 'blocked', blocked: 'blocked' };
+
+const storyStep = (st) => {
+  const id = str(st.id);
+  return { title: str(st.title) || id, text: [id, str(st.description)].filter(Boolean).join(': '), status: st.passes === true ? 'completed' : 'pending' };
+};
+const goalStep = (g) => ({ title: str(g.title) || str(g.id), text: str(g.objective), status: pick(GOAL_STATUS, str(g.status)) ?? null });
+
+// A ralph PRD (`stories` or `userStories`, done where they pass) or ultragoal's goals; items that
+// are not objects are passed over.
+function jsonPlan(path, text) {
+  let d;
+  try {
+    d = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (!isObject(d)) return null;
+  const stories = d.stories ?? d.userStories;
+  if (Array.isArray(stories)) return { title: str(d.title) || str(d.project) || fileName(path), records: stories.filter(isObject).map(storyStep) };
+  if (Array.isArray(d.goals)) return { title: 'ultragoal', records: d.goals.filter(isObject).map(goalStep) };
+  return null;
+}
+
+// The fence a line opens or closes (``` or ~~~), or ''. A run of backticks with a backtick after it
+// opens inline code, not a fence (CommonMark).
+function fenceMark(line) {
+  const m = /^ {0,3}(`{3,}|~{3,})/.exec(line);
+  if (!m) return '';
+  return m[1][0] === '`' && line.slice(m[0].length).includes('`') ? '' : m[1];
+}
+
+// The plan's lines as a reader sees them: a fenced code block's lines (to the fence that closes it,
+// or the end) are blank, so they are no heading or item.
+function proseLines(text) {
+  let fence = '';
+  return text.slice(0, PLAN_CAP).split(/\r?\n/).map((raw) => {
+    const line = raw.slice(0, LINE_CAP);
+    const mark = fenceMark(line);
+    if (!fence) {
+      fence = mark;
+      return mark ? '' : line;
+    }
+    if (mark[0] === fence[0] && mark.length >= fence.length && !line.slice(line.indexOf(mark) + mark.length).trim()) fence = '';
+    return '';
+  });
+}
+
+// The headings, each with where its section ends (the next heading of its level or above) and the
+// headings right under it: one pass, with a stack of the sections still open.
+function outline(lines) {
+  const heads = [];
+  const open = [];
+  lines.forEach((line, i) => {
+    const m = /^(#{1,6})[ \t]+([^\r\n]*)/.exec(line);
+    if (!m) return;
+    const h = { i, level: m[1].length, text: m[2].trim(), end: lines.length, subs: [] };
+    while (open.length && open.at(-1).level >= h.level) open.pop().end = i;
+    open.at(-1)?.subs.push(h);
+    open.push(h);
+    heads.push(h);
+  });
+  return heads;
+}
+
+// How far along a section's checkboxes say it is; null where it has none.
+function boxStatus(lines, h) {
+  let all = 0;
+  let done = 0;
+  for (let i = h.i + 1; i < h.end; i++) {
+    const m = /^\s*[-*+][ \t]+\[([ xX])\]/.exec(lines[i]);
+    if (!m) continue;
+    all += 1;
+    if (m[1] !== ' ') done += 1;
+  }
+  if (!all) return null;
+  return done === 0 ? 'pending' : done === all ? 'completed' : 'in_progress';
+}
+
+const TASK_HEAD = /^Task\s+\d+\s*[:.]\s*/i;
+const STEP_HEAD = /^(?:(?:phase|step|stage|milestone|sprint)\s*[\d.]+|단계\s*\d+|\d+(?:\.\d+)?\s*단계)/i;
+
+// Two or more headings of one level named as steps (Phase 1, Step 2, 3단계): the shallowest such level.
+function stepHeadings(heads) {
+  const byLevel = new Map();
+  for (const h of heads) {
+    if (!STEP_HEAD.test(h.text)) continue;
+    if (!byLevel.has(h.level)) byLevel.set(h.level, []);
+    byLevel.get(h.level).push(h);
+  }
+  const level = [...byLevel.keys()].sort((a, b) => a - b).find((l) => byLevel.get(l).length >= 2);
+  return byLevel.get(level) ?? [];
+}
+
+// Rules 1 and 2: superpowers' `Task N:` headings, else headings named as steps; each as far along
+// as the checkboxes in its section.
+function headedSteps(lines, heads) {
+  const tasks = heads.filter((h) => TASK_HEAD.test(h.text));
+  return (tasks.length ? tasks : stepHeadings(heads))
+    .map((h) => ({ title: h.text.replace(TASK_HEAD, ''), text: h.text, status: boxStatus(lines, h) }));
+}
+
+// Sections whose checkboxes test the work rather than lay out its steps.
+const CRITERIA = /수용\s*기준|인수\s*기준|완료\s*(?:기준|조건|판정)|검증\s*기준|acceptance|definition of done|criteria/i;
+
+// Rule 3: checkboxes at the top level of the text, outside the criteria sections.
+function boxSteps(lines, heads) {
+  const marks = new Int32Array(lines.length + 1);
+  for (const h of heads) {
+    if (!CRITERIA.test(h.text)) continue;
+    marks[h.i] += 1;
+    marks[h.end] -= 1;
+  }
+  const out = [];
+  let depth = 0;
+  lines.forEach((line, i) => {
+    depth += marks[i];
+    const m = depth > 0 ? null : /^[-*+][ \t]+\[([ xX])\][ \t]+([^\r\n]*)/.exec(line);
+    if (m) out.push({ title: m[2], text: m[2], status: m[1] === ' ' ? 'pending' : 'completed' });
+  });
+  return out;
+}
+
+const STEPS_SECTION = /단계|(?:작업|집행|실행|구현|진행)\s*(?:순서|흐름|계획)|\bsteps?\b|implementation|phases?|\btasks?\b|milestones?|로드맵|road ?map/i;
+
+// The numbered items of a section, up to `stop`.
+function numbered(lines, h, stop) {
+  const out = [];
+  for (let i = h.i + 1; i < stop; i++) {
+    const m = /^\d+[.)][ \t]+([^\r\n]*)/.exec(lines[i]);
+    if (m) out.push({ title: m[1], text: m[1], status: null });
+  }
+  return out;
+}
+
+// Rule 4: the first section named for the steps: its own numbered items (those before its first
+// sub-heading), else its sub-headings.
+function sectionSteps(lines, heads) {
+  for (const h of heads) {
+    if (h.level === 1 || STEP_HEAD.test(h.text) || !STEPS_SECTION.test(h.text)) continue;
+    const items = numbered(lines, h, h.subs[0]?.i ?? h.end);
+    if (items.length) return items;
+    if (h.subs.length) return h.subs.map((x) => ({ title: x.text, text: x.text, status: boxStatus(lines, x) }));
+  }
+  return [];
+}
+
+function markdownPlan(path, text) {
+  const lines = proseLines(text);
+  const heads = outline(lines);
+  let records = headedSteps(lines, heads);
+  if (!records.length) records = boxSteps(lines, heads);
+  if (!records.length) records = sectionSteps(lines, heads);
+  return { title: heads.find((h) => h.level === 1)?.text || fileName(path), records, cut: text.length > PLAN_CAP };
+}
+
+// A plan file as `{ title, steps, total, done, hasStates, cut }`: its first 50 steps, each
+// `{ title, text, status }` (status null where the file says none), how many it has and how many
+// are done, and whether the file was longer than what was read. Null for a JSON file that is no plan.
+export function parsePlan(path, text) {
+  const body = String(text).replace(BOM, '');
+  const plan = /\.json$/i.test(String(path)) ? jsonPlan(path, body) : markdownPlan(path, body);
+  if (!plan) return null;
+  const { records } = plan;
+  return {
+    title: clip(plain(clip(plan.title, 400)), 60),
+    steps: records.slice(0, MAX_PLAN_STEPS).map((r) => step(r.title, r.text, r.status)),
+    total: records.length,
+    done: records.filter((r) => r.status === 'completed').length,
+    hasStates: records.some((r) => r.status),
+    cut: Boolean(plan.cut),
+  };
+}