@elvis1513/auto-coding-skill 2.2.0 → 3.0.0

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
@@ -4,6 +4,31 @@ A generic `.agents` engineering workflow with adaptive execution profiles,
4
4
  minimal project scaffolding, evidence-backed closure, and optional CI/Jenkins and
5
5
  target-environment verification.
6
6
 
7
+ ## What changed in v3.0.0
8
+
9
+ - Isolated every write task in a registered Git worktree and task branch.
10
+ - Added `task-start`, `task-status`, `task-submodule-sync`, `task-integrate`,
11
+ `task-finish`, and `task-prune` lifecycle commands.
12
+ - Made `commit-push` validate the task manifest before any gate or ledger write,
13
+ stage only the task worktree's exact paths, and detect gate-time mutations.
14
+ - Added task-scoped active, closure, and evidence records to avoid shared append
15
+ conflicts.
16
+ - Serialized target-branch integration and re-ran the resolved gate after
17
+ updating to the latest remote target.
18
+ - Automatically removed integrated worktrees and local task branches, with safe
19
+ lease-based remote task-branch cleanup and merged-branch pruning.
20
+ - Kept `concurrency.isolation: legacy` only as an explicit compatibility escape
21
+ hatch; missing configuration now defaults to worktree isolation.
22
+
23
+ ## What changed in v2.2.1
24
+
25
+ - Made same-period ledger archiving update one cumulative archive-index entry
26
+ instead of appending duplicate month headings.
27
+ - Recognized Markdown-wrapped and localized settled statuses such as
28
+ `` `Done / PASS` `` and `Done(PASS)` during physical history archiving.
29
+ - Added regression coverage for repeated same-month archives and these status
30
+ formats.
31
+
7
32
  ## What changed in v2.2.0
8
33
 
9
34
  - Added `micro`, `standard`, and `high-risk` execution profiles.
@@ -84,6 +109,59 @@ python3 docs/tools/autopipeline/ap.py impact --scope auto --json
84
109
  Each result includes the effective profile, mode, gate scope, reasons, required
85
110
  verification surfaces, and recommended Agent roles.
86
111
 
112
+ ## Parallel write isolation
113
+
114
+ Each task that may write files runs in its own registered Git worktree and
115
+ `codex/` task branch. Read-only discovery may remain in the primary worktree.
116
+
117
+ ```yaml
118
+ concurrency:
119
+ isolation: worktree
120
+ base_ref: origin/dev
121
+ target_branch: dev
122
+ branch_prefix: codex/
123
+ worktree_root: ../.worktrees
124
+ cleanup_merged: true
125
+ delete_remote_branch: true
126
+ disposable_ignored: []
127
+ ```
128
+
129
+ ```bash
130
+ python3 docs/tools/autopipeline/ap.py task-start T0001
131
+ # Continue in the worktree path printed by task-start.
132
+ python3 docs/tools/autopipeline/ap.py task-status T0001
133
+ python3 docs/tools/autopipeline/ap.py task-submodule-sync T0001
134
+ python3 docs/tools/autopipeline/ap.py commit-push T0001 --msg "T0001: summary"
135
+ python3 docs/tools/autopipeline/ap.py task-integrate T0001
136
+ ```
137
+
138
+ `commit-push` runs only inside the task worktree recorded in the repository
139
+ manifest and stages only that task's changes. Unknown changes stop the command;
140
+ the workflow never restores, resets, stashes, or cleans them.
141
+
142
+ Successful integration removes the clean worktree and merged local branch, and
143
+ deletes the merged remote task branch by default. `task-finish T0001` retries
144
+ cleanup for one integrated task; `task-prune` removes registered merged tasks
145
+ left behind. Dirty worktrees and unmerged branches are never removed. Integration
146
+ does not update the primary checkout; pull it explicitly when its local state is
147
+ ready. Cleanup also refuses unknown ignored files such as local secrets; list
148
+ only disposable project cache/build paths under `concurrency.disposable_ignored`.
149
+ Initialized submodules are recursively checked before forced task-worktree
150
+ removal: they must be clean and contain no unknown ignored data, local-only
151
+ commits, unmirrored local branches, or additional linked worktrees. Their
152
+ remotes are refreshed before that decision. A durable snapshot
153
+ of refs and reflog commits is stored under Git's
154
+ `auto-coding-skill/submodule-recovery` state before forced worktree removal, so
155
+ a remote deletion race cannot destroy the last copy of a commit. Cleanup never
156
+ deinitializes the primary checkout's shared submodule configuration.
157
+ `task-start` enables Git worktree-scoped config and seeds each task's submodule
158
+ URLs. After changing `.gitmodules`, run `task-submodule-sync` before initializing
159
+ or syncing modules. Relative URLs follow Git's current-worktree default-remote
160
+ rules, including task bases whose `.gitmodules` differs from the control checkout.
161
+ Shared/common submodule config changes are reported and never overwritten.
162
+ Residual Git directories from modules manually deinitialized inside a task block
163
+ forced cleanup until they are reinitialized or recovered.
164
+
87
165
  ## Gate configuration
88
166
 
89
167
  ```yaml
@@ -190,9 +268,15 @@ python3 docs/tools/autopipeline/ap.py doctor
190
268
  python3 docs/tools/autopipeline/ap.py classify --scope auto
191
269
  python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
192
270
  python3 docs/tools/autopipeline/ap.py structure-check --scope auto
271
+ python3 docs/tools/autopipeline/ap.py task-start T0001
272
+ python3 docs/tools/autopipeline/ap.py task-status T0001
273
+ python3 docs/tools/autopipeline/ap.py task-submodule-sync T0001
193
274
  python3 docs/tools/autopipeline/ap.py docs-ledger-check
194
275
  python3 docs/tools/autopipeline/ap.py gate-profile
195
276
  python3 docs/tools/autopipeline/ap.py commit-push T0001 --msg "T0001: summary"
277
+ python3 docs/tools/autopipeline/ap.py task-integrate T0001
278
+ python3 docs/tools/autopipeline/ap.py task-finish T0001
279
+ python3 docs/tools/autopipeline/ap.py task-prune
196
280
  ```
197
281
 
198
282
  ## Upgrade and multi-project sync
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: auto-coding-skill
3
- description: Generic .agents engineering workflow with adaptive micro, standard, and high-risk execution profiles; minimal project scaffold; dev and verified closure modes.
3
+ description: Generic .agents engineering workflow with isolated Git worktrees for parallel write tasks, adaptive micro/standard/high-risk profiles, minimal project scaffolding, safe integration and branch cleanup, and evidence-backed dev or verified closure.
4
4
  ---
5
5
 
6
6
  # Auto Coding Skill
@@ -61,16 +61,62 @@ python3 docs/tools/autopipeline/ap.py classify --scope auto
61
61
  python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
62
62
  ```
63
63
 
64
+ ## Parallel write isolation
65
+
66
+ Every task that may write files must use its own registered Git worktree and
67
+ task branch. Read-only discovery may stay in the primary worktree.
68
+
69
+ ```bash
70
+ python3 docs/tools/autopipeline/ap.py task-start <TASK_ID>
71
+ # Continue in the worktree path printed by task-start.
72
+ python3 docs/tools/autopipeline/ap.py task-status <TASK_ID>
73
+ python3 docs/tools/autopipeline/ap.py task-submodule-sync <TASK_ID>
74
+ python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>"
75
+ python3 docs/tools/autopipeline/ap.py task-integrate <TASK_ID>
76
+ ```
77
+
78
+ `task-start` records the base revision, target branch, task branch, and worktree
79
+ in the repository manifest. `commit-push` is valid only inside that task's
80
+ registered worktree and may stage only changes owned by that task. If unknown
81
+ changes appear, stop and report them. Never restore, reset, stash, clean, or
82
+ otherwise modify another task's or the user's changes.
83
+
84
+ After a successful integration, remove the clean worktree and merged local task
85
+ branch. Delete the merged remote task branch by default. Use `task-finish` to
86
+ retry cleanup for one integrated task and `task-prune` to clean registered merged
87
+ tasks in bulk. Refuse cleanup when a worktree is dirty or a branch is unmerged.
88
+ Do not update the primary checkout during integration; pull it explicitly when
89
+ its user-owned state is ready. Treat unknown ignored files as user data and
90
+ block cleanup; allow only explicitly disposable cache/build paths. Before a
91
+ forced task-worktree removal, recursively require every initialized submodule
92
+ to be clean and contain no unknown ignored data, local-only history, or
93
+ unmirrored local branch. Block cleanup when the submodule has another linked
94
+ worktree or its remotes cannot be refreshed. Before the validated forced removal,
95
+ persist its refs and reflog commits in the Git common directory's managed
96
+ submodule-recovery store so a remote race cannot erase the final copy. Never run
97
+ submodule deinit from a linked task worktree because its shared config can alter
98
+ the primary checkout.
99
+
100
+ `task-start` enables Git worktree-scoped config and seeds task-local submodule
101
+ URLs. After editing `.gitmodules`, run `task-submodule-sync` before submodule
102
+ initialization or sync. Resolve relative URLs with Git's current-worktree
103
+ default-remote semantics, not the integration remote. If shared/common submodule
104
+ config differs from the task-start snapshot, stop and report it without restoring
105
+ or overwriting the value. Treat residual module Git directories from a manual
106
+ deinit/removal as user data: block forced cleanup until they are reinitialized or
107
+ explicitly recovered.
108
+
64
109
  ## Development closure
65
110
 
66
- 1. Locate the real entry point, call chain, existing owner module, tests, and
111
+ 1. Start the write task with `task-start` and enter its registered worktree.
112
+ 2. Locate the real entry point, call chain, existing owner module, tests, and
67
113
  reusable helpers.
68
- 2. Update the active task with the smallest useful design note.
69
- 3. Create DD/ADR only for cross-module, API, DB, deployment/CI, security, key UI
114
+ 3. Update the active task with the smallest useful design note.
115
+ 4. Create DD/ADR only for cross-module, API, DB, deployment/CI, security, key UI
70
116
  flow, or lasting structural decisions.
71
- 4. Implement only necessary changes.
72
- 5. Run the resolved gate.
73
- 6. Record `DEV-CLOSED`, commit, push, and stop.
117
+ 5. Implement only necessary changes.
118
+ 6. Run the resolved gate.
119
+ 7. Record `DEV-CLOSED`, commit, push, integrate, and clean the task worktree.
74
120
 
75
121
  ## Verified closure
76
122
 
@@ -80,6 +126,7 @@ High-risk or explicitly verified work uses the strongest path:
80
126
  2. Commit and push.
81
127
  3. Verify enabled CI/Jenkins and target-environment surfaces.
82
128
  4. Record `PASS`, `FAIL`, or `PARTIAL` only from executed evidence.
129
+ 5. Integrate successful work and clean its temporary worktree and branches.
83
130
 
84
131
  ## Structure policy
85
132
 
@@ -130,7 +177,13 @@ python3 docs/tools/autopipeline/ap.py scaffold all --write
130
177
  python3 docs/tools/autopipeline/ap.py docs-ledger-check
131
178
  python3 docs/tools/autopipeline/ap.py docs-ledger-archive --plan
132
179
  python3 docs/tools/autopipeline/ap.py gate-profile
180
+ python3 docs/tools/autopipeline/ap.py task-start <TASK_ID>
181
+ python3 docs/tools/autopipeline/ap.py task-status <TASK_ID>
182
+ python3 docs/tools/autopipeline/ap.py task-submodule-sync <TASK_ID>
133
183
  python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>"
184
+ python3 docs/tools/autopipeline/ap.py task-integrate <TASK_ID>
185
+ python3 docs/tools/autopipeline/ap.py task-finish <TASK_ID>
186
+ python3 docs/tools/autopipeline/ap.py task-prune
134
187
  ```
135
188
 
136
189
  `status` and `sync` manage only the minimal required scaffold. Existing optional
@@ -8,6 +8,16 @@ project:
8
8
  repo_root: "."
9
9
  stack: "generic"
10
10
 
11
+ concurrency:
12
+ isolation: "worktree"
13
+ base_ref: ""
14
+ target_branch: ""
15
+ branch_prefix: "codex/"
16
+ worktree_root: "../.worktrees"
17
+ cleanup_merged: true
18
+ delete_remote_branch: true
19
+ disposable_ignored: []
20
+
11
21
  commands:
12
22
  gate_changed: ""
13
23
  gate_standard: ""
@@ -84,6 +94,9 @@ docs:
84
94
  taskbook: "docs/tasks/taskbook.md"
85
95
  closure_log: "docs/tasks/closure-log.md"
86
96
  evidence_log: "docs/tasks/evidence.jsonl"
97
+ active_task_dir: "docs/tasks/active"
98
+ task_closure_dir: "docs/tasks/closures"
99
+ task_evidence_dir: "docs/tasks/evidence"
87
100
  design_dir: "docs/design"
88
101
  task_archive_dir: "docs/tasks/archives"
89
102
  design_archive_dir: "docs/archive/design"
@@ -135,6 +148,15 @@ Required for normal development:
135
148
  - `workflow.mode`: `dev` or `verify`
136
149
  - `workflow.profile`: `auto`, `micro`, `standard`, or `high-risk`
137
150
  - `project.name`
151
+ - `concurrency.isolation`: keep `worktree` for every task that may write files
152
+ - `concurrency.base_ref` and `target_branch`: leave blank to derive the current
153
+ upstream, or set them explicitly for a fixed integration branch
154
+ - `concurrency.branch_prefix` and `worktree_root`
155
+ - `concurrency.cleanup_merged` and `delete_remote_branch`: keep both enabled to
156
+ remove integrated temporary worktrees and branches
157
+ - `concurrency.disposable_ignored`: add only project-specific ignored cache/build
158
+ paths that may be discarded with a task worktree; ignored secrets and unknown
159
+ paths block cleanup, including inside initialized submodules
138
160
  - at least one usable gate command; configure all three gate commands when the
139
161
  project can exercise changed, standard, and full scopes
140
162
  - `verification.target_env_required` and `verification.jenkins_required`
@@ -149,16 +171,57 @@ enabled, add `jenkins` with its base/job URLs, branch, artifact/deploy metadata,
149
171
  timeout, UI/API users, and password values or environment references. Unused
150
172
  sections should remain absent rather than filled with placeholders.
151
173
 
174
+ ## Concurrent write tasks
175
+
176
+ Run every write task in a registered Git worktree and task branch. Do not share
177
+ the primary worktree between writers.
178
+
179
+ ```bash
180
+ python3 docs/tools/autopipeline/ap.py task-start <TASK_ID>
181
+ # Enter the worktree path printed by task-start.
182
+ python3 docs/tools/autopipeline/ap.py task-status <TASK_ID>
183
+ python3 docs/tools/autopipeline/ap.py task-submodule-sync <TASK_ID>
184
+ python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>"
185
+ python3 docs/tools/autopipeline/ap.py task-integrate <TASK_ID>
186
+ ```
187
+
188
+ `task-start` fixes the task's base revision and records its task branch and
189
+ worktree in the repository manifest. Run `commit-push` only from that registered
190
+ worktree. Stage only task-owned paths. If an unknown change appears, stop and
191
+ report it; never restore, reset, stash, clean, or otherwise alter it.
192
+
193
+ Successful integration removes the clean worktree and merged local branch, and
194
+ deletes the merged remote task branch by default. Use `task-finish <TASK_ID>` to
195
+ retry cleanup for one integrated task and `task-prune` for registered merged
196
+ tasks left behind. Cleanup must refuse dirty worktrees and unmerged branches.
197
+ Before forced task-worktree removal, recursively require initialized submodules
198
+ to be clean and contain no unknown ignored data, local-only history, or
199
+ unmirrored local branches. A submodule with another linked worktree or an
200
+ unrefreshable remote blocks cleanup. Before forced worktree removal, persist its
201
+ refs and reflog commits in the managed Git-common-dir submodule recovery store.
202
+ Do not run submodule deinit from a linked task worktree because its shared config
203
+ can alter the primary checkout.
204
+ `task-start` enables worktree-scoped Git config and seeds task-local submodule
205
+ URLs. After changing `.gitmodules`, run `task-submodule-sync` before submodule
206
+ initialization or sync. Resolve relative URLs with Git's current-worktree
207
+ default-remote semantics. If shared/common submodule config changed after task
208
+ start, report and stop without restoring or overwriting it. Residual module Git
209
+ directories from a manual deinit or removal block forced cleanup until they are
210
+ reinitialized or recovered.
211
+ Integration must not update the primary checkout; pull it explicitly only when
212
+ its user-owned state is ready.
213
+
152
214
  ## Default workflow
153
215
 
154
216
  Development:
155
217
 
156
218
  1. Read this file and the active task entry.
157
- 2. Run or reason through `classify --scope auto`.
158
- 3. Record the smallest useful design note; create DD/ADR only when indicated.
159
- 4. Implement the necessary change using existing project structure and reuse points.
160
- 5. Run the resolved profile gate.
161
- 6. Record `DEV-CLOSED`, commit, and push.
219
+ 2. Start the write task with `task-start` and enter its registered worktree.
220
+ 3. Run or reason through `classify --scope auto`.
221
+ 4. Record the smallest useful design note; create DD/ADR only when indicated.
222
+ 5. Implement the necessary change using existing project structure and reuse points.
223
+ 6. Run the resolved profile gate.
224
+ 7. Record `DEV-CLOSED`, commit, push, integrate, and clean the task worktree.
162
225
 
163
226
  High-risk or explicit verification:
164
227
 
@@ -166,6 +229,7 @@ High-risk or explicit verification:
166
229
  2. Commit and push.
167
230
  3. Verify enabled CI/Jenkins and target-environment surfaces.
168
231
  4. Record `PASS`, `FAIL`, or `PARTIAL` from actual evidence.
232
+ 5. Integrate successful work and clean its temporary worktree and branches.
169
233
 
170
234
  The authoritative order remains ENGINEERING, taskbook/archives, design and
171
235
  interface records, regression/bug records, closure evidence, deployment records,
@@ -210,7 +274,13 @@ python3 docs/tools/autopipeline/ap.py doctor
210
274
  python3 docs/tools/autopipeline/ap.py classify --scope auto
211
275
  python3 docs/tools/autopipeline/ap.py light-gate --scope auto --explain
212
276
  python3 docs/tools/autopipeline/ap.py structure-check --scope auto
277
+ python3 docs/tools/autopipeline/ap.py task-start <TASK_ID>
278
+ python3 docs/tools/autopipeline/ap.py task-status <TASK_ID>
279
+ python3 docs/tools/autopipeline/ap.py task-submodule-sync <TASK_ID>
213
280
  python3 docs/tools/autopipeline/ap.py commit-push <TASK_ID> --msg "<TASK_ID>: <summary>"
281
+ python3 docs/tools/autopipeline/ap.py task-integrate <TASK_ID>
282
+ python3 docs/tools/autopipeline/ap.py task-finish <TASK_ID>
283
+ python3 docs/tools/autopipeline/ap.py task-prune
214
284
  python3 docs/tools/autopipeline/ap.py docs-ledger-check
215
285
  python3 docs/tools/autopipeline/ap.py gate-profile
216
286
  ```