Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 2 additions & 10 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

本仓库发布双语下游工作流模板、canonical `workflow-docs-sync` Skill 和安装器。

新增 marker、alias、parser 或其他控制机制前,先按 DEC-006 证明独立风险、真实消费者和可复现失败路径;否则保持零 diff。

- `zh/` 是中文语义源;`en/` 是从中文派生的模板与说明。
- 根 `.github/` 是本仓库 CI 与 GitHub 基础设施;`zh/.github/`、`en/.github/` 是下游模板源。
- 修改模板:先改 `zh/` 对应九份核心文件,再同步 `en/`。
Expand All @@ -11,16 +13,6 @@
`zh/docs/development_workflow/`,实现决策在其 `decisions.md`。
- 修改测试:进入 `tests/test_workflow_docs_sync.py`;具体约束以测试代码为准,不在此复制。

新增 marker、alias、机器状态、parser、兼容入口或其他控制机制前,必须先证明它表达独立状态,
并存在真实消费者与可复现失败路径。若扩展现有机制可以覆盖:

- 先登记 finding;
- 说明最小扩展边界与新增成本;
- 不得改用同义 alias;
- 若与用户指定实现不同,先说明替代方案。

缺少真实缺口或消费者证据时保持零 diff,不因用户给出了具体实现方案就机械执行。

最短验证入口:

```bash
Expand Down
9 changes: 4 additions & 5 deletions en/.github/pull_request_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ plans, historical drafts, or local uncommitted content.

## 4. Documentation Impact

<!-- List documents actually updated and their evidence. Give a real no-update reason for affected candidate documents left unchanged; not every document needs a diff. -->
<!-- List documents actually updated and their evidence. State the current factual basis for affected authorities left unchanged. -->

## 5. User-visible and Architecture Impact

Expand All @@ -34,7 +34,7 @@ plans, historical drafts, or local uncommitted content.

## 7. Review / Fix Record

<!-- For each finding, record a stable ID, severity, first-seen round or source, evidence, judgment, fix, and recheck result. Finding states are OPEN / CLOSED / DEFERRED. REOPENED is an event, not a state; it preserves the original ID and appends evidence. CURRENT / SUPERSEDED describes only a candidate or evidence, never finding state or an overwritten earlier failure. A prior miss explanation must be evidence-backed, labeled hypothesis, or written as unknown. Formal raw records may live in comments while the body keeps an index. Record Promoted reusable rule: <authority / None>. If there are no findings, list the high-risk areas checked. Do not add a duplicate reconciliation ledger. -->
<!-- Record the actual review, actionable feedback, disposition and recheck results, and any open decisions or limits according to this project's delivery policy. -->

## 8. Known Limits, Open Decisions, and Rollback

Expand All @@ -45,6 +45,5 @@ plans, historical drafts, or local uncommitted content.
- [ ] Actual Change Scope matches the real diff.
- [ ] Test commands, scope, results, and not-run reasons are accurate.
- [ ] User-visible and architecture impact were checked against their authoritative documents.
- [ ] BLOCKERs and actionable WARNs are closed; open decisions are not presented as complete.
- [ ] The PR body contains no historical draft, unimplemented plan, wrong base/head, or repository-local
temporary body path.
- [ ] Actionable review feedback required by this project is handled or explicitly recorded as open.
- [ ] The PR body contains no historical draft, unimplemented plan, or wrong base/head.
8 changes: 4 additions & 4 deletions en/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,8 @@ Describe stable modules, entrypoints, and responsibilities. Do not permanently m
and the business guide. For user-visible behavior changes, update or confirm `interact.md` first.
- Tests remain factual evidence; keep exact commands, fixtures, layers, and isolation details in
`TESTING.md` only.
- Not every change requires every document to change. Give a current, evidence-based no-update reason for
each affected candidate document left unchanged.
- Not every change requires every document to change. For an affected authority left unchanged, state the
current factual basis in the delivery record.
- Derive encoding, lint, formatter, build, and type rules from real repository configuration, not this
template.

Expand Down Expand Up @@ -78,8 +78,8 @@ verified before execution.

## SOP

Read the corresponding `SOP.md` entry for a standard process. Keep execution checklists in the current
session; do not create repository run state, receipts, or temporary process documents.
Read the corresponding `SOP.md` entry for a standard process. Follow this project's actual audit,
recoverability, and delivery policy for whether execution records are stored, where, and for how long.

## PR Delivery

Expand Down
14 changes: 4 additions & 10 deletions en/PR_Checklist.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,8 @@ explicitly requests it.
## Documentation and Contracts

- [ ] Check `AGENTS.md`, `architecture.md`, `capability_contract.json`, `interact.md`, the business guide,
`TESTING.md`, and `SOP.md` according to actual impact. Give a real no-update reason for affected candidates
left unchanged; do not edit every document merely for completeness.
`TESTING.md`, and `SOP.md` according to actual impact. State the current factual basis for affected
authorities left unchanged; do not edit every document merely for completeness.
- [ ] Keep the authority direction `capability_contract.json → interact.md → business_user_guide.md` for
capability changes. User-visible claims have current implementation or test evidence and stable anchors.
- [ ] Reference Markdown anchors through the capability contract's contract-defined protocol without copying
Expand All @@ -45,14 +45,8 @@ explicitly requests it.

- [ ] Complete the review gate required by this project's test and delivery policy, and accurately record
reviewer identity, scope, and limitations.
- [ ] Fix every BLOCKER and actionable WARN that does not require a new product decision. Keep remaining
issues in open decisions with evidence and impact.
- [ ] Preserve material rounds, REOPENED findings, and SUPERSEDED candidates or evidence. Reopening keeps the
original finding ID, and finding state is not confused with evidence state.
- [ ] Support a prior miss explanation with evidence or label it `hypothesis` / `unknown`; never invent cause
merely to fill a field.
- [ ] Evaluate every material finding for promotion to a long-term rule or automated gate, and record why when
it is not promoted.
- [ ] Handle actionable review feedback according to this project's policy. Keep recheck evidence for resolved
items and record the impact and required decision for anything left open.
- [ ] Rerun affected tests and mechanical checks after fixes, then recheck the final diff and Git state.

## PR Delivery
Expand Down
4 changes: 4 additions & 0 deletions en/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,10 @@ Review prefers a fresh-context, blind-first independent reviewer. When cognitive
the result is reported honestly as self-review. The deterministic checker proves final repository state
only, not investigation, test, or review history.

The installer copies only the canonical Skill. Before any target mutation it rejects symlinks, frontmatter
without standard delimiters, and ignored source residue that would otherwise be copied; it stores no source
receipt.

## Template Contract

Markdown project-fill slots use `<!-- project-fill: ... -->`; JSON uses strings prefixed with
Expand Down
4 changes: 2 additions & 2 deletions en/SOP.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@

`SOP.md` keeps stable process entrypoints and does not copy volatile commands, test lists, or publishing
details. When sources conflict, current code, configuration, tests, contracts, and focused authorities such
as `TESTING.md` and `PR_Checklist.md` take precedence. Keep execution checklists in the current session;
do not write them as repository run state, receipts, or temporary SOPs.
as `TESTING.md` and `PR_Checklist.md` take precedence. Follow this project's actual audit, recoverability,
and delivery policy for how execution records are stored and retained.

## Available SOPs

Expand Down
6 changes: 3 additions & 3 deletions en/TESTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,9 @@ maintenance value.

## 3. Capability Contract Alignment

An alignment test belongs to the target project's test suite, not the documentation sync checker. It
should recursively collect stable `anchor_id` values from every object in `capability_contract.json` and
use the protocol defined by the contract rules to check uniqueness and Markdown references without
A project's alignment test should recursively collect stable `anchor_id` values from every object in
`capability_contract.json`. It should use the protocol defined by the contract rules to check uniqueness
and Markdown references without
hardcoding buckets, JSON paths, array positions, or requiring every contract entry to appear in the
business guide.

Expand Down
28 changes: 20 additions & 8 deletions en/docs/development_workflow/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,14 @@ external shallow clone, then pins target HEAD and upstream SHA for the entire ru
source and validates final HEAD, dirty scope, no index/worktree split on editable paths, nine regular UTF-8
nonempty files, a JSON object, active markers, and an existing `.gitignore` as UTF-8. Final-byte whitespace
runs with fixed Git rules from a temporary non-repository directory, independent of target attributes. It
does not parse Markdown or validate capability truth, test levels, prose quality, or execution history.
does not parse Markdown or validate capability truth, test levels, prose quality, or execution history. The
single final-byte path depends on rejecting every dirty path outside the allowlist; relaxing that allowlist
requires reevaluating whitespace coverage. Split detection aggregates both status sides by path and covers
an index deletion or rename source followed by an untracked or ignored recreation at that path. It removes
two publication candidates rather than running a second whitespace check.
- Before any removal or copy, the installer validates source and destination ancestors, source symlinks,
standard delimiters around Claude frontmatter, and ignored source residue that would be copied. It only
removes the exact obsolete reviewer Skill and stores no install state or source receipt.
- Keep temporary PR body Markdown outside the repository. Commit, push, and draft-PR creation occur through
general GitHub publishing capability only after successful checks and only when the user asks.

Expand All @@ -86,13 +93,18 @@ not promise exhaustive alias detection, and structural references do not prove c
does not raise `schema_version` from `0.1.0`. TESTING defines minimum evidence for escaped bugs, public
contracts, no-test diffs, refactors, and documentation-only gates, while the checklist enforces the
add-or-not-add test decision.
Findings keep stable IDs and first-seen evidence; REOPENED is an event, CURRENT / SUPERSEDED applies only to
candidates or evidence, and prior misses are evidence-backed, labeled hypothesis, or recorded as unknown.

With the same target base, upstream candidate, language, and round-one document bytes, Case A round two passes
only as `PASS_NOOP`; an added valid correction is `ROUND1_INCOMPLETE`, and unsupported prose drift is
`ROUND2_DRIFT`. Either failure restarts both rounds from a clean target. This decision adds no parser, ledger,
receipt, run state, installer behavior, or `sync_docs.py` / CLI feature.
Stable IDs, first-seen evidence, REOPENED events, and candidate/evidence states belong to this repository's
maintenance and canonical Skill/eval evidence contract. Downstream templates defer review records,
actionable feedback, rechecks, and open decisions to target-project policy instead of fixing this vocabulary.

Case A preregisters the selected target and known-stale claims before starting a blind executor. Target code,
configuration, tests, other committed artifacts, upstream candidate, and language stay fixed; round one
commits only its final nine documents, and round two starts from that `second_target_sha` in a new clean
checkout. A zero document diff with no staged, untracked, or ignored residue is `PASS_NOOP`; an added valid
correction is `ROUND1_INCOMPLETE`, and unsupported prose drift is `ROUND2_DRIFT`. Alignment runs directly on
the committed second target instead of a derived test-only identity. Either failure restarts both rounds from
a clean target. This decision adds no parser, ledger, receipt, run state, installer behavior, or
`sync_docs.py` / CLI feature.

Key implementation files:

Expand Down
Loading