@elvis1513/auto-coding-skill 4.0.0 → 4.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -5,7 +5,12 @@ A delivery-first Codex engineering workflow:
5
5
  `analysis → decomposition → necessary design → development → one final fast
6
6
  changed-scope gate → commit/push`.
7
7
 
8
- Version 4.0 replaces the 3.x governance-first defaults with progressive
8
+ The Skill is a selectable guardrail, not a command sequence that must run for
9
+ every task. The model skips machinery whose expected benefit does not exceed its
10
+ cost; read-only work and obvious small clean-checkout changes normally stay direct.
11
+
12
+ Version 4.1.1 consolidates the 4.x delivery-first workflow into one canonical
13
+ repository contract. Version 4.0 replaced the 3.x governance-first defaults with progressive
9
14
  guardrails. Clean single-writer work stays on the current branch. Worktrees,
10
15
  parallel fixers, fingerprint review, durable design records, and stronger
11
16
  affected-scope checks are enabled only when concurrency or risk justifies them.
@@ -26,7 +31,7 @@ The project install contains:
26
31
  .agents/agents/
27
32
  docs/ENGINEERING.md
28
33
  docs/tools/autopipeline/ap.py
29
- AGENTS.md (managed bridge only; project content is preserved)
34
+ AGENTS.md (fully managed canonical repository contract)
30
35
  ```
31
36
 
32
37
  Ordinary projects no longer receive taskbook or closure logs. Existing optional
@@ -60,9 +65,13 @@ The result includes:
60
65
  - `execution_mode=isolated`: dirty checkout, explicit isolation, or multiple writers.
61
66
  - `execution_mode=none`: no task signal or change; create no branch/worktree.
62
67
  - `review_required` and `design_required`: risk-based escalation decisions.
68
+ - `mechanism_plan.required`: the complete minimum mechanism set for the task.
69
+ - `mechanism_plan.not_required`: mechanisms that stay off unless the user asks.
63
70
  - an adaptive agent plan that does not force fan-out for ordinary work.
64
71
 
65
- Use a machine-enforced task lifecycle when useful:
72
+ Clean serial work proceeds directly on the current branch with normal Git; it does
73
+ not create machine lifecycle state. Use `task-start` only when classification
74
+ requires isolation/review or the user explicitly requests lifecycle tracking:
66
75
 
67
76
  ```bash
68
77
  python3 docs/tools/autopipeline/ap.py task-start T0001 \
@@ -71,16 +80,15 @@ python3 docs/tools/autopipeline/ap.py commit-push T0001 \
71
80
  --msg "T0001: fix order retry"
72
81
  ```
73
82
 
74
- On a clean single-writer checkout, `task-start` records a lightweight direct
75
- manifest in the Git common directory and creates no branch or worktree.
76
- `commit-push` runs the final gate, commits, and pushes the current target branch.
77
- If no diff was produced, it clears the manifest without commit or push.
83
+ When a required review still uses the current clean checkout, `task-start` records
84
+ a direct manifest without creating a branch/worktree. If no diff is produced,
85
+ closure clears the manifest without commit or push.
78
86
 
79
87
  Dirty or parallel work receives an isolated task branch/worktree:
80
88
 
81
89
  ```bash
82
90
  python3 docs/tools/autopipeline/ap.py task-start T0002 \
83
- --owned-path backend --writers 2 --review-required
91
+ --owned-path backend --review-required
84
92
  # implement in the printed worktree
85
93
  python3 docs/tools/autopipeline/ap.py task-review T0002 \
86
94
  --verdict approved --diff-fingerprint "$SHA256"
@@ -93,6 +101,10 @@ Integration serializes the target push and removes clean merged worktrees and
93
101
  temporary branches. Unknown changes, unmerged history, unsafe ignored data, or
94
102
  dirty submodules block cleanup rather than being discarded.
95
103
 
104
+ Parallel development uses one task ID and one `task-start` per writer. `--writers`
105
+ belongs to `classify` planning only; the runtime rejects overlapping active
106
+ `owned_paths` and never creates multiple writers in one task/worktree.
107
+
96
108
  ## Real changed-scope validation
97
109
 
98
110
  Risk classification and validation execution are deliberately separate:
@@ -104,6 +116,8 @@ commands:
104
116
 
105
117
  validation:
106
118
  on_unmapped: error
119
+ max_command_seconds: 120
120
+ max_total_seconds: 180
107
121
  routes:
108
122
  - name: backend
109
123
  paths: ["backend/**", "contracts/**"]
@@ -138,6 +152,10 @@ closure gate is limited to one stable-diff run. Full regression, Docker, builds,
138
152
  Jenkins, deployment, API verification, and target checks remain explicit
139
153
  diagnostics outside normal closure.
140
154
 
155
+ The final closure gate is hard-bounded to at most 120 seconds per command and 180
156
+ seconds total; projects may lower those values. A timeout requires a narrower
157
+ route and never triggers a broader fallback.
158
+
141
159
  ## Risk and subagent policy
142
160
 
143
161
  - Micro and standard work default to the main agent.
@@ -152,13 +170,14 @@ diagnostics outside normal closure.
152
170
 
153
171
  The main agent owns architecture, final validation, Git closure, ordered
154
172
  integration, push, and cleanup. Push ends the coding task; later CI/acceptance is
155
- handled only through a separately requested diagnostic task.
173
+ not polled automatically. An explicitly requested failure diagnosis may continue
174
+ in the same conversation/task without an artificial second ledger lifecycle.
156
175
 
157
176
  ## Upgrade and multi-project sync
158
177
 
159
- Finish all in-flight schema-1/schema-2 registered tasks using their installed 3.x
160
- runtime before syncing 4.0. Batch sync fails before any writes when it finds an
161
- incompatible active task.
178
+ Finish every registered task using its currently installed runtime before syncing
179
+ a different Skill version. Batch sync fails before any writes when it finds an
180
+ active manifest, regardless of schema version.
162
181
 
163
182
  ```bash
164
183
  autocoding status --projects /path/a,/path/b
@@ -168,8 +187,36 @@ autocoding sync --projects /path/a,/path/b
168
187
 
169
188
  Sync replaces the managed Skill directory, so missing files are restored and
170
189
  obsolete managed files are removed. It preserves project frontmatter, access
171
- values, custom agents, explicit model overrides, optional documents, and content
172
- outside managed AGENTS/ENGINEERING blocks.
190
+ values, custom role agents, explicit model overrides, optional documents, and
191
+ project-specific facts outside the managed ENGINEERING block. Root `AGENTS.md` is
192
+ replaced as a whole; its previous content is archived under
193
+ `docs/archive/workflow/` as historical, non-authoritative context.
194
+
195
+ ## What changed in 4.1.1
196
+
197
+ - Added a machine-readable minimum mechanism plan and rejected unnecessary clean
198
+ serial task lifecycles unless explicitly requested.
199
+ - Added hard per-command and total time ceilings for the final changed-scope gate.
200
+ - Made root `AGENTS.md` the sole behavioral protocol, reduced `SKILL.md` to
201
+ invocation guidance, and reduced `ENGINEERING.md` to project configuration and
202
+ facts.
203
+
204
+ ## What changed in 4.1.0
205
+
206
+ - Made root `AGENTS.md` byte-identical across installed projects and whole-file
207
+ managed on every full sync/upgrade.
208
+ - Established code/tests/runtime as the source of current behavior and
209
+ `ENGINEERING.md` as the single project workflow/configuration source.
210
+ - Added an engineering-centered documentation framework plus optional
211
+ `docs/project/` fact templates.
212
+ - Prevented Skill upgrades while any registered task is active and recorded the
213
+ installed Skill version in new task manifests.
214
+ - Made reviewer scope bounded, with targeted recheck for mechanical docs-only
215
+ fixes and non-blocking handling of adjacent findings.
216
+ - Defined ledger/archive reconciliation as a terminal maintenance action, so
217
+ closing records cannot recursively create more task records.
218
+ - Kept explicit Jenkins failure diagnosis in the same requested task while
219
+ preserving push-as-completion and no automatic polling.
173
220
 
174
221
  ## What changed in 4.0.0
175
222
 
@@ -20,8 +20,9 @@ developer_instructions = """
20
20
  - 复现条件
21
21
  - 建议修法
22
22
  9. 发现测试不足时,指出应补哪些测试或验证路径。
23
- 10. 结论必须是 approved 或 changes-requested;changes-requested 只返回 owning_fixer,修改后必须基于新 diff 重审。
23
+ 10. 结论必须是 approved 或 changes-requested;changes-requested 只返回 owning_fixer,修改后必须绑定新的 diff fingerprint。代码、配置或行为语义变化需要重新审查;仅链接、归档索引、状态措辞等机械文档修正,可由同一 reviewer 只做 targeted recheck,不必重跑完整审计。
24
24
  11. 不修改代码,不提交、不推送、不集成、不清理分支;审查不扩展本地门禁。
25
25
  12. 最终只返回一个 JSON 对象,不要 Markdown 或代码围栏。对象必须符合 `.agents/skills/auto-coding-skill/data/contracts/orchestration-v1.schema.json#/$defs/agentResult`,包含全部必填字段,`contract_version` 固定为 1,`role` 固定为 `reviewer`,`changed_paths` 固定为空数组,`diff_fingerprint` 必须原样返回;审查完成时 `status=completed` 且 `verdict` 只能是 `approved` 或 `changes-requested`,无法继续时使用 `status=blocked`、`verdict=blocked`。findings 按 P0/P1/P2/P3 排序。
26
- 13. 目标分支推送成功后,不跟踪 Jenkins、部署或项目负责人的实际验收。
26
+ 13. 只阻断当前任务承诺范围内由本次变更新增或恶化的问题。相邻或既有问题写入 risks/follow-up,不得无限扩大当前任务和 review 范围。
27
+ 14. 目标分支推送成功后,不自动跟踪 Jenkins、部署或项目负责人的实际验收;用户明确要求诊断本次推送引发的失败时,可在同一会话和任务范围继续,不要求人为新建台账任务。
27
28
  """
@@ -1,127 +1,74 @@
1
1
  ---
2
2
  name: auto-coding-skill
3
- description: Delivery-first engineering workflow for repository changes. Use for analysis, task decomposition, necessary design, implementation, fast changed-scope validation, safe commit/push, adaptive Git isolation, parallel writer coordination, and temporary branch cleanup. Keep clean single-writer work on the current branch; escalate to worktrees, subagents, review, or stronger affected-scope checks only when risk or concurrency justifies them.
3
+ description: Delivery-first engineering workflow for repository changes. Use for analysis, task decomposition, necessary design, implementation, bounded changed-scope validation, safe commit/push, adaptive Git isolation, parallel writer coordination, and temporary branch cleanup. Keep clean serial work on the current branch and add lifecycle, worktrees, subagents, design, or review only when classify marks them required or the user explicitly requests them.
4
4
  ---
5
5
 
6
6
  # Auto Coding Skill
7
7
 
8
- Deliver changes through:
8
+ ## Use the two authorities
9
9
 
10
- `analysis → decomposition → necessary design → development → one final fast
11
- changed-scope gate → commit/push`.
12
-
13
- Read `docs/ENGINEERING.md` for project facts, access values, risk rules, and
14
- validation routes. Treat target-branch push as coding completion. Do not poll or
15
- fix Jenkins, deployment, or owner acceptance unless the user opens a separate
16
- diagnostic task.
10
+ Read root `AGENTS.md` for the shared behavioral protocol. Read
11
+ `docs/ENGINEERING.md` frontmatter for project facts, access values, risk rules,
12
+ validation routes, and time budgets. Do not reconstruct or duplicate those rules
13
+ from historical task documents.
17
14
 
18
- ## Choose the lightest safe path
15
+ Normal delivery is:
19
16
 
20
- Inspect the checkout before writing:
17
+ `analysis → decomposition → necessary design → development → one bounded final
18
+ changed-scope gate → commit/push`.
21
19
 
22
- - Use the current branch for one writer when the checkout is clean.
23
- - Use an isolated task branch/worktree when unrelated changes already exist,
24
- when more than one writer will run, or when the project explicitly requires it.
25
- - Use one writer per worktree and non-overlapping owned paths.
26
- - Create no temporary branch merely to analyze a task or when no diff is produced.
27
- - Never restore, reset, stash, clean, or modify unknown user/task changes.
20
+ ## Select the minimum mechanism set
28
21
 
29
- Classify planned work before development when impact is unclear:
22
+ Skip classification for read-only work, obvious clean serial edits, and terminal
23
+ ledger maintenance. When impact, risk, or concurrency is unclear, run:
30
24
 
31
25
  ```bash
32
26
  python3 docs/tools/autopipeline/ap.py classify --scope auto \
33
27
  --planned-path <PATH> --intent "<intent>" [--writers <N>]
34
28
  ```
35
29
 
36
- `execution_mode=direct` means stay on the current branch.
37
- `execution_mode=isolated` means start registered worktrees. `execution_mode=none`
38
- means do not create Git state.
30
+ Follow `mechanism_plan.required`. Do not add anything listed under
31
+ `mechanism_plan.not_required` unless the user explicitly requests it. In
32
+ particular, ordinary direct work does not create a task lifecycle.
39
33
 
40
- Use the runtime-supported lifecycle when a machine-enforced task boundary helps:
34
+ Use the registered lifecycle only when classification requires isolation or
35
+ fingerprinted review, or when the user explicitly requests it:
41
36
 
42
37
  ```bash
43
38
  python3 docs/tools/autopipeline/ap.py task-start T0001 \
44
- --owned-path src [--writers 2] [--isolated] [--review-required]
45
- # Work in the path printed by task-start.
39
+ --owned-path src [--isolated] [--review-required]
46
40
  python3 docs/tools/autopipeline/ap.py commit-push T0001 --msg "T0001: summary"
47
41
  # Isolated tasks only:
48
42
  python3 docs/tools/autopipeline/ap.py task-integrate T0001
49
43
  ```
50
44
 
51
- Direct `commit-push` runs the final gate and pushes the current target branch.
52
- If the task has no diff, it clears its machine state without commit or push.
53
- Isolated `commit-push` pushes the task branch; `task-integrate` serializes the
54
- target push and removes clean merged temporary worktrees and branches. Use
55
- `task-finish` or `task-prune` only for safe lifecycle cleanup.
56
-
57
- ## Scale design and review by risk
58
-
59
- Use `micro`, `standard`, and `high-risk` only to scale reasoning and guardrails;
60
- never use them to trigger a full local repository gate automatically.
61
-
62
- - Keep ordinary micro/standard work main-agent-only unless delegation has a
63
- concrete latency or expertise benefit.
64
- - Create DD/ADR only for lasting cross-module, API, data, security, deployment,
65
- or key user-flow decisions.
66
- - Require independent fingerprinted review for high-risk, cross-module,
67
- explicitly configured, or parallel integration work.
68
- - Route blocking review findings back to the owning writer and invalidate the
69
- approval after any content change or rebase.
70
-
71
- Historical debt does not block normal delivery. Block only new or worsened P0/P1
72
- issues. Handle repository-wide governance through an explicit task and optional
73
- baseline/backlog.
45
+ Each parallel writer uses a distinct task ID, registered worktree, writer lease,
46
+ dependency SHAs, and non-overlapping `owned_paths`. The main agent alone runs the
47
+ final gate, integrates, pushes, and cleans safely merged temporary branches.
74
48
 
75
- ## Use subagents when they improve throughput
76
-
77
- Let the main agent own decomposition, architecture, dependencies, final gate,
78
- Git closure, integration, and cleanup.
79
-
80
- - Run independent read-only explorer, docs, or browser questions in parallel.
81
- - Dispatch fixers only for bounded, dependency-free units with non-overlapping
82
- paths; give each parallel fixer its own registered worktree.
83
- - Start dependent writers only after prerequisite commits are integrated.
84
- - Add a reviewer only when the risk policy requires one.
85
- - Do not force fan-out for small serial tasks.
86
-
87
- Subagents do not commit, push, integrate, clean branches, or run the final project
88
- gate. Use the bundled orchestration contract when structured assignments/results
89
- are useful; ordinary main-agent work needs no task ledger.
90
-
91
- ## Run real changed-scope validation
92
-
93
- Keep classification under `risk.rules` and executable checks under
94
- `validation.routes`. Match every changed path against all routes, collect command
95
- references in configuration order, remove duplicates, and run each once.
49
+ ## Close with the bounded routed gate
96
50
 
97
51
  ```bash
98
52
  python3 docs/tools/autopipeline/ap.py validation-map-check --path <PATH>
99
53
  python3 docs/tools/autopipeline/ap.py light-gate --scope changed --explain
100
54
  ```
101
55
 
102
- - Fail before staging when changed code is unmapped or a route references a
103
- missing/blank command.
104
- - Allow docs-only changes to use the built-in diff check.
105
- - Treat `git diff --check` as additional hygiene, never as business validation.
106
- - Allow focused tests and test/fix/retest loops during development.
107
- - Run one final routed closure gate after the diff is stable.
108
- - Do not automatically run full regression, Docker, builds, Jenkins, deployment,
109
- API verification, or target checks.
110
- - Do not automatically install dependencies. If the final route needs a locked
111
- dependency absent from the checkout, restore it once and retry only that route.
112
-
113
- ## Keep project state small
56
+ Every changed code/config path must map to a real project command. The runtime
57
+ de-duplicates matched commands and enforces both per-command and total closure
58
+ budgets. A timeout means the route must be narrowed; it never falls back to a full
59
+ build. Focused test/fix/retest loops remain allowed before the final gate.
114
60
 
115
- Store task manifests, ownership, leases, dependencies, and review fingerprints in
116
- the Git common directory. Store gate timing/evidence under `.local` by default.
117
- Do not create taskbook, closure Markdown, evidence JSONL, active-task, or design
118
- documents for ordinary work. Preserve existing project documents as user data;
119
- create or update them only when explicitly useful.
61
+ Run full regression, Docker, Jenkins, deployment, browser/device writes, or target
62
+ acceptance only as an explicit diagnostic. If the user asks to diagnose the
63
+ just-pushed failure, continue in the same conversation/task without inventing a
64
+ new ledger lifecycle.
120
65
 
121
- Keep `docs/ENGINEERING.md` as the only manual workflow configuration source.
122
- Allow direct plaintext values under `access.*`; do not invent or echo credentials.
66
+ ## Keep state and upgrades safe
123
67
 
124
- ## Install and upgrade
68
+ Machine task state, leases, fingerprints, and gate evidence stay in Git
69
+ common/local state. Ordinary work creates no taskbook, closure Markdown, evidence
70
+ JSONL, active-task, or design artifact. Terminal ledger reconciliation validates
71
+ and commits once without creating another lifecycle.
125
72
 
126
73
  ```bash
127
74
  autocoding init
@@ -131,7 +78,6 @@ python3 docs/tools/autopipeline/ap.py upgrade --write
131
78
  python3 docs/tools/autopipeline/ap.py doctor
132
79
  ```
133
80
 
134
- Finish in-flight pre-4.0 registered tasks before syncing the 4.0 runtime. Upgrade
135
- must preserve project configuration, access values, custom agents, optional
136
- documents, and explicit model overrides while removing obsolete managed Skill
137
- files and filling new managed assets.
81
+ Finish registered tasks before changing runtime versions. Sync replaces the
82
+ canonical root `AGENTS.md`, archives its previous content, preserves project facts
83
+ and access values, and converges all managed Skill/runtime/agent assets together.
@@ -11,6 +11,17 @@
11
11
  "type": "string"
12
12
  }
13
13
  },
14
+ "mechanismPlan": {
15
+ "type": "object",
16
+ "required": ["required", "not_required", "lifecycle_required", "rule"],
17
+ "properties": {
18
+ "required": { "$ref": "#/$defs/stringArray" },
19
+ "not_required": { "$ref": "#/$defs/stringArray" },
20
+ "lifecycle_required": { "type": "boolean" },
21
+ "rule": { "type": "string", "minLength": 1 }
22
+ },
23
+ "additionalProperties": false
24
+ },
14
25
  "fingerprint": {
15
26
  "type": "string",
16
27
  "pattern": "^$|^[0-9a-f]{64}$"
@@ -444,7 +455,8 @@
444
455
  "profile",
445
456
  "categories",
446
457
  "recommended_agents",
447
- "agent_plan"
458
+ "agent_plan",
459
+ "mechanism_plan"
448
460
  ],
449
461
  "properties": {
450
462
  "contract_version": {
@@ -483,6 +495,9 @@
483
495
  },
484
496
  "agent_plan": {
485
497
  "$ref": "#/$defs/agentPlan"
498
+ },
499
+ "mechanism_plan": {
500
+ "$ref": "#/$defs/mechanismPlan"
486
501
  }
487
502
  },
488
503
  "additionalProperties": true