Skip to content

Simplify workflow docs sync around direct risk coverage #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
wlvh merged 1 commit into from
Aug 2, 2026
Merged

Simplify workflow docs sync around direct risk coverage #18

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
20 changes: 20 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# 仓库维护入口

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

- `zh/` 是中文语义源；`en/` 是从中文派生的模板与说明。
- 根 `.github/` 是本仓库 CI 与 GitHub 基础设施；`zh/.github/`、`en/.github/` 是下游模板源。
- 修改模板：先改 `zh/` 对应九份核心文件，再同步 `en/`。
- 修改 Skill：进入 `zh/skills/workflow-docs-sync/`。
- 修改安装器：进入 `zh/scripts/install_skills.py`。
- 修改入口说明：更新根 README、`zh/README.md` 与 `en/README.md`；详细工作流在
`zh/docs/development_workflow/`，实现决策在其 `decisions.md`。
- 修改测试：进入 `tests/test_workflow_docs_sync.py`；具体约束以测试代码为准，不在此复制。

最短验证入口：

```bash
python3 -m pytest -q
```

完整维护地图与补充验证见 [zh/README.md](zh/README.md#维护者地图)。
33 changes: 9 additions & 24 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,35 +2,20 @@

[中文](zh/README.md) | English

This repository publishes bilingual workflow-document templates and the
`workflow-docs-sync` Skill that specializes them against a real target repository.
This repository publishes bilingual downstream workflow-document templates, the canonical
`workflow-docs-sync` Skill, and its installer. Chinese under `zh/` is the semantic source; `en/` is derived.

## Quick Start

Invoke the Skill once. Provide only the target repository, optional language
(`zh` or `en`), and whether to create a draft PR after successful validation.
Invoke the Skill once with only the target Git repository, `zh` or `en`, and whether a draft PR should be
created after success:

```text
Use $workflow-docs-sync for /absolute/path/to/repository in English.
Do not create a draft PR.
```

The main agent is the only workspace writer. Four domain analyses and the
adversarial audit are read-only; the final checker validates repository state,
not execution history. Upstream checkout and commit resolution are internal.

## Directory Map

- [en/](en/): English templates and workflow documentation.
- [zh/](zh/): Chinese source templates, prompts, decisions, and Skill implementation.
- [zh/skills/workflow-docs-sync/](zh/skills/workflow-docs-sync/): single-session orchestration, read-only analysis references, and the deterministic checker.
- [tests/test_workflow_docs_sync.py](tests/test_workflow_docs_sync.py): sync and installer regression tests.

## Install Path Rule

The `zh/` and `en/` directories are upstream source prefixes. The Skill strips
only the selected leading language directory and installs the remaining paths at
the target repository root. Inner paths such as `.github/` remain unchanged.
The repository root contains CI and GitHub infrastructure. Downstream `.github/` templates live under the
language directories and are installed without that leading language prefix.

Chinese remains the source-of-truth workflow. English is its derived language
path; unfinished English coverage must be identified explicitly as `en-pending`.
For source ownership, edit locations, and validation commands, use the
[Chinese maintainer map](zh/README.md#维护者地图). English template and directory guidance is available in
[en/README.md](en/README.md).
120 changes: 28 additions & 92 deletions en/.github/pull_request_template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,114 +1,50 @@
<!--
PR body principles:

1. Write only facts completed by this PR, not plans.
2. File lists must come from: git diff --name-only <base>...HEAD.
3. Testing strategy and test evidence follow TESTING.md.
4. User-visible changes are checked against interact.md.
5. Architecture changes are checked against architecture.md.
6. Every review / fix round must be recorded in "Review / Fix Record".
Write only facts completed by this PR. Derive scope from the actual Git diff, follow TESTING.md for test
evidence, and check user behavior and architecture against interact.md and architecture.md. Do not include
plans, historical drafts, or local uncommitted content.
-->

## 1. Background and Goal

---
<!-- Explain the problem, goal, linked requirement, and scope explicitly excluded from this PR. -->

## 2. Implementation
## 2. Implementation and Tradeoffs

<!--
Explain the core approach and key tradeoffs.
Do not restate every code change.
-->

---

## 3. Change Scope

<!--
Must come from:
git diff --name-only <base>...HEAD

List only files or directories actually changed in this PR.
Do not list files absent from the current patch.
-->
<!-- Explain the core implementation, key tradeoffs, and rejected alternatives without restating every file diff. -->

| File / Directory | Change Type | Notes |
|---|---|---|
| | Added / Modified / Deleted | |
## 3. Actual Change Scope

---
<!-- List actual changes from git diff --name-only <base>...HEAD. Do not keep empty tables or planned files. -->

## 4. Documentation Impact

<!--
List affected documents only. If no documents need updates, write: None.

If this PR changes capability boundaries, check capability_contract.json / interact.md / docs/business_user_guide.md.

If this PR changes user-visible behavior, check interact.md and decide whether docs/business_user_guide.md also needs updates.

If this PR changes what business users can ask, how they ask, how they read results, or when they ask a human, check docs/business_user_guide.md.

If this PR adds "can do / cannot do / must ask / must refuse" statements, confirm each has a capability_contract.json anchor_id or a test anchor.
-->

Affected documents:

- None

Notes:

-

---

## 5. User and Architecture Impact

User-visible change:

- Yes / No
- Notes:

Architecture change:

- Yes / No
- Notes:

---

## 6. Review / Fix Record

<!--
Under the one-commit strategy, this section is the fix history.
Update it after every review, fix, or merge-readiness response.
-->
<!-- 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. -->

| Round | Source | Issue Summary | Judgment | Result | Evidence |
|---|---|---|---|---|---|
| R0 | Initial submission | N/A | N/A | Initial implementation | |
| R1 | Codex / Claude / Human | | Real / Invalid / Defer | Fixed / Won't fix / N/A | |
## 5. User-visible and Architecture Impact

---
<!-- Describe user-visible and architecture changes separately. If none exist, write None and the evidence checked. -->

## 7. Known Limits and Rollback
## 6. Testing Evidence

Known limits:
- Exact command: Record the command verbatim, or write `Not run`.
- Scope: State the layer, entrypoint, and boundary the command actually proves.
- Result: Record pass, failure, skip, and important counts or errors.
- Not-run reason: Write `Not applicable` when run; otherwise give the concrete reason and risk.
- Environment: Record the actual execution environment, isolation method, side effects, and cleanup result.

-
## 7. Review / Fix Record

Rollback:
<!-- For each finding ID, record severity, evidence, judgment, fix, and recheck result. If there are no findings, list the high-risk areas checked. Do not add a duplicate reconciliation ledger. -->

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

---
<!-- Separate known limits, product decisions still open, and executable rollback. Write None when a category is empty. -->

## 8. Final Self-Check
## 9. Final Self-check

- [ ] Current branch is not the main branch.
- [ ] Ran `git diff --name-only <base>...HEAD`.
- [ ] Change Scope matches the actual diff.
- [ ] PR body contains no stale drafts, old branch names, or unimplemented plans.
- [ ] Testing and test evidence follow `TESTING.md`.
- [ ] User-visible changes were checked against `interact.md`.
- [ ] Architecture changes were checked against `architecture.md`.
- [ ] Every review / fix round is recorded in "Review / Fix Record".
- [ ] 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.
119 changes: 71 additions & 48 deletions en/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,72 +1,95 @@
## File Overview
# Agent Working Guide

### Core Config
## Authority Map

- `AGENTS.md`: Agent entrypoint, file overview, coding rules, and user-facing document relationships.
- `capability_contract.json`: Cross-project sample registry for capability boundaries, responsibility boundaries, and agent behavior commitments.
- `.github/pull_request_template.md`: Long-term PR body template used to draft local `PR_BODY.md`.
- Current code, configuration, tests, committed artifacts, and reproducible results are project facts.
- `architecture.md` defines system structure and boundaries; `TESTING.md` defines test entrypoints and
evidence levels; `PR_Checklist.md` defines delivery checks; `SOP.md` keeps only stable process entrypoints.
- `capability_contract.json` defines capability boundaries, `interact.md` defines user-visible behavior and
acceptance, and `docs/business_user_guide.md` only derives explanations from the first two.
- Existing documents are claims to verify against implementation; they cannot prove themselves correct.

### Core Modules
<!-- project-fill: Add other authoritative project sources and conflict precedence, then remove this marker. -->

### Business Logic
## Repository Overview

### Notes
Describe stable modules, entrypoints, and responsibilities. Do not permanently mirror `git ls-files`.

- When files are added or changed, update this file overview where relevant. Test files are governed by `TESTING.md`.
- All repository files use UTF-8. Command-line reads and edits must explicitly use UTF-8.
- One-off artifact folders are exempt from this overview when explicitly approved.
### Core Configuration

## Architecture
<!-- project-fill: List real configuration entrypoints and responsibilities. If none apply, write Not applicable with a verified reason, then remove this marker. -->

### Runtime Entrypoints

The authoritative architecture document is `architecture.md`. If a change affects module boundaries, runtime call flow, data flow, state model, error model, external dependencies, or extension points, update `architecture.md`; otherwise explain the no-update reason in the PR body.
<!-- project-fill: List real user, service, job, or CLI runtime entrypoints, then remove this marker. -->

## Business Knowledge
### Core Modules

## Review Checklist
<!-- project-fill: Summarize core implementation by stable module boundaries, not individual files, then remove this marker. -->

When the user asks you to submit a PR, fully follow `PR_Checklist.md`; any exemption must be explained in the PR description.
### Domain Logic

## Testing Flow
<!-- project-fill: Identify modules containing domain rules and their authoritative tests or contracts, then remove this marker. -->

Before fixing bugs, starting tests, or submitting a PR, read and follow `TESTING.md`. Main branch changes must go through PR merge only.
### Generated Artifacts and External State

## SOP
<!-- project-fill: List committed or generated artifacts, persisted state, and external systems. If none exist, write Not applicable with a verified reason, then remove this marker. -->

## Change Impact Rules

When you execute a standard process, read and follow `SOP.md`; when SOP entries are added or changed, update this list with the SOP name.
- Update or confirm `architecture.md` when module boundaries, runtime call flow, data flow, state, error
model, external dependencies, or extension points change.
- For capability changes, update or confirm `capability_contract.json` first, then inspect `interact.md`
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.
- Derive encoding, lint, formatter, build, and type rules from real repository configuration, not this
template.

## User-Facing Document Relationships
## Collaboration

This project distinguishes three user-facing sources of truth:
- The primary executor owns final judgments, deliverables, and writes; delegated results must be reviewed
and synthesized before use.
- Assign non-overlapping path ownership before parallel writes; follow the target project's policy for the
isolation method.
- Divide work dynamically by module, call flow, risk, or evidence type; do not require a fixed agent count
or schedule.
- Agreement, voting, or consensus is not evidence. Important conclusions must trace to repository facts and
reproducible validation.
- Investigation and review tasks are read-only by default; when changes are needed, hand them off explicitly
to an executor who owns the affected paths.

1. `capability_contract.json`
- Machine-readable source for capability boundaries.
- Answers what the system can do, cannot do, must ask about, or must refuse.
<!-- project-fill: Add verified project collaboration or ownership rules. If none exist, remove this marker. -->

2. `interact.md`
- Source for user-visible behavior and acceptance invariants.
- Answers how the system must behave and what acceptance means.
## Architecture

Treat `architecture.md` as the architecture authority. Rebuild affected call paths from real entrypoints
before a change, then verify invariants, module responsibilities, data contracts, state, side effects, and
failure paths afterward.

## Testing

Read `TESTING.md` completely before testing and derive exact commands from repository configuration. Do not
present light, mock, golden, or local repair success as a higher validation level. Choose the execution
environment from command side effects, CI capabilities, and project policy, with isolation and cleanup
verified before execution.

## SOP

3. `docs/business_user_guide.md`
- Derived teaching document for first-time business users.
- Answers what business users can ask, how to ask, how to read results, and when to ask a human.
- It must not declare independent capabilities; it only explains capabilities and behavior already declared in `capability_contract.json` and `interact.md`.
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.

Update rules:
## PR Delivery

- If capability boundaries change, update or confirm `capability_contract.json` first, then check `interact.md` and `docs/business_user_guide.md`.
- If user-visible behavior changes, update or confirm `interact.md` first, then check `docs/business_user_guide.md`.
- If business-user questions, prompts, result interpretation, or escalation guidance change, check `docs/business_user_guide.md`.
- Any "can do / cannot do / must ask / must refuse" statement in `docs/business_user_guide.md` must anchor to `capability_contract.json`, `interact.md`, or tests.
- Follow `PR_Checklist.md` and `.github/pull_request_template.md`; write delivery facts from the actual Git
diff, test output, and final repository state.
- Resolve the default branch from the repository instead of hardcoding it. Follow target-project policy for
PR body draft location and publishing; never commit temporary drafts accidentally, and keep the body
consistent with the real diff and test evidence.
- Do not commit, push, or create a PR unless the user explicitly requests it.

## Coding Rules
## Project-specific Conventions

1. What I cannot create, I do not understand.
2. Use the project's selected working language; answer in English unless user or project instructions require otherwise. Code volume is a liability after functionality is met; keep code as small as possible, then optimize for maintainability.
3. Follow PEP 8 for Python. Use UTC time. Use UTF-8 text.
4. Manage parameters centrally. Always call functions with explicit parameter names instead of relying on positional defaults. Do not use `get` for expected parameters; fail fast when a required parameter is missing.
5. Every class and function needs a docstring. Each functional block inside a function needs comments explaining why, expected output, and parameter meaning, range, and format. Script-level docstrings must explain purpose and call relationships.
6. Do not let `try/except` or `if/else` blocks run naked. Use explicit exception types and enough print/log information in `except` and `else` branches. Unexpected errors should fail inside the current function.
7. Data in, data out: scripts, functions, and modules interact only through explicit data inputs and outputs, not hidden external state.
8. Reused code blocks should be wrapped into functions or modules to keep code DRY.
9. Use language features to reduce code and performance cost while keeping readability.
10. Do everything necessary to help the user reach the goal.
<!-- project-fill: Derive project conventions from lint, formatter, compiler, build, or team configuration. If none are verifiable, write None and the configuration scope checked, then remove this marker. -->
Loading