dsh-work-fish 0.2.0 → 0.2.2

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.
@@ -40,8 +40,8 @@ import { fileURLToPath } from 'node:url'
40
40
  import { bundleRoots, inspect, trustedRoots } from './approve-paths.mjs'
41
41
  import { resolveWorkHome } from '../tools/lib/paths.mjs'
42
42
 
43
- /** Absolute path of this package's directory (`lib/`), the bundle's own root. */
44
- const PACKAGE_DIR = dirname(dirname(fileURLToPath(import.meta.url)))
43
+ /** Absolute path of the package root (this file sits in `<package>/lib/core/`). */
44
+ export const PACKAGE_DIR = dirname(dirname(dirname(fileURLToPath(import.meta.url))))
45
45
 
46
46
  /** Plugin name used by the loader / Cordis row. */
47
47
  export const name = 'wf-approve'
@@ -125,9 +125,9 @@ const MAX_REPORTS = 40
125
125
  const MAX_PERSONA_BYTES = 96 * 1024
126
126
 
127
127
  /** The package version, read once for `/wf/info`. */
128
- const VERSION = (() => {
128
+ export const VERSION = (() => {
129
129
  try {
130
- return String(JSON.parse(fs.readFileSync(path.join(DIR, '..', 'package.json'), 'utf8')).version ?? '')
130
+ return String(JSON.parse(fs.readFileSync(path.join(DIR, '..', '..', 'package.json'), 'utf8')).version ?? '')
131
131
  } catch {
132
132
  return ''
133
133
  }
@@ -0,0 +1,80 @@
1
+ /**
2
+ * Guards the package-root derivations.
3
+ *
4
+ * Every module under `lib/` resolves the package root from its own URL; the
5
+ * 0.2.0 restructure (code moved from `<pkg>/core/` into `<pkg>/lib/core/`) left
6
+ * three of them one level short, and nothing failed loudly: the skills row threw
7
+ * ENOENT and took the whole preset down, `/wf/info` silently reported an empty
8
+ * version, and the auto-approver trusted `<pkg>/lib` instead of `<pkg>`.
9
+ *
10
+ * These assertions fail the moment a path derivation drifts again.
11
+ */
12
+
13
+ import test from 'node:test'
14
+ import assert from 'node:assert/strict'
15
+ import fs from 'node:fs'
16
+ import os from 'node:os'
17
+ import path from 'node:path'
18
+ import { fileURLToPath } from 'node:url'
19
+
20
+ import { VERSION } from './index.mjs'
21
+ import { PACKAGE_DIR } from './approve.mjs'
22
+ import { apply as applySkills } from './skills.mjs'
23
+ import { bootstrap } from './bootstrap.mjs'
24
+
25
+ /** This file sits in `<pkg>/lib/core/`, so the package root is two levels up. */
26
+ const PKG = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
27
+
28
+ test('VERSION is read from the package manifest', () => {
29
+ const manifest = JSON.parse(fs.readFileSync(path.join(PKG, 'package.json'), 'utf8'))
30
+ assert.equal(VERSION, manifest.version)
31
+ assert.match(VERSION, /^\d+\.\d+\.\d+$/)
32
+ })
33
+
34
+ test('the auto-approver trusts the package root, not lib/', () => {
35
+ assert.equal(PACKAGE_DIR, PKG)
36
+ assert.ok(fs.existsSync(path.join(PACKAGE_DIR, 'package.json')))
37
+ })
38
+
39
+ test('bundled skills are read from <pkg>/skills', () => {
40
+ /** @type {{path: string}[]} */
41
+ const registered = []
42
+ const ctx = {
43
+ skills: { register: (skill) => registered.push(skill) },
44
+ logger: { info() {}, warn() {} },
45
+ }
46
+ applySkills(ctx)
47
+
48
+ const skillsRoot = path.join(PKG, 'skills')
49
+ const expected = fs
50
+ .readdirSync(skillsRoot, { withFileTypes: true })
51
+ .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(skillsRoot, entry.name, 'SKILL.md')))
52
+
53
+ assert.equal(registered.length, expected.length)
54
+ for (const skill of registered) {
55
+ assert.ok(skill.path.startsWith(skillsRoot + path.sep), `skill outside <pkg>/skills: ${skill.path}`)
56
+ }
57
+ })
58
+
59
+ test('bootstrap points the rules index at files that exist', () => {
60
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), 'wf-paths-'))
61
+ try {
62
+ bootstrap(home)
63
+ const index = fs.readFileSync(path.join(home, 'rules', 'INDEX.md'), 'utf8')
64
+
65
+ const rule = index.match(/\]\(([^)]+code-rules\.md)\)/)
66
+ assert.ok(rule, 'rules/INDEX.md carries no rule link')
67
+ // The generated index uses forward slashes; resolve before comparing.
68
+ const rulePath = path.resolve(rule[1])
69
+ assert.ok(fs.existsSync(rulePath), `rule link points nowhere: ${rule[1]}`)
70
+ assert.ok(rulePath.startsWith(path.resolve(PKG, 'rules') + path.sep), 'rule link is not inside <pkg>/rules')
71
+
72
+ const tools = index.match(/no `tools\/` directory: `([^`]+)`/)
73
+ assert.ok(tools, 'rules/INDEX.md carries no tools path')
74
+ const toolsPath = path.resolve(tools[1])
75
+ assert.ok(fs.existsSync(toolsPath), `tools path points nowhere: ${tools[1]}`)
76
+ assert.equal(toolsPath, path.resolve(PKG, 'lib', 'tools'))
77
+ } finally {
78
+ fs.rmSync(home, { recursive: true, force: true })
79
+ }
80
+ })
@@ -15,8 +15,12 @@ import fs from 'node:fs'
15
15
  import path from 'node:path'
16
16
  import { fileURLToPath } from 'node:url'
17
17
 
18
- /** `<package>/skills`, resolved from this file rather than from `process.cwd()`. */
19
- const SKILLS_DIR = fileURLToPath(new URL('../skills', import.meta.url))
18
+ /**
19
+ * `<package>/skills`, resolved from this file rather than from `process.cwd()`.
20
+ * This module sits in `<package>/lib/core/`, so the package root is two levels up
21
+ * and the skills directory is a sibling of `lib/`, not of `core/`.
22
+ */
23
+ const SKILLS_DIR = fileURLToPath(new URL('../../skills', import.meta.url))
20
24
 
21
25
  /** Provider label stored on every registered skill. */
22
26
  const SOURCE = 'dsh-work-fish'
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-work-fish",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "license": "MIT",
5
5
  "description": "Unofficial Work Fish plugin for DeepSeek Harness: task setup, task board tracking and delivery, with a floating task panel. Not affiliated with DeepSeek.",
6
6
  "type": "module",
@@ -1,80 +1,513 @@
1
1
  ---
2
2
  name: git-flow
3
- description: Git operations end to end: authorisation, four checks before committing, message format, one commit per task, stash handling, and a hard ban on rewriting published remote history. Read before running git commit, push or any remote-altering command. Extra rules for bookkeeping commits are in §0.
4
- whenToUse: About to run git commit, git push, or anything that changes a remote (force, delete, retag); the user says "提交" or "入库"; a task is closing out and has to land in history.
3
+ description: "End-to-end Git workflow covering authorization, remote synchronization, pre-commit checks, commit message conventions, one commit per task, stash management, and remote history protection. Read before running git commit, git push, or any remote-altering command."
4
+ whenToUse: Before committing, pushing, or changing remote references; when the user requests a commit or push; or when a task is ready to be recorded in Git history.
5
5
  ---
6
6
 
7
- # Git flow
7
+ # Git Flow
8
8
 
9
- ## 0. Which kind of commit is this?
9
+ ## 0. Identify the Repository Type
10
10
 
11
- | Target | Rules |
11
+ First, identify which repository the operation targets.
12
+
13
+ | Target | Applicable Rules |
12
14
  |---|---|
13
- | A project repository (business code) | §1–§6 |
14
- | The workbench (`tasks/` / `memory/` / `rules/`) | §1, §3 and §6. Keep the reviewed snapshot and any "unreviewed" marker out of the body; the `wf-*` write tools are what guarantee compliance. |
15
+ | Project repository (business code) | Follow all sections. |
16
+ | Workbench repository (`tasks/`, `memory/`, `rules/`) | Follow the authorization, commit-message, and remote-history rules, together with the dedicated workbench write rules. |
17
+
18
+ Additional requirements for workbench repositories:
19
+
20
+ - Keep reviewed snapshots and any `unreviewed` markers out of commit message bodies.
21
+ - Use the `wf-*` write tools to make workbench changes; these tools enforce the required write workflow.
22
+
23
+ ## 1. Authorization and Scope
24
+
25
+ ### 1.1 Commit and Push Authorization
26
+
27
+ - Commit only when the user explicitly requests a commit or asks to save changes to Git in the current task.
28
+ - If the user has not requested a commit, modify files without committing.
29
+ - Push only when the user explicitly requests a push.
30
+ - Authorization from previous tasks does not carry over to the current task.
31
+
32
+ ### 1.2 Repository and File Scope
33
+
34
+ Run all Git commands with an explicit repository path:
35
+
36
+ ```bash
37
+ git -C <repo> <command>
38
+ ```
39
+
40
+ Do not rely on the current working directory to identify the repository.
41
+
42
+ Before changing Git state, inspect the repository:
43
+
44
+ ```bash
45
+ git -C <repo> status --short
46
+ git -C <repo> diff
47
+ git -C <repo> diff --cached
48
+ ```
49
+
50
+ Identify the current branch, its upstream, and which files belong to the current task. Preserve changes belonging to other tasks.
51
+
52
+ Requirements:
53
+
54
+ - Include only files that belong to the current task.
55
+ - Do not overwrite, discard, or commit unrelated changes.
56
+ - If ownership of a change is unclear, leave it untouched and report it.
57
+ - Stage files by explicitly listing their paths.
58
+
59
+ Never use:
60
+
61
+ ```bash
62
+ git add .
63
+ git add -A
64
+ ```
65
+
66
+ ## 2. Commit Workflow
67
+
68
+ Follow these steps in order whenever a commit is authorized.
69
+
70
+ ### Step 1: Inspect the Working Tree
71
+
72
+ Run:
73
+
74
+ ```bash
75
+ git -C <repo> status --short
76
+ git -C <repo> branch -vv
77
+ ```
78
+
79
+ Identify:
80
+
81
+ - The current branch and its upstream branch.
82
+ - Tracked, staged, and unstaged changes.
83
+ - Untracked files.
84
+ - Changes belonging to other tasks.
85
+
86
+ Do not discard or overwrite existing local work.
87
+
88
+ ### Step 2: Preserve Local Changes When Needed, Then Pull
89
+
90
+ If local changes would prevent or interfere with synchronization, preserve them before pulling. Use a named stash when appropriate:
91
+
92
+ ```bash
93
+ git -C <repo> stash push -u -m "<project>-<topic>-<MMDD>"
94
+ ```
95
+
96
+ Include untracked files when they are part of the local work that must be preserved. Do not use options that include ignored files unless those files specifically need protection.
97
+
98
+ Then synchronize the current branch:
99
+
100
+ ```bash
101
+ git -C <repo> pull --rebase
102
+ ```
103
+
104
+ Requirements:
105
+
106
+ - Confirm that the command completed successfully. `Already up to date` is a successful result.
107
+ - `fetch` alone does not replace `pull --rebase`.
108
+ - Resolve rebase conflicts before continuing. Do not create a merge commit merely to complete synchronization.
109
+ - If the branch has no valid upstream, the remote is unavailable, or Pull otherwise fails, stop and resolve the issue before committing.
110
+
111
+ If a stash was created:
112
+
113
+ 1. Identify the exact stash created for this operation; do not assume it is `stash@{0}` without checking.
114
+ 2. Restore it with `git stash apply <stash-ref>`.
115
+ 3. Resolve any conflicts and verify that the changes have been restored correctly.
116
+ 4. Drop only that stash after successful verification:
117
+
118
+ ```bash
119
+ git -C <repo> stash drop <stash-ref>
120
+ ```
121
+
122
+ If restoration fails or is incomplete, keep the stash and resolve the problem. Never drop a stash merely to make the stash list look clean.
123
+
124
+ ### Step 3: Check Line Endings and Whitespace
125
+
126
+ Inspect the line-ending information for changed tracked files:
127
+
128
+ ```bash
129
+ git -C <repo> ls-files --eol -- <paths>
130
+ ```
131
+
132
+ Check the repository's `.gitattributes` and `.editorconfig`, when present, to determine the expected line-ending convention. New files must follow the repository's convention.
133
+
134
+ Requirements:
135
+
136
+ - Check that the index and working-tree line endings are consistent with the repository policy.
137
+ - Investigate unexpected `i/` and `w/` differences reported by `git ls-files --eol`.
138
+ - Normalize only files that actually violate the repository's convention.
139
+ - Do not perform broad or automatic line-ending conversions without checking their impact.
140
+
141
+ Also run:
142
+
143
+ ```bash
144
+ git -C <repo> diff --check
145
+ git -C <repo> diff --cached --check
146
+ ```
147
+
148
+ Resolve unintended whitespace errors before proceeding.
149
+
150
+ ### Step 4: Check Change Scope
151
+
152
+ Run:
153
+
154
+ ```bash
155
+ git -C <repo> diff --stat
156
+ git -C <repo> diff
157
+ ```
158
+
159
+ Verify that:
160
+
161
+ - Every changed file belongs to the current task.
162
+ - The changes match the user's requirements.
163
+ - No unrelated modifications are included.
164
+ - No temporary or unintended files are present.
165
+
166
+ Changes outside the task scope must remain untouched. List them and ask the user before including them.
167
+
168
+ ### Step 5: Check Generated Files
169
+
170
+ For build artifacts, generated files, and other derived outputs:
171
+
172
+ - Rebuild them from their source files rather than editing generated files manually.
173
+ - Do not modify generated files as a substitute for changing their source.
174
+ - If the source or regeneration process cannot be identified, leave the generated files unchanged.
175
+ - When the generation relationship is unclear, preserve the original files and explain the situation.
176
+
177
+ ### Step 6: Stage and Review the Exact Commit
178
+
179
+ Stage only the files belonging to the current task:
180
+
181
+ ```bash
182
+ git -C <repo> add <file1> <file2>
183
+ ```
184
+
185
+ Review the complete staged change:
186
+
187
+ ```bash
188
+ git -C <repo> diff --cached --stat
189
+ git -C <repo> diff --cached
190
+ ```
191
+
192
+ Confirm that:
193
+
194
+ - Every staged file belongs to the current task.
195
+ - The staged content matches the requested changes.
196
+ - No unrelated file or temporary artifact is included.
197
+ - No intended change has been omitted.
198
+
199
+ If staging changes the working-tree/index situation or more edits are made, repeat the relevant checks before committing.
200
+
201
+ ### Step 7: Commit When the Task Is Ready
202
+
203
+ Commit only after the task is ready for acceptance and all preceding checks are complete. Follow the commit-message rules in §3.
204
+
205
+ ## 3. Commit Message
206
+
207
+ ### 3.1 Title Format
208
+
209
+ Use this format:
210
+
211
+ ```text
212
+ <type>: <summary>
213
+ ```
214
+
215
+ The `type` must come from this closed list and remain in Chinese, consistent with the existing commit history in these repositories:
216
+
217
+ | Type | Usage |
218
+ |---|---|
219
+ | 记账 | Bookkeeping changes |
220
+ | 台账 | Tracking and registry changes |
221
+ | 规范 | Rules and conventions |
222
+ | 工具 | Tools and automation |
223
+ | 结构 | Project structure changes |
224
+ | 修复 | Bug fixes |
225
+ | 文档 | Documentation changes |
226
+
227
+ Requirements:
228
+
229
+ - Use one of the specified Chinese types.
230
+ - Keep the entire title within 50 characters.
231
+ - Do not add a trailing period.
232
+ - Do not invent new types.
233
+ - Make the summary accurately describe the primary result of the task.
234
+
235
+ ### 3.2 Commit Body
236
+
237
+ Use one sentence per line. Each line should describe one change and the problem it addresses.
238
+
239
+ Use separate `-m` flags rather than combining everything into one paragraph. For example:
240
+
241
+ ```bash
242
+ git -C <repo> commit \
243
+ -m "规范: 调整 Git 提交流程" \
244
+ -m "统一提交前检查的执行顺序" \
245
+ -m "明确远程同步和变更范围检查要求"
246
+ ```
247
+
248
+ Requirements:
249
+
250
+ - Describe one change per line.
251
+ - Explain what changed and what issue it resolved.
252
+ - Do not include irrelevant implementation details.
253
+ - Avoid unverifiable claims such as "significantly improved performance."
254
+
255
+ Write commit messages for people who will read the Git history later. Focus on the outcome, not the development process.
256
+
257
+ ## 4. Commit Timing and Granularity
258
+
259
+ ### 4.1 One Commit per Task
260
+
261
+ Under normal circumstances, create one commit for each completed task.
262
+
263
+ - Commit when the task is ready for acceptance and verification.
264
+ - Do not split one task into unnecessary commits simply because multiple files changed.
265
+ - Do not combine unrelated tasks into a single commit.
266
+
267
+ ### 4.2 Do Not Commit Too Early
268
+
269
+ Do not commit when:
270
+
271
+ - Requirements are still undecided.
272
+ - The technical approach is still being discussed or adjusted.
273
+ - The user is still confirming the implementation direction.
274
+ - The changes are not yet ready for acceptance.
275
+
276
+ ### 4.3 Temporary Files
277
+
278
+ Keep the following out of formal commits:
279
+
280
+ - Intermediate artifacts.
281
+ - Incomplete drafts.
282
+ - Temporary test scripts.
283
+ - One-off helper files.
284
+ - Anything under `.tmp/`.
285
+
286
+ ### 4.4 Interim Commits for Cross-Session Handover
287
+
288
+ An interim commit may be necessary for a cross-session handover, but it is an exception to the normal one-commit-per-completed-task rule.
289
+
290
+ - Use an interim commit only when genuinely necessary and authorized in the current task.
291
+ - Follow the same Pull and pre-commit checks as any other commit.
292
+ - Record the following on the corresponding task-board entry:
293
+
294
+ ```text
295
+ unfinished, committed <short sha>
296
+ ```
297
+
298
+ - Record this at most once per task.
299
+ - Do not present an interim commit as a completed task.
300
+
301
+ ## 5. Stash Management
302
+
303
+ ### 5.1 Naming Convention
304
+
305
+ Give every stash a descriptive name using this format:
306
+
307
+ ```text
308
+ <project>-<topic>-<MMDD>
309
+ ```
310
+
311
+ Examples:
312
+
313
+ ```text
314
+ cine-flow-prompt-1120
315
+ cine-flow-video-1120
316
+ ```
317
+
318
+ Do not create anonymous stashes.
319
+
320
+ ### 5.2 Stash Lifecycle
321
+
322
+ - Every stash must have a clearly identified purpose.
323
+ - Restore and remove a task-created stash as soon as its contents have been safely restored and verified.
324
+ - Do not use stashes as long-term storage for work.
325
+ - Do not delete pre-existing stashes or stashes whose contents have not been verified.
326
+ - If a stash must remain beyond the current day, document why it is being retained. Data preservation takes priority over routine cleanup.
327
+
328
+ ### 5.3 Autostash
329
+
330
+ If `pull --rebase --autostash` is used:
331
+
332
+ - Verify that the Pull/Rebase operation completed successfully.
333
+ - Verify that the local changes were restored.
334
+ - Resolve any restoration conflicts.
335
+ - Confirm that no temporary autostash remains unresolved.
336
+
337
+ Do not assume that successful Pull/Rebase means the automatic restoration also succeeded.
338
+
339
+ ### 5.4 Stash Close-Out
340
+
341
+ Run:
342
+
343
+ ```bash
344
+ git -C <repo> stash list
345
+ ```
346
+
347
+ Confirm that no task-created stash remains unintentionally. Preserve any pre-existing or unresolved stash until its ownership and contents are clear.
348
+
349
+ ## 6. Protect Remote History
350
+
351
+ A remote repository contains shared history. Normal pushes must be fast-forward updates. Do not rewrite published history or remove shared references during routine work.
352
+
353
+ ### 6.1 Prohibited in Normal Work
354
+
355
+ The following operations are prohibited during normal work:
356
+
357
+ #### Force Push
358
+
359
+ ```bash
360
+ git push --force
361
+ git push -f
362
+ git push --force-with-lease
363
+ git push --force-if-includes
364
+ ```
365
+
366
+ Do not treat `--force-with-lease` as a safe exception.
367
+
368
+ #### Mirror, Prune, and Forced RefSpecs
369
+
370
+ ```bash
371
+ git push --mirror
372
+ git push --prune
373
+ ```
374
+
375
+ Any refspec beginning with `+` is also prohibited.
376
+
377
+ #### Deleting Remote Branches or Tags
378
+
379
+ ```bash
380
+ git push <remote> --delete <ref>
381
+ git push <remote> :<ref>
382
+ ```
383
+
384
+ #### Overwriting Published Tags
385
+
386
+ Do not:
387
+
388
+ - Force-push an already published tag.
389
+ - Delete and recreate a tag using the same name.
390
+ - Move an existing published tag to another commit.
391
+ - Overwrite a published tag through another method.
392
+
393
+ #### Rewriting Published History
394
+
395
+ Do not rewrite commits that already exist on a remote repository and then push the rewritten history. This includes using `git commit --amend`, `git rebase`, `git reset --hard`, or `git filter-branch` on commits that have already been published.
396
+
397
+ #### Bypassing Remote Protection Hooks
398
+
399
+ ```bash
400
+ git push --no-verify
401
+ ```
402
+
403
+ Do not bypass Git hooks that protect the remote repository.
404
+
405
+ ### 6.2 Safe Alternatives
406
+
407
+ When remote history needs to be corrected, use these approaches in order:
408
+
409
+ **Option 1: Revert**
410
+
411
+ ```bash
412
+ git revert <sha>
413
+ git push
414
+ ```
415
+
416
+ Prefer creating a new reversing commit that preserves existing history.
417
+
418
+ **Option 2: Publish on a New Branch**
419
+
420
+ - Make the required changes locally.
421
+ - Create a new branch.
422
+ - Push the new branch with a normal push.
423
+ - Submit it for review or merge.
424
+ - Leave the original remote branch unchanged.
425
+
426
+ **Option 3: Remote History Rewriting Is Truly Necessary**
15
427
 
16
- ## 1. Authorisation
428
+ Stop and request explicit authorization from the user before proceeding. Explain:
17
429
 
18
- Commit only what the user asked for in this turn. No request, no commit, and no push.
430
+ 1. The exact remote branch involved.
431
+ 2. The complete command to be executed.
432
+ 3. What content may be lost or overwritten.
433
+ 4. Which other collaborators may be affected.
19
434
 
20
- Stage nothing that belongs to another task: read `git status --short` and pick the paths by hand (**never `git add -A`**). Run every command as `git -C <repo>` instead of trusting the current directory.
435
+ Only explicit approval from the user in the current task can authorize an exceptional history-rewriting operation. Authorization applies to one specified branch, one exact command, and one execution. Silence, previous approval, or automated prompts do not constitute authorization.
21
436
 
22
- ## 2. Four checks before committing
437
+ This exceptional approval path does not automatically authorize deleting remote branches or tags, or replacing published tags.
23
438
 
24
- 1. **Pull.** `git -C <repo> pull --rebase`. Fix conflicts on the spot; never manufacture a merge commit.
25
- 2. **Line endings.** `git diff --shortstat` and `git diff -w --shortstat` must report the same counts. When they differ, normalise to the line endings `HEAD` uses before committing.
26
- 3. **Scope.** `git diff --stat` must match the task. Anything beyond it gets listed and asked about, never carried along.
27
- 4. **Generated files.** Rebuild them from source, never by hand; with no source to rebuild from, leave them alone.
439
+ ### 6.3 Handling a Rejected Push
28
440
 
29
- ## 3. Commit message
441
+ If an authorized normal push is rejected:
30
442
 
31
- Title: `<type>: <summary>`. The type comes from a closed list and stays Chinese, the way every existing commit in these repositories is written: `记账` (bookkeeping), `台账` (board), `规范` (rules), `工具` (tools), `结构` (structure), `修复` (fix), `文档` (docs). At most 50 characters, no trailing period.
443
+ 1. Do not force-push or bypass remote protection.
444
+ 2. Determine why the push was rejected.
445
+ 3. If it is a non-fast-forward rejection, inspect the working tree and preserve any local changes before synchronizing.
446
+ 4. Run `git pull --rebase` and resolve any conflicts.
447
+ 5. Review the resulting history and changes; rerun relevant checks or tests if conflict resolution changed the result.
448
+ 6. Retry a normal push.
32
449
 
33
- Body: one sentence per line, each saying what changed and what it fixed. Split across several `-m` flags rather than cramming one paragraph.
450
+ If the rejection is caused by authentication, network problems, branch protection, or a server-side hook, stop and report the cause. Do not repeatedly retry or attempt to bypass the restriction.
34
451
 
35
- Write for whoever reads the log later. Skip the code narrative, and skip claims nobody can check ("improved performance").
452
+ ### 6.4 Local-Only History Rewriting
36
453
 
37
- ## 4. One commit per task
454
+ Local history rewriting is permitted for commits that have never been pushed to a remote repository. This includes:
38
455
 
39
- Commit once the task's acceptance can be checked. Not while the requirement is 未定 (undecided), not while the approach is, not while the user is still confirming.
456
+ - `rebase`
457
+ - `commit --amend`
458
+ - `reset --hard`
40
459
 
41
- Interim artefacts, drafts, throwaway scripts and anything under `.tmp/` stay out of the repository.
460
+ Before rewriting, verify that the target commits have not been published. Check the configured upstream and inspect:
42
461
 
43
- A cross-session handover sometimes forces an interim commit. Note "unfinished, committed <short sha>" on the task board row, once per task at most.
462
+ ```bash
463
+ git -C <repo> log @{u}..HEAD
464
+ git -C <repo> branch -r --contains <sha>
465
+ ```
44
466
 
45
- ## 5. Stashes
467
+ Do not assume a commit is unpublished without checking. If the upstream is missing or the result is ambiguous, stop and verify the remote state before rewriting history.
46
468
 
47
- Name every stash `<project>-<topic>-<MMDD>` and never let one survive the day.
469
+ ### 6.5 Protect Local Work from Destructive Commands
48
470
 
49
- After `pull --autostash` succeeds, restore at once, resolve any conflict on the spot, then drop. No anonymous stash is left behind.
471
+ Commands such as the following can discard local data:
50
472
 
51
- At close-out, `git stash list` shows nothing anonymous and nothing from an earlier day.
473
+ ```bash
474
+ git reset --hard
475
+ git clean -fd
476
+ git checkout -- <path>
477
+ git restore <path>
478
+ ```
52
479
 
53
- ## 6. Never force a remote
480
+ Before using any command that discards or overwrites working-tree content:
54
481
 
55
- The remote is shared history. Push fast-forwards only; anything that rewrites what others may already have fetched is banned outright, not merely discouraged.
482
+ - Inspect `git status --short`, `git diff`, and `git diff --cached`.
483
+ - Identify untracked files that may be affected.
484
+ - Preserve any user changes that must remain.
485
+ - Use a dry run, such as `git clean -nd`, before any cleanup that deletes untracked files.
486
+ - Do not use destructive commands as a routine way to resolve conflicts.
56
487
 
57
- **Forbidden without exception in normal work:**
488
+ If the affected content or ownership is unclear, do not run the command. Preserve the data and ask the user how to proceed.
58
489
 
59
- - `git push --force`, `-f`, `--force-with-lease`, `--force-if-includes` — no variant is "the safe one" here.
60
- - `git push --mirror`, `git push --prune` and any refspec with a leading `+`.
61
- - Deleting a remote branch or tag: `git push <remote> --delete <ref>`, `git push <remote> :<ref>`.
62
- - Moving or overwriting a published tag: `git push --force <remote> <tag>`, delete-then-repush, or re-tagging the same name.
63
- - Rewriting published history and pushing it: after `git commit --amend`, `git rebase`, `git reset --hard` or `git filter-branch` on commits already on the remote.
64
- - `git push --no-verify` to bypass a hook that guards the remote.
490
+ ## Close-Out Self-Check
65
491
 
66
- **What to do instead**, in this order:
492
+ After the commit, verify:
67
493
 
68
- 1. Undo forward: `git revert <sha>`, then a normal push.
69
- 2. Rewrite locally, publish on a new branch, open it for review; the old branch stays untouched.
70
- 3. If a force is genuinely the only way, stop and ask the user: name the branch, the exact command, what will be lost, and who else fetches from it. Only their explicit go-ahead in this turn authorises it — one branch, one command, one time. Silence, a previous approval, or an automated prompt is not consent.
494
+ - [ ] The user's current-task authorization for the commit is clear.
495
+ - [ ] The current branch was synchronized with `git pull --rebase` before committing.
496
+ - [ ] Local changes were preserved and restored correctly, if a stash was needed.
497
+ - [ ] Line endings and whitespace were checked.
498
+ - [ ] The staged content contains only changes belonging to the current task.
499
+ - [ ] Generated files were handled according to their source-generation process.
500
+ - [ ] `git log --merges` shows no new merge commit created by this operation.
501
+ - [ ] No in-scope changes remain uncommitted.
502
+ - [ ] Any out-of-scope changes remain untouched and are reported.
503
+ - [ ] The commit title uses an approved type, is no longer than 50 characters, and has no trailing period.
504
+ - [ ] The commit body accurately describes the changes and the problems they address.
505
+ - [ ] No task-created stash remains unintentionally; unresolved or pre-existing stashes have been preserved.
506
+ - [ ] No prohibited remote history rewrite, forced ref update, remote ref deletion, or published tag overwrite was performed.
507
+ - [ ] Push was performed only when explicitly authorized, and every push was a normal fast-forward update.
71
508
 
72
- Local-only rewriting (`rebase`, `amend`, `reset --hard` on commits never pushed) is unaffected — but confirm with `git log @{u}..HEAD` / `git branch -r --contains` before assuming a commit is unpublished.
509
+ ## Final Principles
73
510
 
74
- ## Close-out self-check
511
+ User authorization determines whether to commit or push. The task scope determines what to include. Remote synchronization and pre-commit checks determine whether the changes are ready. Commit-message conventions determine how the work is recorded. Remote-history and local-data protection rules prevent damage to shared history and user work.
75
512
 
76
- - [ ] The commit's authorisation can be quoted from the user's own words
77
- - [ ] `git log --merges` shows no new merge
78
- - [ ] `git status --short` is clean, with no in-scope file left uncommitted
79
- - [ ] The title carries a type, stays within 50 characters, and ends without a period
80
- - [ ] No `--force`, `--mirror`, `--prune`, ref deletion or re-tag went to a remote; every push was a fast-forward
513
+ When a check fails or the repository state is unclear, preserve the existing data, resolve the issue, and then continue. Never bypass a check merely to complete the workflow.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: plan-revision
3
- description: How to revise a plan: give the whole plan every time, lead with what changed, and hand over only the revised result. Load it when the user comments on a plan, asks for a new design, or asks you to re-read the requirements.
3
+ description: "How to revise a plan: give the whole plan every time, lead with what changed, and hand over only the revised result. Load it when the user comments on a plan, asks for a new design, or asks you to re-read the requirements."
4
4
  whenToUse: The user pushes back on a plan, asks for a new version, or says 「再读一遍要求」 (re-read my requirements).
5
5
  ---
6
6
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: task-setup
3
- description: Task setup: turn one vague request into an acceptance-checkable task card, decide whether it goes on the board, and route it to the workflow that owns the work. Read before taking on a new assignment.
3
+ description: "Task setup: turn one vague request into an acceptance-checkable task card, decide whether it goes on the board, and route it to the workflow that owns the work. Read before taking on a new assignment."
4
4
  whenToUse: A new task arrives, the request is vague, or the work is expected to take more than 3 steps or cross sessions. Also load when unsure whether a request belongs in feature-dev or in the light path.
5
5
  ---
6
6