zf-refactor-generalization-audit

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# ZaoFu Refactor Generalization Audit

## Objective

Decide whether fixes learned from a recent refactor are generic ZaoFu harness
capabilities or one-off project patches, then produce a concrete preflight
checklist for the next target agent/project refactor.

Default repository-facing output is Chinese unless the user asks otherwise.

## Ground Rules

- Read `AGENTS.md` first and follow ZaoFu repository rules.
- Treat `zf.yaml` as the only control-plane config. Respect
  `project.state_dir`; do not assume `.zf`.
- Use committed evidence as the source of truth: `tasks/done`, commit hashes,
  tests, and runtime events. Dirty worktree files are context, not proof.
- Do not mutate runtime truth: `events.jsonl`, `kanban.json`,
  `feature_list.json`, `session.yaml`, and `role_sessions.yaml` are kernel
  managed.
- This skill is read-only unless the user explicitly approves creating or
  updating skills, docs, backlogs, or code.
- If a deterministic checker or runtime change is needed, create a proposed
  backlog first. Do not implement it in the same pass unless approved.

## Inputs

Use only the inputs relevant to the request:

- bounded time window, such as "最近两天";
- target project path and target `zf.yaml`;
- recent `tasks/done/*.md` and related `backlogs/*.md`;
- `git log`, `git show --stat`, and targeted diffs for referenced commits;
- focused tests named in done tasks;
- runtime evidence under the configured state dir when diagnosing a live run.

## Audit Workflow

1. Bound the scope.
   - If the user gives no window, inspect recent commits plus the current
     requested target.
   - Record target repo path, target config path, branch, state dir, and
     backend assumptions.

2. Audit completed backlog evidence.
   - Read only relevant `tasks/done` items.
   - For each item, capture bug class, fix commit, verification command, and
     whether the fix touched harness code or target project code.
   - Prefer done tasks with explicit implementation commit and focused tests.

3. Review the associated commits.
   - Use `git show --stat <commit>` first.
   - Open targeted diffs only when the stat cannot answer ownership or
     genericity.
   - Classify touched files:
     - generic harness: `src/zf/core`, `src/zf/runtime`, `src/zf/cli`,
       `src/zf/autoresearch`, `src/zf/web`, shared tests and docs;
     - config/project adapter: examples, `zf.yaml`, provider setup, skills;
     - project-specific: target application code, one-off branches, manual
       state repair, private provider history.

4. Check portability criteria.
   - Generic when the behavior is config-driven, covered by non-project-only
     tests, and does not hard-code target ids, branch names, paths, or event
     payloads.
   - Needs adaptation when event names, dirty-file policy, provider backend,
     stage names, artifact paths, or LLM validation commands differ by target.
     注意:writer/impl slice 的完工事件可能是 `dev.build.done` 或
     `impl.child.completed`(controller/profile flow 发后者,kernel 视为等价——
     `dispatch_routing_queries.py` `_requires_task_ref_for_progress_event`、`terminal_ledger.py` `TERMINAL_SUCCESS_EVENTS`、`topology.py`);
     只认单一 `dev.build.done` 会误判 controller/profile 拓扑不可移植。
   - Project-specific when it depends on one repo's source layout, manual
     local state, or a non-repeatable prompt/session condition.

5. Inspect the target `zf.yaml`.
   - Verify workflow stages, role backends, event contracts, affinity lanes,
     rework routing, repair policy, trigger budget, state dir, and skills.
   - Confirm scan/plan/artifact/task-map outputs are durable files, not only
     chat text or pane history.
   - Confirm resume/recover paths can infer the next action from events.

6. Produce the decision.
   - `GO`: no P0 gap blocks reuse; config and smoke checks pass.
   - `GO_WITH_ADAPTATION`: reusable harness exists, but target config or
     skills need explicit changes before launch.
   - `STOP`: missing contract, hard-coded assumption, broken smoke, or no
     recovery path for a known critical failure.

## Output Format

Lead with a concise decision, then include this table:

```text
| Bug/fix class | Evidence | Genericity | Target adaptation needed | Next action |
|---|---|---|---|---|
```

Then include:

- target preflight checklist;
- known residual risks;
- proposed backlog/skill/doc assets, if any;
- exact commands already run and commands still recommended.

## Preflight Checklist

Before starting a long refactor on a new target project:

- `zf validate --cold-start` passes for the target config.
- Target `project.state_dir` is isolated and not stale from another run.
- **根脚手架 ownership**:仅当本轮 delivery 必须修改或验证根级脚手架/entrypoint
  时，task_map 才声明 `workspace_root_owner_required=true`（顶层或
  `refactor_contract` 内）并分配对应根路径。局部/存量项目默认省略该字段（等同
  false），不应虚构 assembly 或根文件所有权。该开关不放松 task schema/path/evidence
  或并行 bundle assembly 校验；审计时确认其与 source inventory 一致。
- workflow stages have explicit completion events and next-stage dispatch
  rules.
- fanout stages have bounded stuck handling and child completion
  reconciliation. 注意:不收敛升级不再原地 stuck-guard——现在按 stall 指纹铸

From uisee-ai/zaofu, Apache-2.0.

More from uisee-ai/zaofu