Intent Normalize

扫描现有项目，将 intent 和 planning 文件规范化到 IDD 标准。能自动修的直接修，不能修的打上状态让 TeamSwarm pickup。

设计原则

格式先行 — 所有文件先有 frontmatter，让系统能识别
能修则修 — 机械性问题直接修复（frontmatter、目录结构、命名）
不能修则标记 — 内容问题打上状态，后续由 TeamSwarm 或人处理
幂等 — 多次运行结果一致，已规范的文件不会被改动

工作流程

/intent-normalize [path]
        ↓
┌───────────────────────────────────┐
│  1. 扫描 intent/ 和 planning/     │
│     发现所有 .md 和 .yaml 文件     │
└─────────────┬─────────────────────┘
              ↓
┌───────────────────────────────────┐
│  2. 分析每个文件的合规状态         │
│     - 有无 frontmatter?           │
│     - 有无 Anchor?                │
│     - 目录结构是否完整?            │
└─────────────┬─────────────────────┘
              ↓
┌───────────────────────────────────┐
│  3. 自动修复机械问题               │
│     - 补 frontmatter              │
│     - 创建 records/ + INDEX.md    │
│     - 创建 _archive/, _data/      │
│     - 规范化文件命名               │
└─────────────┬─────────────────────┘
              ↓
┌───────────────────────────────────┐
│  4. 标记内容问题                   │
│     - 缺 Anchor → status: draft   │
│     - 超预算 → 标记 needs_critique │
│     - 无法分类 → status: draft     │
└─────────────┬─────────────────────┘
              ↓
┌───────────────────────────────────┐
│  5. 输出规范化报告                 │
└───────────────────────────────────┘

检查项与修复策略

自动修复（机械性，无需判断）

检查项	条件	修复动作
Intent frontmatter	INTENT.md 没有 frontmatter	添加 `status: active`（或根据内容推断）
Planning frontmatter	planning/ 下 .md 没有 frontmatter	添加 `type:` (从内容推断: idea/research/feedback/analysis)
Anchor 格式	Anchor 存在但格式不对（不是 blockquote）	修正为 `> Anchor: ...` 格式
records/ 目录	intent 目录下没有 records/	创建 `records/` + 空 `INDEX.md`
_archive/ 目录	intent/ 下没有 _archive/	创建 `intent/_archive/`
_data/ 目录	intent/ 下没有 _data/	创建 `intent/_data/`
TASK.yaml 格式	TASK.yaml 缺少 type 字段	添加 `type: one-shot`（默认）

标记 pickup（需要内容判断）

检查项	条件	标记动作
缺少 Anchor	INTENT.md 没有 Anchor 行	frontmatter 加 `needs: [anchor]`
超预算	行数 > 500	frontmatter 加 `needs: [critique]`
预算警告	300 < 行数 ≤ 500	frontmatter 加 `needs: [review]`
无 Assumes	内容中引用了其他 intent 但没有 Assumes 标签	frontmatter 加 `needs: [assumes]`
分类不明	planning 文件无法自动判断类型	`type: idea`（默认最安全）

`needs` 字段

needs 是 frontmatter 中的 pickup 信号，表示该文件需要后续处理：

---
status: active
needs: [anchor, critique]
---

TeamSwarm 扫描 needs 字段来自动调度后续 skill：

needs: [anchor] → 安排 /intent-interview 补充
needs: [critique] → 安排 /intent-critique 精简
needs: [review] → 安排 /intent-review
needs: [assumes] → 安排人工补充依赖声明

处理完成后，对应的 needs 项被移除。needs 为空时可以删掉整个字段。

Planning 类型推断

自动从文件内容推断 type:：

关键词/模式	推断类型
idea, concept, proposal, brainstorm, what if	`idea`
research, analysis, comparison, benchmark, study	`research`
feedback, user, complaint, request, survey	`feedback`
code analysis, refactor, migration, legacy, improvement	`analysis`
无法判断	`idea`（最安全的默认值）

执行细节

1. 扫描范围

默认扫描当前项目根目录下的：
- intent/           → 所有 INTENT.md 文件（递归，跳过 _archive/ 和 _data/）
- planning/         → 所有 .md 文件
- **/intent/        → 模块级 intent 目录

2. Frontmatter 注入

对没有 frontmatter 的文件，在文件头部插入：

Intent 文件：

---
status: active
---

如果文件看起来已经实现（有对应的代码目录和测试），推断为：

---
status: implemented
---

Planning 文件：

---
type: research
---

3. 推断 status 的启发式规则

信号	推断 status
有 TASK.yaml 且 status: done	`implemented`
有对应的 src/ 目录且文件最近没修改	`implemented`
文件内容很少（< 50 行）或明显不完整	`active`（+ `needs: [anchor]`）
默认	`active`

4. 幂等保证

已有正确 frontmatter 的文件不修改
已有 records/ 的不重建
needs 字段只添加不覆盖（合并已有的）
每次运行结果相同

输出

规范化报告

# Intent Normalize Report

> 项目: my-project
> 扫描时间: 2026-02-06

## 统计

| 类型 | 扫描 | 已规范 | 自动修复 | 需 pickup |
|------|------|--------|----------|-----------|
| Intent 文件 | 15 | 8 | 5 | 2 |
| Planning 文件 | 7 | 2 | 4 | 1 |
| 目录结构 | — | — | 3 | — |

## 自动修复（已完成）

1. ✅ `intent/kernel/proc/INTENT.md` — 添加 frontmatter `status: active`
2. ✅ `intent/kernel/afs/INTENT.md` — 添加 frontmatter `status: implemented`
3. ✅ `planning/v2-ideas.md` — 添加 frontmatter `type: idea`
4. ✅ `planning/legacy-analysis.md` — 添加 frontmatter `type: analysis`
5. ✅ `intent/kernel/proc/records/` — 创建目录 + INDEX.md
6. ✅ `intent/_archive/` — 创建目录
7. ✅ `intent/_data/` — 创建目录

## 需要 Pickup（已标记）

| 文件 | needs | 建议 |
|------|-------|------|
| `intent/ash/INTENT.md` | `[anchor, critique]` | 缺少 Anchor，612 行超预算 |
| `intent/surfaces/INTENT.md` | `[anchor]` | 缺少 Anchor |
| `planning/random-notes.md` | — | 无法分类，默认 type: idea |

使用

基本用法

/intent-normalize

扫描并规范化当前项目。

指定路径

/intent-normalize intent/kernel/

只规范化特定目录。

Dry run

/intent-normalize --dry-run

只报告，不做任何修改。

与其他命令配合

/intent-normalize       # 先规范化格式（本命令）
    ↓
TeamSwarm pickup        # 自动调度 needs 中的后续 skill
    ↓
/intent-interview       # 处理 needs: [anchor]
/intent-critique        # 处理 needs: [critique]
/intent-review          # 处理 needs: [review]
    ↓
/intent-check           # 最终合规检查

intent-normalize