verify-before-commit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: verify-before-commit

WHAT

Purpose và context

目的与上下文

Purpose: gate every commit — typecheck, lint, test, smoke trước commit; sau commit promote draft lên wiki và đóng vòng đời task.
Trigger (when to use): After any impl task, before
```
git commit
```
.
Non-goals: không viết tính năng mới, không bỏ qua bước nào vì "thay đổi nhỏ", không tự đổi state-machine task ngoài lệnh
```
code-logger.py
```
đã khai.

目的： 为每次 commit 设置门禁——在 commit 前执行 typecheck、lint、test、smoke；commit 后将 draft 发布到 wiki，并结束 task 生命周期。
触发时机（何时使用）： 任何 impl 任务完成后、
```
git commit
```
之前。
非目标： 不编写新功能；不因“改动很小”而跳过任何步骤；除已声明的
```
code-logger.py
```
命令外，不自行更改 task 的 state-machine。

Mental model

diff → typecheck → lint → test → qc-regression → task_lifecycle gate → smoke → commit (why) → promote draft (+ ## Origin) → log + index → task state=done

diff → typecheck → lint → test → qc-regression → task_lifecycle gate → smoke → commit (why) → promote draft (+ ## Origin) → log + index → task state=done

。

Input và output contract

输入与输出约定

	Field	Required?	Ý nghĩa
In	thay đổi code đã impl	có	đối tượng gate
In	draft khớp feature trong `llmwiki/wiki/sources/draft/`	không	không có (hotfix/refactor) → ghi "no draft — <reason>" vào log
In	`task: T-…` trong frontmatter draft	không	không có → skip step 8 (fail-open)
Out	commit	có	message nói why, không what
Out	trang wiki đã promote có `## Origin`	khi có draft	`concepts/` hoặc `sources/`
Out	`llmwiki/wiki/log.md` + `index.md`	có	cập nhật

	字段	是否必需	含义
In	已实现的代码变更	是	gate 的对象
In	`llmwiki/wiki/sources/draft/` 中与 feature 匹配的 draft	否	如果没有（hotfix/refactor）→ 在 log 中写入 `no draft — <reason>`
In	draft frontmatter 中的 `task: T-…`	否	如果没有 → 跳过步骤 8（fail-open）
Out	commit	是	message 说明 why，而不是 what
Out	已发布且包含 `## Origin` 的 wiki 页面	有 draft 时	`concepts/` 或 `sources/`
Out	`llmwiki/wiki/log.md` + `index.md`	是	更新

Rules và capabilities

规则与能力

RULE-01 (MUST): All steps mandatory. No exceptions.
RULE-02 (MUST): Post-commit — mandatory, never skip.
Capabilities: chạy typecheck/lint/test/smoke của repo (tự dò theo manifest); chạy validator harness nếu có; ghi git commit + wiki + log vòng đời task.

RULE-01 (MUST)：所有步骤均为必选，无例外。
RULE-02 (MUST)：Post-commit 为必选步骤，绝不跳过。
能力：根据 manifest 自主检测并运行仓库的 typecheck/lint/test/smoke；如果存在 validator harness，则运行；写入 git commit、wiki 和 log，并记录 task 生命周期。

Failure boundaries

失败边界

Typecheck/lint/test đỏ → blocked: fix rồi chạy lại, không commit.
```
qc-regression.py --run
```
đỏ → blocked (bug đã fix tái phát hoặc chưa fix); chưa có test
```
qc-*
```
→ fail-open, không chặn.
```
task_lifecycle.py
```
chặn (task-ID sai state-machine) → blocked; không có file (install cũ) → bỏ qua.
Không có draft → không promote, ghi lý do vào log (succeeded hẹp). Không có
```
task:
```
id → skip step 8, không phải lỗi.

Typecheck/lint/test 失败 → blocked：修复后重跑，不得 commit。
```
qc-regression.py --run
```
失败 → blocked（已修复的 bug 再次出现，或尚未修复）；尚无
```
qc-*
```
test → fail-open，不阻断。
```
task_lifecycle.py
```
阻断（task-ID 的 state-machine 错误）→ blocked；文件不存在（旧版安装）→ 跳过。
没有 draft → 不执行发布，在 log 中记录原因（视为范围受限的 succeeded）。没有
```
task:
```
id → 跳过步骤 8；这不是错误。

HOW

Main workflow

主工作流

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	repo	Type-check (dò lệnh theo repo)	rc 0	lỗi → fix, lặp
W02	deterministic	repo	Lint	rc 0, ghi chú warning	lỗi → fix, lặp
W03	deterministic	repo	Test + test tái hiện qc-code (3b, nếu có harness)	rc 0	fail → fix, lặp
W04	deterministic	draft/task	Trụ 3 gate `task_lifecycle.py` (nếu có harness)	rc 0	chặn → blocked
W05	judgment	app	Smoke check golden path end-to-end	golden path chạy	hỏng → fix
W06	effect	diff	Commit, message why	commit hash	—
W07	effect	draft	Promote draft + `## Origin` + log + index	trang wiki	không draft → B01
W08	effect	`task:` id	Đóng vòng đời task qua `code-logger.py` (best-effort)	state=done	không id → B02

Chi tiết từng bước (nguồn chân lý cho W01–W08; W01–W03 = bước 1–3b, W04 = 4, W05 = 5, W06 = 6 pre-commit, W07 = 6–7 post-commit, W08 = 8):

Pre-commit:

```
RUN: <type-check-cmd>
```
— detect from repo:
```
npx tsc --noEmit
```
(package.json) /
```
go build ./...
```
(go.mod). Fix all errors.

RUN: <lint-cmd>

— detect:

npx eslint src/

go vet ./...

. Fix errors; note warnings.

```
RUN: <test-cmd>
```
— detect:
```
npm test
```
/
```
go test ./...
```
. Fix failures. 3b. Test tái hiện qc-code (nếu có harness):
```
RUN: [ -f harness/scripts/qc-regression.py ] && python3 harness/scripts/qc-regression.py --run
```
— chạy các test
```
qc-*
```
do
```
/qc-code
```
sinh (tái hiện bug đã tìm). ĐỎ = một bug đã fix nay tái phát, hoặc chưa fix. Tất định, 0-token, KHÔNG gọi LLM. Fail-open nếu chưa có test
```
qc-*
```
nào (dự án chưa dùng qc-code) — không chặn.
Trụ 3 gate (nếu có harness):
```
RUN: [ -f harness/validators/task_lifecycle.py ] && python3 harness/validators/task_lifecycle.py --root .
```
— chặn cứng nếu task-ID đi sai state-machine (lùi/nhảy/né gate) hoặc draft trỏ task lạ. Không có file (install cũ) → bỏ qua. Đây là bản CỨNG của step 8 best-effort bên dưới.
Smoke check: verify golden path end-to-end.
Commit with message: why, not what.

Post-commit — mandatory, never skip: 6. Find draft in

llmwiki/wiki/sources/draft/

matching feature.

Promote to

llmwiki/wiki/concepts/

llmwiki/wiki/sources/

(permanent).

Add

## Origin

section:

Draft: <path>

Commit: <hash> — <msg>

Date: YYYY-MM-DD

CHECK: grep -l "## Origin" <promoted-file>

— must return file.

RUN: echo "promoted" >> llmwiki/wiki/log.md

— then edit log properly; update

llmwiki/wiki/index.md

Trụ 3 — đóng vòng đời (best-effort, fail-open): draft có frontmatter
```
task: T-…
```
→
```
python3 harness/scripts/code-logger.py --task set <T-id> state=done note="<commit-hash>"
```
. Lệnh fail-open (thiếu
```
--task
```
/id → bỏ qua, không chặn commit). Xác nhận:
```
--task show <T-id>
```
in lifecycle proposed→approved→dispatched→done;
```
--audit
```
xác minh các transition nằm trong chuỗi bất biến.

No draft (hotfix/refactor)? Note "no draft — <reason>" in log.md, skip step 6. No
task:
id (install cũ / propose bỏ qua mint)? Skip step 8 — fail-open, không phải lỗi.

All steps mandatory. No exceptions.

步骤	类型	输入	操作	输出/退出	失败/下一步
W01	deterministic	repo	执行类型检查（检测仓库对应的命令）	rc 0	出错 → 修复并重试
W02	deterministic	repo	执行 Lint	rc 0，记录 warning	出错 → 修复并重试
W03	deterministic	draft/task	执行 Test，并运行可复现 qc-code 的 test（3b；如有 harness）	rc 0	失败 → 修复并重试
W04	deterministic	draft/task	运行 `task_lifecycle.py` 的 3 道 gate（如有 harness）	rc 0	阻断 → blocked
W05	judgment	app	对 golden path 执行端到端 smoke check	golden path 可运行	损坏 → 修复
W06	effect	diff	Commit，message 强调 why	commit hash	—
W07	effect	draft	发布 draft，添加 `## Origin` ，并更新 log + index	wiki 页面	无 draft → B01
W08	effect	`task:` id	通过 `code-logger.py` 关闭 task 生命周期（best-effort）	state=done	无 id → B02

以下为每个步骤的详细信息（W01–W08 的唯一事实来源；W01–W03 = 步骤 1–3b，W04 = 4，W05 = 5，W06 = 6 pre-commit，W07 = 6–7 post-commit，W08 = 8）：

提交前（Pre-commit）：

```
RUN: <type-check-cmd>
```
——从 repo 中检测：
```
npx tsc --noEmit
```
（package.json）/
```
go build ./...
```
（go.mod）。修复所有错误。
```
RUN: <lint-cmd>
```
——检测：
```
npx eslint src/
```
/
```
go vet ./...
```
。修复错误；记录 warning。
```
RUN: <test-cmd>
```
——检测：
```
npm test
```
/
```
go test ./...
```
。修复失败项。 3b. 可复现 qc-code 的 test（如有 harness）：
```
RUN: [ -f harness/scripts/qc-regression.py ] && python3 harness/scripts/qc-regression.py --run
```
——运行
```
/qc-code
```
生成的
```
qc-*
```
test（复现已发现的 bug）。RED = 已修复的 bug 再次出现，或尚未修复。该过程是确定性的、0-token，且不调用 LLM。如果尚无
```
qc-*
```
test（项目尚未使用 qc-code），则 fail-open，不阻断。
第 3 支柱（Trụ 3）gate（如有 harness）：
```
RUN: [ -f harness/validators/task_lifecycle.py ] && python3 harness/validators/task_lifecycle.py --root .
```
——如果 task-ID 偏离 state-machine（倒退、跳转或绕过 gate），或 draft 指向未知 task，则硬性阻断。文件不存在（旧版安装）→ 跳过。这是下文步骤 8 best-effort 机制的硬性版本。
Smoke check：验证端到端的 golden path。
使用说明 why 而非 what 的 message 进行 Commit。

提交后（Post-commit）——必选，绝不跳过： 6. 在

llmwiki/wiki/sources/draft/

中查找与 feature 匹配的 draft。

将其发布到永久目录

llmwiki/wiki/concepts/

或

llmwiki/wiki/sources/

。

添加

## Origin

章节：

Draft: <path>

Commit: <hash> — <msg>

Date: YYYY-MM-DD

CHECK: grep -l "## Origin" <promoted-file>

——必须返回文件。

RUN: echo "promoted" >> llmwiki/wiki/log.md

——随后正确编辑 log；更新

llmwiki/wiki/index.md

。

第 3 支柱（Trụ 3）——关闭生命周期（best-effort，fail-open）： draft frontmatter 包含
```
task: T-…
```
→
```
python3 harness/scripts/code-logger.py --task set <T-id> state=done note="<commit-hash>"
```
。该命令采用 fail-open 机制（缺少
```
--task
```
/id → 跳过，不阻断 commit）。确认：
```
--task show <T-id>
```
打印生命周期 proposed→approved→dispatched→done；
```
--audit
```
验证各 transition 均位于固定链路中。

没有 draft（hotfix/refactor）？在 log.md 中记录
no draft — <reason>
，跳过 post-commit 的步骤 6。没有
task:
id（旧版安装 / propose 阶段跳过 mint）？跳过步骤 8——fail-open，不是错误。

所有步骤均为必选，无例外。

Branches

分支

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	conditional_required	không có draft (hotfix/refactor)	ghi "no draft — <reason>" vào `log.md` , skip step 6 post-commit	—	W08
B02	conditional_required	draft không có `task:` id (install cũ / propose bỏ qua mint)	skip step 8 — fail-open	—	kết thúc
B03	capability_optional	có `harness/` (qc-regression, task_lifecycle, code-logger)	chạy 3b, 4, 8	thiếu file → bỏ qua, fail-open	bước kế

ID	类型	守卫条件	行为	跳过/失败	汇合点
B01	conditional_required	没有 draft（hotfix/refactor）	在 `log.md` 中记录 `no draft — <reason>` ，跳过 post-commit 的步骤 6	—	W08
B02	conditional_required	draft 中没有 `task:` id（旧版安装 / propose 阶段跳过 mint）	跳过步骤 8——fail-open	—	结束
B03	capability_optional	存在 `harness/` （qc-regression、task_lifecycle、code-logger）	运行 3b、4、8	文件缺失 → 跳过，fail-open	下一步骤

Validation và stopping

验证与停止条件

Tất định: rc của typecheck/lint/test/qc-regression/task_lifecycle;

CHECK: grep -l "## Origin" <promoted-file>

phải trả file;

--task show <T-id>

--audit

xác nhận lifecycle. Cần review: smoke golden path. Dừng khi mọi bước pre + post xong; đỏ ở pre-commit thì không commit.

确定性验证：typecheck/lint/test/qc-regression/task_lifecycle 的 rc；

CHECK: grep -l "## Origin" <promoted-file>

必须返回文件；

--task show <T-id>

--audit

确认 lifecycle。需要人工检查：smoke golden path。所有 pre + post 步骤完成后停止；若 pre-commit 阶段失败，则不得 commit。

Examples

示例

Positive: repo có

package.json

→

npx tsc --noEmit

npx eslint src/

npm test

xanh,

qc-regression.py --run

xanh → commit "why" → promote draft

DDMMYY-login-otp.md

vào

wiki/concepts/

có

## Origin

→

code-logger.py --task set T-12 state=done note="<hash>"

Boundary/failure:
```
go test ./...
```
fail 1 test → dừng ở W03, fix rồi chạy lại, chưa commit. Hotfix không có draft → log "no draft — hotfix typo", skip promote.

正向： repo 包含

package.json

→

npx tsc --noEmit

、

npx eslint src/

、

npm test

全部通过，

qc-regression.py --run

通过 → 使用说明 why 的 message commit → 将 draft

DDMMYY-login-otp.md

发布到包含

## Origin

的

wiki/concepts/

→

code-logger.py --task set T-12 state=done note="<hash>"

。

边界/失败：
```
go test ./...
```
有 1 个 test 失败 → 停在 W03，修复后重试，暂不 commit。Hotfix 没有 draft → 记录
```
no draft — hotfix typo
```
，跳过发布。

Delivery — Output Report

交付——输出报告

After all main skill tasks complete, write a propose draft to the wiki.

完成所有主要 skill 任务后，向 wiki 写入一份状态为 proposed 的 draft。

Steps

步骤

1. Build the filename:

Format:
```
DDMMYY-<ten>.md
```
```
DDMMYY
```
= today (e.g.,
```
020626
```
for 2 June 2026)

<ten>

= 2–4 kebab-case words summarising what was done (e.g.,

landing-page-coteccons

brand-kit-fintech

ingest-auth-spec

)

2. Write

llmwiki/wiki/sources/draft/DDMMYY-<ten>.md

---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

1. 构建文件名：

格式：
```
DDMMYY-<ten>.md
```
```
DDMMYY
```
= 今天（例如，2026 年 6 月 2 日对应
```
020626
```
）
```
<ten>
```
= 2–4 个概括所完成内容的 kebab-case 词（例如
```
landing-page-coteccons
```
、
```
brand-kit-fintech
```
、
```
ingest-auth-spec
```
）

2. 写入

llmwiki/wiki/sources/draft/DDMMYY-<ten>.md

：

---
type: draft
title: "DDMMYY-<ten>"
status: proposed
tags: [<skill-name>, output-report]
timestamp: YYYY-MM-DD
---

DDMMYY-<ten>

Type: draft Status: proposed Tags: <skill-name>, output-report Proposed: YYYY-MM-DD

What

Output

Files

File	Action
`path/to/file`	created / modified

File	Action
`path/to/file`	created / modified

Notes

Invoked via:
```
/<skill-name>
```
skill

Invoked via:
```
/<skill-name>
```
skill

Origin

Draft:
```
wiki/sources/draft/DDMMYY-<ten>.md
```
Commit: (filled by verify-before-commit)
Date promoted: (filled by verify-before-commit)


**3. Update wiki index & log:**
- `llmwiki/wiki/index.md` — append one row: `| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |`
- `llmwiki/wiki/log.md` — append: `## YYYY-MM-DD — <skill-name> — <ten>`

> Skip only when the skill produces zero artefacts and zero decisions (e.g., a pure display mode like `/caveman-stats`).

Draft:
```
wiki/sources/draft/DDMMYY-<ten>.md
```
Commit: (filled by verify-before-commit)
Date promoted: (filled by verify-before-commit)


**3. 更新 wiki index 与 log：**
- `llmwiki/wiki/index.md`——追加一行：`| [DDMMYY-<ten>](sources/draft/DDMMYY-<ten>.md) | draft | YYYY-MM-DD |`
- `llmwiki/wiki/log.md`——追加：`## YYYY-MM-DD — <skill-name> — <ten>`

> 仅当 skill 未产生任何产物和任何决策时（例如 `/caveman-stats` 这类纯展示模式）才可跳过。