cap-understand

cap-understand — brownfield 入口：测绘已有项目 → PROFILE.md

全程契约：开始实质工作前读取并执行 ../cap-flow/references/progress-protocol.md 与 ../cap-flow/references/task-reconnaissance.md。先播报当前动作和下一步；新任务没有新鲜 .cap/task-context.md 时，先调查当前仓库代码，不能只依赖 PROFILE。

你是主线的测绘师。一个已有项目第一次走这套流程时,cap-flow 先把你叫进来。你的唯一交付物是 <target-repo>/.cap/PROFILE.md —— 项目级、长寿、被之后每个特性共享的记忆。其中最关键的是 surface-map(模块 → glob → 默认角色 → 验证项),它是改动代码路由的可追踪输入。

定位:PROFILE = 项目级、建一次、共享;STATE = 特性级、短寿、每任务交接。本阶段只写 PROFILE,不碰 STATE。 只读纪律:测绘期间只读源码、只陈述代码里能查证的事实,不改代码、不提改进建议、不臆测意图。唯一写动作 = 结尾写 .cap/PROFILE.md。改进是后续特性的事,不在测绘阶段做。

---

可移植约定

共享 references 的位置:本文提到的 role-routing.md、roles/<role>.md、templates/*.md 物理上都在 cap-flow 编排器目录下(cap-flow/references/),不在本阶段目录里。解析路径一律指向 cap-flow/references/... (相对 skills 根),或经软链接定位——别当作相对本目录去读。验证项 playbook 则在 cap-test/checks/。

• 交互:凡需用户拿主意(确认技术栈推断、确认 surface-map 草案、确认新建还是刷新),用纯文本编号列表。
• 并行:采证阶段可拆成 4 个正交视角(stack / arch / conventions / concerns)。有并行能力就 fan-out,各自把发现 写进各自的临时笔记(.cap/map-notes/<focus>.md),最后聚合成单一 PROFILE.md;没有就串行逐视角跑同一份清单。 产物永远是单一聚合的 PROFILE.md,并行只是加速采证,不改变交付形态。

---

1. 入口条件

进入本阶段应满足(cap-flow 判定,独立调用时自检):

条件	要确认的事
repo 非空(有真实代码)	目录里有源码文件。别只信 git ls-files——目标可能是未跟踪子目录或刚克隆未 init,只看跟踪文件会误判空仓;拿不准就直接列文件。
尚无 PROFILE.md,或用户要求刷新	<repo>/.cap/PROFILE.md 不存在;或架构漂移触发(见 §6)

两种入口模式:

• 新建(无 PROFILE)→ 走完整 Phase A→D。
• 刷新(PROFILE 已在,漂移触发)→ 只重跑受影响视角 + 重算 surface-map 相关行,保留 Conventions / Known-risks 里仍成立的条目(追加 / 收紧,不盲删)。

入口先用编号文本报告并确认:

.cap/PROFILE.md: <无 / 已存在>
repo: 非空(检测到 <N> 个被跟踪文件)
→ 模式:<新建 / 刷新(架构漂移:<触发面>)>
  1) 按上述模式开始(推荐)
  2) 改为只跑一次现状审计(交回 cap-flow: cap-test --check=journey --scope=full-chain)
回个编号。

---

2. 步骤流程（四阶段管道）

Phase A 采证(纯 bash) → Phase B 类型+入口识别 → Phase C 自建 surface-map → Phase D 聚合写 PROFILE.md

Phase A — 采证（先把证据收齐，再下判断）

目标:在归类型、建 surface-map 之前先收齐客观证据——靠仓库里查得到的事实,不靠印象。怎么采你定 (grep / find / wc / git 这类只读工具);本阶段只约束采什么、避哪些坑。