Skip to content

Commit 2c3d270

Browse files
fix(feedback-consume): 两 bundle 25 条裁定落地——github#9/github#10 直接修 + improve-skills github#3/github#4/github#6
- progress-engine coverage:phase 节点退出闭合树(tree_items 排除 phase,新增 phase_nodes 字段) ——修复"台账条目 vs 含阶段分解树"恒假告警(实测 8+4 场景 closure 由 False 转 True) - check-coherence:图源优先读 assets/*.puml(正文残留源码块记 FAIL;引用图⇄.puml 同名双向配对; 无 assets 退回旧正文形态)——对齐 consistency-rules 已定的 assets 交付规范,消除非交互必误报 - improve-skills:Step5 增"禁叙述文档自身历史"具体禁令(L2 承载改写示例)、HC5 增检测脚本反向用例、 新增 HC8 收尾提交核对暂存区;形状门 exit 0(4958/5000) - draw-plantuml github#11 经核已全部修复于现行源(UA/回退链/monochrome/语法坑文档),acknowledge-only
1 parent fabaf98 commit 2c3d270

8 files changed

Lines changed: 122 additions & 14 deletions

File tree

‎.specify/skills/improve-skills/SKILL.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ Batch procedure, ownership resolution, and routing rationale: [`./references/loo
7171
- Update `./references/`, `./scripts/`, or `./assets/` only when the evidence shows they will reduce future mistakes.
7272
- When Step 4 extracted deterministic logic into a new `${SKILL_HOME}/scripts/` script, list that script in the Resources table so the executable resource stays discoverable.
7373
- Avoid adding process logs, changelogs, or full retrospectives to the Skill; distill only reusable lessons.
74+
- **Never narrate the document's own history**: corrections state the current fact only — never `旧文档断言…已证伪` / `重要勘误` / `本条不再是限制` frames (exceptions: confidence markers, misuse guards). Rewrite examples: [`./references/skill-slimming-principles.md`](./references/skill-slimming-principles.md) `## No History Narration`.
7475
- **Rename/removal downstream-wiring checklist**: a rename/consolidation/removal is not done until every downstream pointer moves with it (obsolete-skills list, contract tests, skills-count list, feature history, dogfooded artifacts), and both mirrors are synced and verified byte-equal. Five-step checklist and the move-then-edit ordering rule: [`./references/loop-playbook.md`](./references/loop-playbook.md) `## Step 5`.
7576

7677
6. **Validate the improvement loop**
@@ -171,9 +172,10 @@ Objective conditions for finishing a loop. Each is checkable, not a matter of ju
171172
2. **New detail lands in L2/L3 by default.** Do not add worked examples, full command sequences, or multi-line snippets to `SKILL.md` — write them into `./references/` or `./scripts/` and leave a one-line pointer with an anchor in the body.
172173
3. **Evidence before defect.** Do not label anything a defect without an observed symptom (error text, wrong output, user correction, artifact). `Unobserved` findings are recorded only; counting signals alone never becomes an optimization point.
173174
4. **Capability verified before it is documented.** Before writing a delegation path, data table, or coverage claim, read the delegate's real surface (`--help`, contract, cached facts) and encode honest limitation branches. Do not write values or capabilities from memory.
174-
5. **Reference code is executed, not eyeballed.** Any snippet or script added/changed must be run (or traced line-by-line against the documented API). "File exists" and "links resolve" are not validation — state explicitly when runtime validation is deferred.
175+
5. **Reference code is executed, not eyeballed.** Any snippet or script added/changed must be run (or traced line-by-line against the documented API). "File exists" and "links resolve" are not validation — state explicitly when runtime validation is deferred. For detection scripts also run a **reverse case on a domain-legitimate sample** (must NOT flag required syntax) — catching bad samples alone can induce deleting required syntax.
175176
6. **Removal preserves content.** Every slimming move is delete-and-absorb in the same edit; never delete a section and defer relocating its substance.
176177
7. **No claim of "fixed" without before/after.** Improvement outcomes are decided by the intervention ledger's next-run comparison, not by asserting the edit works.
178+
8. **Wrap-up commits verify the staging area.** Before any loop-end commit, `git status --short` and confirm only this loop's files are staged; unstage unrelated pre-staged entries or commit by explicit pathspec — never `git add -A`.
177179

178180
## Feedback
179181

‎.specify/skills/improve-skills/references/skill-slimming-principles.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -207,3 +207,18 @@ A slim `SKILL.md` makes the agent's behavior **predictable and auditable**:
207207
Slimming also has a **measured compliance payoff**. Skill loading is progressive across four levels: **L0** frontmatter `description` (always in context), **L1** `SKILL.md` body (loaded on trigger; keep ≤ ~5K tokens), **L2** `references/` (read on demand), **L3** `scripts/` (executed, near-zero token cost). Hard constraints buried mid-way through a bloated L1 body sit in the attention low-zone and get violated at a measurably higher rate (~72–80% vs ~100% when kept compact and well-placed — see [constraint-placement.md](./constraint-placement.md)). Every manual paragraph left in L1 dilutes the rules that must survive there; moving it to L2/L3 is compliance protection, not just tidiness.
208208

209209
Slimming is not a one-time refactor; it is a steady-state discipline applied every time the Skill changes.
210+
211+
## No History Narration
212+
213+
A Skill document states current facts for the next executor. Corrections replace the
214+
wrong claim outright; they do not report the replacement.
215+
216+
- WRONG (history narration — delete): `> 旧文档断言「个人身份消息无法撤回」已证伪——实测该表明示不要重试。`
217+
- RIGHT (current fact only): `个人身份消息撤回按平台返回码分诊:不支持时直接告知用户,不要重试。`
218+
- WRONG: `(重要勘误:本条不再是限制)`
219+
- RIGHT: delete the line; if a misuse guard is genuinely needed, state it forward: `X 命令已下线,改用 Y。`
220+
221+
Keep two forward-looking markers — they describe current state, not change history:
222+
223+
- confidence markers: `未实测(待验证)`, `文档口径,待二进制实测校准`
224+
- misuse guards: `该 flag 位置与实测不符,以实测为准(示例见下)`

‎.specify/skills/summarize-project/scripts/check-coherence.py‎

Lines changed: 35 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -151,7 +151,7 @@ def check_blocks(text: str, f: Findings, report: dict) -> None:
151151
report["blocks"] = []
152152
report["has_wbs"] = False
153153
if not blocks:
154-
f.fail("CG-0", "报告中没有任何 plantuml 源码块(图表即文本原则要求源码嵌入)")
154+
f.fail("CG-0", "没有任何 plantuml 图源(assets/ 无 .puml 且正文无源码块)→ 图源⇄渲染产物须同名配对交付")
155155
return
156156
for idx, src in enumerate(blocks, 1):
157157
kind = block_kind(src)
@@ -342,12 +342,15 @@ def check_dates(prose: str, f: Findings, report: dict) -> None:
342342
f.fail("DATE", f"非 yyyy-mm-dd 日期写法:{b}")
343343

344344

345-
def check_selfcontained(text: str, f: Findings, report: dict, base_dir: pathlib.Path) -> None:
345+
def check_selfcontained(text: str, f: Findings, report: dict, base_dir: pathlib.Path,
346+
puml_files: list | None = None) -> None:
346347
"""目录自包含检查:报告以相对路径引用交付目录内的渲染图片(`![…](assets/x.svg)`)。
347348
348349
- 相对路径引用的文件必须**存在于交付目录内**(以报告所在目录为根);
349350
- 引用交付目录外的文件(`..` 逃逸、绝对路径)或外链 URL(http/https 等)→ FAIL;
350-
- 每个 plantuml 源码块之后应有其渲染图引用(或渲染失败告示)。
351+
- 每个 plantuml 源码块之后应有其渲染图引用(或渲染失败告示);
352+
- assets 形态(源码落 `assets/*.puml`):引用图 ⇄ `.puml` 图源同名双向配对
353+
(每张引用图有同名图源;每个图源被正文引用或有渲染失败告示)。
351354
"""
352355
base = base_dir.resolve()
353356
imgs = re.findall(r"!\[[^\]]*\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)", text)
@@ -395,6 +398,20 @@ def check_selfcontained(text: str, f: Findings, report: dict, base_dir: pathlib.
395398
f"{n_src} 个 plantuml 块,但只有 {n_img} 个渲染图引用 + {n_svg} 个内联 SVG + {n_warn} 条渲染失败告示"
396399
f" → 存在未渲染的裸源码块",
397400
)
401+
if puml_files:
402+
stems = {pf.stem for pf in puml_files}
403+
for u in ok_refs:
404+
if u.startswith("data:"):
405+
continue
406+
if pathlib.PurePosixPath(u).stem not in stems:
407+
f.fail("SELF", f"引用图 `{u}` 在 assets/ 内无同名 `.puml` 图源 → 图源⇄渲染产物须同名配对")
408+
# referenced = rendered refs (ok) + refs whose render artifact is missing
409+
# (already flagged) — both prove the .puml is referenced by the body.
410+
referenced_stems = {pathlib.PurePosixPath(u).stem
411+
for u in ok_refs + missing}
412+
for pf in puml_files:
413+
if pf.stem not in referenced_stems:
414+
f.fail("SELF", f"assets/{pf.name} 未被正文渲染图引用(也无渲染失败告示)→ 图源⇄渲染产物须同名配对")
398415

399416

400417
def check_id_namespace(prose: str, f: Findings, report: dict) -> None:
@@ -435,11 +452,24 @@ def main() -> int:
435452

436453
f = Findings()
437454
report: dict = {"report": str(path)}
438-
check_blocks(text, f, report) # 图元/图例:需要 plantuml 源码,用全文
455+
# 图源优先读 assets/*.puml(consistency-rules:源码只作为 .puml 文件交付,正文不出现
456+
# 源码块);assets/ 无 .puml 时退回正文残留围栏块(旧单文件形态兼容)。
457+
assets_dir = path.parent / "assets"
458+
puml_files = sorted(assets_dir.glob("*.puml")) if assets_dir.is_dir() else []
459+
if puml_files:
460+
diagram_text = "\n".join(
461+
"```plantuml\n" + pf.read_text(encoding="utf-8") + "\n```"
462+
for pf in puml_files)
463+
residual = len(re.findall(r"```plantuml\n", text))
464+
if residual:
465+
f.fail("SELF", f"正文残留 {residual} 个 plantuml 源码块 → 源码只作为 assets/*.puml 交付")
466+
else:
467+
diagram_text = text
468+
check_blocks(diagram_text, f, report) # 图元/图例:需要 plantuml 源码,用图源
439469
check_numbers(prose, f, report) # 数字:用正文(已去代码块 + SVG)
440470
check_coverage(prose, f, report) # 覆盖完整性:用正文
441471
check_dates(prose, f, report) # 日期:用正文
442-
check_selfcontained(text, f, report, path.parent) # 目录自包含:相对引用须落在交付目录内,用全文
472+
check_selfcontained(text, f, report, path.parent, puml_files) # 目录自包含:相对引用须落在交付目录内,用全文
443473
check_id_namespace(prose, f, report) # 裸编号:用正文
444474

445475
c = f.counts()

‎.specify/skills/summarize-project/scripts/progress-engine.py‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1518,7 +1518,13 @@ def coverage_block(data: dict, items: list):
15181518
excluded = int(cov.get("excluded", 0) or 0)
15191519
truncated = int(cov.get("granularity_truncated", 0) or 0)
15201520
unattributed = int(cov.get("unattributed", 0) or 0)
1521-
tree_items = len([it for it in items if it["type"] != "milestone"])
1521+
# Phases are inferred groupings, not ledger candidates (the candidate_total
1522+
# counts source-label-level entries only) — counting phase nodes into the
1523+
# closure tree against an items-only total produced a permanent false
1524+
# warning (feedback consume 2026-08-17). They are reported separately.
1525+
phase_nodes = len([it for it in items if it.get("type") == "phase"])
1526+
tree_items = len([it for it in items
1527+
if it["type"] not in ("milestone", "phase")])
15221528
expected = total - excluded - truncated
15231529
denom = total - excluded
15241530
attributed = denom - unattributed
@@ -1529,6 +1535,7 @@ def coverage_block(data: dict, items: list):
15291535
"granularity_truncated": truncated,
15301536
"unattributed": unattributed,
15311537
"tree_items": tree_items,
1538+
"phase_nodes": phase_nodes,
15321539
"closure_equation": "%d − %d − %d = %d" % (total, excluded, truncated, expected),
15331540
"closure_ok": expected == tree_items,
15341541
"closure_note": (

‎skills/improve-skills/SKILL.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ Batch procedure, ownership resolution, and routing rationale: [`./references/loo
7171
- Update `./references/`, `./scripts/`, or `./assets/` only when the evidence shows they will reduce future mistakes.
7272
- When Step 4 extracted deterministic logic into a new `${SKILL_HOME}/scripts/` script, list that script in the Resources table so the executable resource stays discoverable.
7373
- Avoid adding process logs, changelogs, or full retrospectives to the Skill; distill only reusable lessons.
74+
- **Never narrate the document's own history**: corrections state the current fact only — never `旧文档断言…已证伪` / `重要勘误` / `本条不再是限制` frames (exceptions: confidence markers, misuse guards). Rewrite examples: [`./references/skill-slimming-principles.md`](./references/skill-slimming-principles.md) `## No History Narration`.
7475
- **Rename/removal downstream-wiring checklist**: a rename/consolidation/removal is not done until every downstream pointer moves with it (obsolete-skills list, contract tests, skills-count list, feature history, dogfooded artifacts), and both mirrors are synced and verified byte-equal. Five-step checklist and the move-then-edit ordering rule: [`./references/loop-playbook.md`](./references/loop-playbook.md) `## Step 5`.
7576

7677
6. **Validate the improvement loop**
@@ -171,9 +172,10 @@ Objective conditions for finishing a loop. Each is checkable, not a matter of ju
171172
2. **New detail lands in L2/L3 by default.** Do not add worked examples, full command sequences, or multi-line snippets to `SKILL.md` — write them into `./references/` or `./scripts/` and leave a one-line pointer with an anchor in the body.
172173
3. **Evidence before defect.** Do not label anything a defect without an observed symptom (error text, wrong output, user correction, artifact). `Unobserved` findings are recorded only; counting signals alone never becomes an optimization point.
173174
4. **Capability verified before it is documented.** Before writing a delegation path, data table, or coverage claim, read the delegate's real surface (`--help`, contract, cached facts) and encode honest limitation branches. Do not write values or capabilities from memory.
174-
5. **Reference code is executed, not eyeballed.** Any snippet or script added/changed must be run (or traced line-by-line against the documented API). "File exists" and "links resolve" are not validation — state explicitly when runtime validation is deferred.
175+
5. **Reference code is executed, not eyeballed.** Any snippet or script added/changed must be run (or traced line-by-line against the documented API). "File exists" and "links resolve" are not validation — state explicitly when runtime validation is deferred. For detection scripts also run a **reverse case on a domain-legitimate sample** (must NOT flag required syntax) — catching bad samples alone can induce deleting required syntax.
175176
6. **Removal preserves content.** Every slimming move is delete-and-absorb in the same edit; never delete a section and defer relocating its substance.
176177
7. **No claim of "fixed" without before/after.** Improvement outcomes are decided by the intervention ledger's next-run comparison, not by asserting the edit works.
178+
8. **Wrap-up commits verify the staging area.** Before any loop-end commit, `git status --short` and confirm only this loop's files are staged; unstage unrelated pre-staged entries or commit by explicit pathspec — never `git add -A`.
177179

178180
## Feedback
179181

‎skills/improve-skills/references/skill-slimming-principles.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -207,3 +207,18 @@ A slim `SKILL.md` makes the agent's behavior **predictable and auditable**:
207207
Slimming also has a **measured compliance payoff**. Skill loading is progressive across four levels: **L0** frontmatter `description` (always in context), **L1** `SKILL.md` body (loaded on trigger; keep ≤ ~5K tokens), **L2** `references/` (read on demand), **L3** `scripts/` (executed, near-zero token cost). Hard constraints buried mid-way through a bloated L1 body sit in the attention low-zone and get violated at a measurably higher rate (~72–80% vs ~100% when kept compact and well-placed — see [constraint-placement.md](./constraint-placement.md)). Every manual paragraph left in L1 dilutes the rules that must survive there; moving it to L2/L3 is compliance protection, not just tidiness.
208208

209209
Slimming is not a one-time refactor; it is a steady-state discipline applied every time the Skill changes.
210+
211+
## No History Narration
212+
213+
A Skill document states current facts for the next executor. Corrections replace the
214+
wrong claim outright; they do not report the replacement.
215+
216+
- WRONG (history narration — delete): `> 旧文档断言「个人身份消息无法撤回」已证伪——实测该表明示不要重试。`
217+
- RIGHT (current fact only): `个人身份消息撤回按平台返回码分诊:不支持时直接告知用户,不要重试。`
218+
- WRONG: `(重要勘误:本条不再是限制)`
219+
- RIGHT: delete the line; if a misuse guard is genuinely needed, state it forward: `X 命令已下线,改用 Y。`
220+
221+
Keep two forward-looking markers — they describe current state, not change history:
222+
223+
- confidence markers: `未实测(待验证)`, `文档口径,待二进制实测校准`
224+
- misuse guards: `该 flag 位置与实测不符,以实测为准(示例见下)`

0 commit comments

Comments
 (0)