diff --git a/AGENTS.md b/AGENTS.md index d120ee5..f1d7fcf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,10 +11,20 @@ `zh/docs/development_workflow/`,实现决策在其 `decisions.md`。 - 修改测试:进入 `tests/test_workflow_docs_sync.py`;具体约束以测试代码为准,不在此复制。 +新增 marker、alias、机器状态、parser、兼容入口或其他控制机制前,必须先证明它表达独立状态, +并存在真实消费者与可复现失败路径。若扩展现有机制可以覆盖: + +- 先登记 finding; +- 说明最小扩展边界与新增成本; +- 不得改用同义 alias; +- 若与用户指定实现不同,先说明替代方案。 + +缺少真实缺口或消费者证据时保持零 diff,不因用户给出了具体实现方案就机械执行。 + 最短验证入口: ```bash -python3 -m pytest -q +PYTHONDONTWRITEBYTECODE=1 python3 -m pytest -q -p no:cacheprovider ``` 完整维护地图与补充验证见 [zh/README.md](zh/README.md#维护者地图)。 diff --git a/en/README.md b/en/README.md index 3828ab2..794e1d6 100644 --- a/en/README.md +++ b/en/README.md @@ -49,8 +49,9 @@ Templates do not assume a programming language, framework, test runner, service, - GitHub paths: root `.github/` serves this repository, while `.github/` here and under `zh/` are downstream template sources. -The shortest entrypoint is `python3 -m pytest -q`. Full closure commands are maintained in the -[Chinese maintainer map](../zh/README.md#维护者地图). +The residue-safe shortest entrypoint is +`PYTHONDONTWRITEBYTECODE=1 python3 -m pytest -q -p no:cacheprovider`. The full closure sequence is maintained +only in the [Chinese maintainer map](../zh/README.md#维护者地图). ## Directory Map diff --git a/zh/README.md b/zh/README.md index 8d1f8be..c904f84 100644 --- a/zh/README.md +++ b/zh/README.md @@ -54,15 +54,31 @@ Markdown project-fill slot 使用 ``,JSON 使用 - GitHub 路径:根 `.github/` 只服务本仓库 CI/GitHub;`zh/.github/` 与 `en/.github/` 是下游 模板源。 -最短入口是 `python3 -m pytest -q`。完整收口命令: +最短入口是 `PYTHONDONTWRITEBYTECODE=1 python3 -m pytest -q -p no:cacheprovider`。以下是唯一完整 +验证命令权威;它比较验证前后的普通与 ignored 状态,不使用 `git clean`: ```bash -python3 -m pytest -q -python3 -m py_compile zh/skills/workflow-docs-sync/scripts/sync_docs.py zh/scripts/install_skills.py -python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" \ +set -euo pipefail +validation_tmp="$(mktemp -d /tmp/coding-workflow-validation.XXXXXX)" +trap 'rm -rf -- "$validation_tmp"' EXIT +before="$validation_tmp/status.before" +after="$validation_tmp/status.after" + +git status --porcelain=v1 -z --untracked-files=all --ignored > "$before" +PYTHONDONTWRITEBYTECODE=1 python3 -m pytest -q -p no:cacheprovider +PYTHONPYCACHEPREFIX="$validation_tmp/pycache" python3 -m py_compile \ + zh/skills/workflow-docs-sync/scripts/sync_docs.py zh/scripts/install_skills.py +PYTHONDONTWRITEBYTECODE=1 \ + python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" \ zh/skills/workflow-docs-sync git diff --check -python3 zh/skills/workflow-docs-sync/scripts/sync_docs.py --help +PYTHONDONTWRITEBYTECODE=1 python3 zh/skills/workflow-docs-sync/scripts/sync_docs.py --help +git status --porcelain=v1 -z --untracked-files=all --ignored > "$after" + +if ! cmp -s "$before" "$after"; then + diff -u <(tr '\0' '\n' < "$before") <(tr '\0' '\n' < "$after") || true + exit 1 +fi ``` ## 目录地图 diff --git a/zh/skills/workflow-docs-sync/SKILL.md b/zh/skills/workflow-docs-sync/SKILL.md index 00daa58..f69de2d 100644 --- a/zh/skills/workflow-docs-sync/SKILL.md +++ b/zh/skills/workflow-docs-sync/SKILL.md @@ -30,7 +30,10 @@ description: 从目标 Git 仓库的代码、配置、测试和 committed artifa ``` 4. 只消费单行 JSON,固定返回的 `target_head` 和 `upstream_sha`,整轮复用同一对 SHA。 -5. 临时 clone 在会话结束时清理;canonical checkout 不清理。 +5. 创建临时 upstream 时立即记录临时根目录。当前 Agent 必须在任何成功、失败或提前停止的 + 最终回复前删除它并运行 `test ! -e `。未通过时登记 + `WDS-UPSTREAM-CLEANUP / BLOCKER`,不得报告完成;Controller 后置清理不能改判本轮成功。 + canonical checkout 不清理。 `prepare` 从固定 Git object 读取模板,并在任何目标写入前确认九份 source path 都存在且为 UTF-8、八份非 PR source 至少含一个 active marker;随后只创建缺失文件,不覆盖已有文档。 @@ -43,6 +46,12 @@ UTF-8、八份非 PR source 至少含一个 active marker;随后只创建缺 committed artifacts、可重复运行结果和必要 Git 历史;不得用旧文档证明旧文档正确,也不得 因为内容未出现在近期 diff 中而跳过。 +确认文档问题后、任何语义编辑前,先在会话中登记 finding:唯一 ID、`BLOCKER` / `WARN` / +`NOTE`、代码/配置/测试或 artifact 证据、风险和最小修复边界。不得在编辑完成后根据最终 diff +或 reviewer 结论倒填为“写入前 finding”。同一根因、同一证据链和同一修复边界影响多份文档 +时合并为一个 finding,不按文件或行机械拆分。多份文档共同声明但代码和测试不存在的能力, +必须在编辑前登记 `BLOCKER`。 + - 全量质疑九份文档,只改错误、缺失、失真或失效内容;正确内容保持零 diff。 - 删除没有当前事实证据的强声明。需要产品判断时记录 open decision,不编造结论。 - 保持 `capability_contract.json → interact.md → docs/business_user_guide.md` 的权威方向。 @@ -73,6 +82,9 @@ committed artifacts、可重复运行结果和必要 Git 历史;不得用旧 副作用、CI 能力和项目政策决定,可以是 CI、container、独立 checkout、远端环境或其他已 验证环境;记录 exact command、scope、result、not-run reason、环境、隔离和清理结果。 +目标 `TESTING.md` 要求多个解释器时,分别运行并记录每个解释器的命令和结果;不能运行时分别 +记录 not-run reason。一个解释器的结果不能替代另一个解释器。 + 验证层级不得膨胀。Unit、contract、scenario、golden、report build、repair validation、light review、full validation 和 live test 只能按实际覆盖范围表述;未运行不得报告为通过。 @@ -99,7 +111,11 @@ Review mode: self-review; independent review was not available 不得把 self-review 称为 independent。用户明确要求 independent review 而平台无法提供时, 停止在发布前。 -每个 finding 包含唯一 ID、severity、证据、风险和预期修复边界: +review mode 为 `independent` 时,最终报告必须记录 reviewer 会话或线程标识、启动时间和认知 +隔离边界;缺少这些证据时,不得仅凭主 Agent 声明认定 independent。 + +Reviewer 使用同一受控 severity。每个 finding 包含唯一 ID、severity、证据、风险和预期修复 +边界: - `BLOCKER`:当前候选会产生错误、虚构、越权、不可复现交付或关键风险遗漏,必须修复后才能 收口。