maestro-flow-one 0.2.35 → 0.2.37

package/maestro-flow/agents/role-design-author.md

@@ -190,9 +190,11 @@ All behavioral statements MUST use MUST / SHOULD / MAY / MUST NOT / SHOULD NOT.
 - [ ] No interrogative sentences (all declarative)
 - [ ] system-architect: §3 contains "Data Model" and "State Machine" headings
 
-## Return Protocol
+## Completion Sequence (MANDATORY ORDER)
 
-Report completion with this structure (the orchestrator reads ONLY this, not the files):
+**Step A — Write files**: Use the Write tool to create every file under `output_dir/`. Then verify with Glob that `analysis.md` and each `analysis-F-*.md` exist on disk. If any Write call fails, emit `TASK BLOCKED` and stop.
+
+**Step B — Report summary**: ONLY AFTER Step A files are confirmed on disk, emit this text (the orchestrator reads this summary to track progress — it does NOT substitute for the files):
 
 ```
 TASK COMPLETE
@@ -205,7 +207,7 @@ rfc_keyword_count: {N}
 total_lines: {sum across all files}
 ```
 
-If blocked: report blocker with `TASK BLOCKED` prefix.
+Never emit `TASK COMPLETE` without files on disk. If blocked: report with `TASK BLOCKED` prefix.
 
 ## NEVER
 

package/maestro-flow/commands/manage/harvest.md

@@ -44,6 +44,7 @@ Follow '~/.maestro/workflows/harvest.md' Stages 1-8 in order.
 2. **Dedup before write** — check harvest-log.jsonl and existing stores before each write.
 3. **Never modify source artifacts** — harvest is purely extractive.
 4. **Dedup contract with parallel writers** — when appending to `issues.jsonl`, set `source: "harvest"` on each row so concurrent writers (e.g. `manage-issue-discover` with `source: "discover"`) can be distinguished and deduplicated.
+5. **Conflict pre-check on spec routing** — when routing to spec (Stage 6b), compare new entry against existing specs with same keywords/category. If semantic conflict detected, set `confidence="low"` on the new entry and log conflict note. Use `maestro spec conflict mark` if contradiction is clear.
 
 Extraction patterns, classification rules, routing infrastructure, and fragment ID scheme defined in workflow harvest.md.
 
@@ -58,6 +59,8 @@ Extraction patterns, classification rules, routing infrastructure, and fragment
 | Wiki graph needs linking | `/manage-wiki connect --fix` |
 | Issues created | `/manage-issue list --source harvest` |
 | Specs extracted | `/spec-load --role implement` |
+| Specs extracted (冲突审查) | `/manage-knowledge-audit --scope spec` — 新写入的 spec 可能与现有条目矛盾 |
+| Spec 冲突标记已存在 | `maestro spec conflict list` — 查看当前冲突状态 |
 | Full phase retrospective | `/quality-retrospective` |
 </completion>
 

package/maestro-flow/commands/manage/knowledge-audit.md

@@ -43,10 +43,12 @@ Follow `~/.maestro/workflows/knowledge-audit.md` Stages 1-8 in order.
 **GATE 1: Load → Detect** (Stages 1-2 → Stage 4)
 - REQUIRED: Scope 解析通过，互斥标志校验完成。
 - REQUIRED: 三存储按 scope 加载完成。
+- REQUIRED: 加载已有冲突标记: `maestro spec conflict list` → 合并到 finding 池。
 - BLOCKED if scope 非法或存储不可读: E001/E002。
 
 **GATE 2: Detect → Decision** (Stage 4 → Stage 5)
 - REQUIRED: Finding 池按 P0/P1/P2 分级输出。
+- REQUIRED: 已标记 `contested` 的条目自动归入 P0 finding（来源: conflict-marker）。
 - REQUIRED: 未 harvest 的 artifact 删除前触发抢救确认（W002）。
 - BLOCKED if finding 为空: 无需淘汰，直接输出报告。
 
@@ -61,6 +63,31 @@ Follow `~/.maestro/workflows/knowledge-audit.md` Stages 1-8 in order.
 - **Deprecate over delete**: 文本存储首选 `status="deprecated"`，保留历史。
 - **Purge 仅 artifact**: `--purge` 不作用于 spec/knowhow。
 - **Rescue before delete**: 未抽取 artifact 删除前强制提示先 `/manage-harvest`。
+
+### Conflict Resolution Integration
+
+四态决策（扩展自三态 keep/deprecate/delete）：
+
+| 动作 | 适用场景 | 执行 |
+|------|---------|------|
+| `keep` | 内容正确，无需变更 | 写 audit-log ignore 记录 |
+| `contest` | 矛盾真实存在，需进一步审查 | `maestro spec conflict mark <file> <line> --note "<evidence>"` |
+| `deprecate` | 内容过时或被取代 | 注入 `status="deprecated"` + `maestro spec conflict clear <file> <line>` |
+| `delete` | 内容明确错误 | 移除 entry + `maestro spec conflict clear <file> <line>` |
+
+**关键**: deprecate/delete 执行时，如果目标条目有 conflict-marker，必须同步调用 `maestro spec conflict clear` 清除标记，避免悬空冲突。
+
+### Code-as-Truth 校验（审查核心原则）
+
+**代码是唯一真理源。** Spec/knowhow 中的任何声明，必须与代码实际行为一致。
+
+当 detector 发现 spec 条目声称某行为/规则时：
+1. **代码校验**: grep/read 代码中相关实现，确认 spec 声明是否与代码一致
+2. **不一致处理**:
+   - 代码正确、spec 过时 → `deprecate` 或 `delete` spec 条目
+   - 代码正确、spec 不完整 → `contest` 并建议补充
+   - 代码有 bug、spec 正确 → `keep` spec，生成 issue 修代码
+3. **禁止**: 仅凭 spec 文本判断正确性。每个 finding 的 evidence 必须包含代码引用（文件:行号）
 </execution>
 
 <completion>
@@ -71,6 +98,8 @@ Follow `~/.maestro/workflows/knowledge-audit.md` Stages 1-8 in order.
 | 复审淘汰记录 | 查看 `audit-report-{date}.md` |
 | 抢救未抽取 artifact | `/manage-harvest <artifact-id>` |
 | 验证 spec 现状 | `/spec-load --role implement` |
+| 查看冲突标记 | `maestro spec conflict list` |
+| 清除已解决冲突 | `maestro spec conflict clear-all <file>` |
 | 周期巡检 | `--scope all --report` |
 </completion>
 

package/maestro-flow/commands/quality/review.md

@@ -50,6 +50,7 @@ Each artifact's type determines its outputs at `.workflow/{a.path}/`:
 - Codebase docs: `.workflow/codebase/ARCHITECTURE.md` → component boundaries, layer rules
 - Wiki constraints: `maestro search "architecture constraint" --json` → documented decisions
 - Specs: `maestro spec load --category review` → review standards, checklists, knowhow tools
+- Conflict state: `maestro spec conflict list` → 当前已标记冲突的 spec 条目（review 时优先关注）
 - Role knowledge: `maestro search --category review` → select relevant → `maestro wiki load`
 
 **Output**: `REVIEW_DIR = .workflow/scratch/{YYYYMMDD}-review-P{N}-{slug}/` (P{N} = phase number, enables directory-level identification as state.json fallback)
@@ -73,6 +74,7 @@ Follow '~/.maestro/workflows/review.md' completely.
 - REQUIRED: review.json written with findings, severity distribution, and verdict.
 - REQUIRED: Issues auto-created based on level thresholds.
 - REQUIRED: index.json updated with review status.
+- REQUIRED: Spec conflict check — if any finding directly contradicts a loaded spec entry (code behavior ≠ spec rule), suggest `maestro spec conflict mark` on the spec entry. Code is the single source of truth.
 
 **Output writes to REVIEW_DIR** (not EXEC_DIR):
 - `REVIEW_DIR/review.json` — findings, severity distribution, verdict
@@ -127,6 +129,7 @@ maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
 | PASS verdict | `/quality-test {phase}` |
 | WARN verdict (non-blocking issues) | `/quality-test {phase}` (proceed with caveats) |
 | BLOCK verdict (critical findings) | `/maestro-plan {phase} --gaps` (fix first) |
+| Spec contradictions found | `maestro spec conflict list` → `/manage-knowledge-audit --scope spec` |
 | Want code cleanup | `/quality-refactor {phase}` |
 </completion>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow-one",
-  "version": "0.2.35",
+  "version": "0.2.37",
   "description": "All Maestro workflow commands as a single Claude Code skill — intent routing, decision gates, minimal closed-loop chains",
   "bin": {
     "maestro-flow": "bin/maestro-flow.js"