From 8af2616ffadbe2794e1ef517ff021fd9cab50065 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Wed, 2 Sep 2026 11:30:49 +0800 Subject: [PATCH 1/2] feat(aidd-vcs): recover from scoped commit hook failures --- docs/CATALOG.md | 14 +++---- plugins/aidd-vcs/CATALOG.md | 2 +- plugins/aidd-vcs/README.md | 2 +- plugins/aidd-vcs/skills/01-commit/SKILL.md | 21 +++++----- .../skills/01-commit/actions/01-collect.md | 15 ++++--- .../skills/01-commit/actions/03-commit.md | 41 +++++++++++++++---- 6 files changed, 64 insertions(+), 31 deletions(-) diff --git a/docs/CATALOG.md b/docs/CATALOG.md index d08bf4696..e6554d378 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -82,13 +82,13 @@ Meta-cognition: brainstorm, challenge, blind-spot scan, fact-check. Version-control workflows: repo init, commit, pull/merge request, release tag, issue. -| Skill | Role | Actions | -| ----------------- | ------------------------------------------------------------------------------- | ----------------------- | -| `00-repo-init` | Initialize a repo: git init, default branch, bootstrap commit, optional remote | `01-init`, `02-publish` | -| `01-commit` | Create an atomic conventional commit | `01-commit` | -| `02-pull-request` | Create a draft pull or merge request | `01-pull-request` | -| `03-release-tag` | Cut a semver release with annotated tag and notes | `01-release-tag` | -| `04-issue-create` | Create an issue in the configured ticketing tool | `01-issue-create` | +| Skill | Role | Actions | +| ----------------- | ------------------------------------------------------------------------------ | --------------------------------------- | +| `00-repo-init` | Initialize a repo: git init, default branch, bootstrap commit, optional remote | `01-init`, `02-publish` | +| `01-commit` | Create atomic conventional commits and safely repair scoped hook failures | `01-collect`, `02-message`, `03-commit` | +| `02-pull-request` | Create a draft pull or merge request | `01-pull-request` | +| `03-release-tag` | Cut a semver release with annotated tag and notes | `01-release-tag` | +| `04-issue-create` | Create an issue in the configured ticketing tool | `01-issue-create` | ## 🎼 aidd-orchestrator diff --git a/plugins/aidd-vcs/CATALOG.md b/plugins/aidd-vcs/CATALOG.md index fed85e299..96fe0251e 100644 --- a/plugins/aidd-vcs/CATALOG.md +++ b/plugins/aidd-vcs/CATALOG.md @@ -41,7 +41,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-message.md](skills/01-commit/actions/02-message.md) | - | | `actions` | [03-commit.md](skills/01-commit/actions/03-commit.md) | - | | `assets` | [commit-template.md](skills/01-commit/assets/commit-template.md) | `VCS commit message template` | -| `-` | [SKILL.md](skills/01-commit/SKILL.md) | `Create an atomic git commit with a conventional message, optionally pushing. Use when the user wants to commit changes, optionally pushing the branch. Not for amending, rebasing, opening a pull request, or tagging a release.` | +| `-` | [SKILL.md](skills/01-commit/SKILL.md) | `Create atomic conventional commits, safely repair scoped hook failures, and optionally push. Use when the user wants to commit changes, optionally pushing the branch. Not for amending, rebasing, opening a pull request, or tagging a release.` | #### `skills/02-pull-request` diff --git a/plugins/aidd-vcs/README.md b/plugins/aidd-vcs/README.md index 75e4898df..cac53a1f8 100644 --- a/plugins/aidd-vcs/README.md +++ b/plugins/aidd-vcs/README.md @@ -17,7 +17,7 @@ Covers all external artifact creation: repo init, commits, pull/merge requests, | Bracket ID | Skill | Description | |---|---|---| | [3.0] | [repo-init](skills/00-repo-init/SKILL.md) | Initialize a repo: git init, default branch, bootstrap commit, CONTRIBUTING.md, optional remote. | -| [3.1] | [commit](skills/01-commit/SKILL.md) | Create a git commit with proper conventional message format. | +| [3.1] | [commit](skills/01-commit/SKILL.md) | Create atomic conventional commits, safely repair scoped hook failures, and optionally push. | | [3.2] | [pull-request](skills/02-pull-request/SKILL.md) | Create PR (GitHub) or MR (GitLab) with filled template. | | [3.3] | [release-tag](skills/03-release-tag/SKILL.md) | Create and push a semantic version git tag with release notes. | | [3.4] | [issue-create](skills/04-issue-create/SKILL.md) | Create issues in the configured ticketing tool. | diff --git a/plugins/aidd-vcs/skills/01-commit/SKILL.md b/plugins/aidd-vcs/skills/01-commit/SKILL.md index ea1286d44..fe5c9e730 100644 --- a/plugins/aidd-vcs/skills/01-commit/SKILL.md +++ b/plugins/aidd-vcs/skills/01-commit/SKILL.md @@ -1,22 +1,22 @@ --- name: 01-commit -description: Create an atomic git commit with a conventional message, optionally pushing. Use when the user wants to commit changes, optionally pushing the branch. Not for amending, rebasing, opening a pull request, or tagging a release. +description: Create atomic conventional commits, safely repair scoped hook failures, and optionally push. Use when the user wants to commit changes, optionally pushing the branch. Not for amending, rebasing, opening a pull request, or tagging a release. argument-hint: paths | auto | push --- # Commit -Stage the right changes, write the message, commit. `01 → 02 → 03`. +Stage the right changes, write the message, commit, and report what happened. `01 → 02 → 03`. ## Actions -| # | Action | Step | -| --- | --------- | ----------------------------------------------------- | -| 01 | `collect` | Review the change and stage what belongs in one commit | -| 02 | `message` | Write the conventional message | -| 03 | `commit` | Commit, and push when asked | +| # | Action | Step | +| --- | --------- | ------------------------------------------------------------------ | +| 01 | `collect` | Review the change and stage what belongs in one commit | +| 02 | `message` | Write the conventional message | +| 03 | `commit` | Commit, recover from scoped failures, report, and push when asked | -Several concerns means several commits: repeat the chain, one concern at a time. +Several concerns means several commits: repeat the chain, one concern at a time, then emit one combined report. Before running an action, read its file in `actions/`, not only the table or assets. ## Transversal rules @@ -25,8 +25,9 @@ Before running an action, read its file in `actions/`, not only the table or ass - One concern per commit. Imperative mood. The body says why, not what. - Reference the issue in the body when there is one. - Never `--force` push; `--force-with-lease` only when explicitly asked. -- A hook that rejects the commit is not this skill's job: report which hook and why, then stop. Re-stage only files a hook auto-formatted. -- `auto` never prompts. `interactive` confirms before staging and before each split. +- Keep a run ledger of correction cycles and created commits. Emit it after the last concern, not after every commit. +- Repair a rejecting hook only when the correction is deterministic and bounded to the current commit's files. Never broaden the change to make a check pass. +- `auto` never prompts and stops on scope ambiguity. `interactive` asks when the scope is ambiguous and confirms before staging and before each split. - Commits locally by default; pushes as well only when the push option is set. ## Assets diff --git a/plugins/aidd-vcs/skills/01-commit/actions/01-collect.md b/plugins/aidd-vcs/skills/01-commit/actions/01-collect.md index ed6c1d34f..97d1cbb36 100644 --- a/plugins/aidd-vcs/skills/01-commit/actions/01-collect.md +++ b/plugins/aidd-vcs/skills/01-commit/actions/01-collect.md @@ -4,19 +4,24 @@ Review the working change and stage what belongs in one atomic commit. ## Input -Optional paths to restrict the commit, and the mode (`interactive` default, or `auto`). +Optional paths to restrict the commit, the changes made during the current conversation, and the mode (`interactive` default, or `auto`). ## Output -The staged set for one commit, and the concern it covers. +An ordered commit plan and the staged set for its first concern. ## Process -1. **Read.** Look at the diff and group it by concern. -2. **Pick.** Stage the files for one concern. With explicit paths, stage exactly those; otherwise keep what is already staged, never adding unstaged files on your own. -3. **Split.** When several concerns are mixed, stage one at a time with `git add -p`. In `interactive`, propose each split (its scope and why) and wait for approval. +1. **Resolve.** Determine the authorized change set in this order: explicit paths, already staged changes, then changes made during the current conversation. + - Never add other unstaged changes merely because they are present. + - When conversation ownership or the requested scope is ambiguous, ask in `interactive`; stop with the ambiguity in `auto`. +2. **Group.** Review the authorized diff and build an ordered plan with one concern per commit. +3. **Pick.** Stage the first concern only. Keep an existing atomic staged set as-is; otherwise stage exact paths or use `git add -p` when a file contains several concerns. +4. **Confirm.** In `interactive`, show each proposed split with its scope and reason, then wait for approval. In `auto`, proceed only when every split is unambiguous. ## Test - The staged set covers one concern, nothing unrelated. - Files the user did not name or stage are left untouched. +- Ambiguity is surfaced, never resolved by silently staging more files. +- When all authorized changes are requested, distinct concerns remain distinct commits. diff --git a/plugins/aidd-vcs/skills/01-commit/actions/03-commit.md b/plugins/aidd-vcs/skills/01-commit/actions/03-commit.md index 49d2a7aa0..9361a12d7 100644 --- a/plugins/aidd-vcs/skills/01-commit/actions/03-commit.md +++ b/plugins/aidd-vcs/skills/01-commit/actions/03-commit.md @@ -1,23 +1,50 @@ # 03 - Commit -Record the commit, and push when asked. +Record each atomic commit, recover from safe scoped failures, then report and optionally push the run. ## Input -The staged set from `01-collect`, the message from `02-message`, and whether to push (a trailing `push` argument). +The commit plan and staged set from `01-collect`, the message from `02-message`, the run ledger, and whether to push (a trailing `push` argument). ## Output -The commit sha, the branch, and whether it was pushed. +The branch, push outcome, correction summary, and one final row per created commit. ## Process 1. **Commit.** Run `git commit` with the message. -2. **Hook.** If a pre-commit hook rejects it, report which hook and why, then stop; fixing it is the caller's job. Re-stage and retry once only when the hook merely auto-formatted files. -3. **Push.** When asked, push the branch. Use `--force-with-lease` only when explicitly required, never `--force`. +2. **Classify.** When a hook rejects the commit, identify the failing check, its decisive error, and every file changed by the hook. +3. **Recover.** Correct and retry only when the fix is deterministic and can be restricted to the current commit's files. + - Re-stage only in-scope files changed by the hook or the correction. + - A message-policy failure loops through `02-message`; a path-bounded format or lint failure may use its specific fixer. + - Never run a repository-wide fixer, alter unrelated changes, or guess at a semantic, product, security, or architecture decision. + - Append the cycle's problem, correction, and result to the run ledger. + - Stop when the same failure repeats without meaningful progress, the correction needs broader authority, or the retry after the third correction still fails. +4. **Record.** After success, read the commit timestamp, short sha, subject, and committed file count from the created commit itself, then append them to the run ledger. Render the timestamp in the user's local timezone when known; otherwise preserve git's recorded offset. +5. **Repeat.** Return to `01-collect` for the next planned concern, preserving the ledger. +6. **Push.** After the last concern, push once when asked. Use `--force-with-lease` only when explicitly required, never `--force`. +7. **Report.** Emit the correction summary followed by the commit table. Do not add a validation column. + +If no correction was needed: + +> No correction needed. + +If corrections were made: + +| Cycle | Problem detected | Correction applied | Result | +| ---: | --- | --- | --- | +| 1 | `` | `` | `` | + +Always finish with: + +| Date and time | Commit | Message | Files | +| --- | --- | --- | ---: | +| `` | `` | `` | `` | ## Test - `git rev-parse HEAD` returns the new sha and its message matches the project convention. -- A rejecting hook leaves no commit and a clear report, not a retry loop. -- When pushed, the remote branch shows the sha. +- Every correction and re-staged file belongs to the current commit's authorized scope. +- A repeated, ambiguous, semantic, out-of-scope failure, or a failure after the third correction leaves no commit for that concern and reports the blocker. +- The correction summary contains exactly the cycles that changed something; the final table contains exactly the commits created by this run. +- When pushed, the remote branch shows the final sha. From 70583903e6771a72ea00e26ba49510b30fb0a62c Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Thu, 3 Sep 2026 13:37:35 +0800 Subject: [PATCH 2/2] refactor(aidd-vcs): simplify scoped hook recovery --- docs/CATALOG.md | 2 +- plugins/aidd-vcs/CATALOG.md | 2 +- plugins/aidd-vcs/README.md | 2 +- plugins/aidd-vcs/skills/01-commit/SKILL.md | 21 +++++----- .../skills/01-commit/actions/01-collect.md | 15 +++---- .../skills/01-commit/actions/03-commit.md | 41 ++++--------------- 6 files changed, 26 insertions(+), 57 deletions(-) diff --git a/docs/CATALOG.md b/docs/CATALOG.md index e6554d378..33d6cf502 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -85,7 +85,7 @@ Version-control workflows: repo init, commit, pull/merge request, release tag, i | Skill | Role | Actions | | ----------------- | ------------------------------------------------------------------------------ | --------------------------------------- | | `00-repo-init` | Initialize a repo: git init, default branch, bootstrap commit, optional remote | `01-init`, `02-publish` | -| `01-commit` | Create atomic conventional commits and safely repair scoped hook failures | `01-collect`, `02-message`, `03-commit` | +| `01-commit` | Commit atomically; safely retry scoped hook fixes | `01-collect`, `02-message`, `03-commit` | | `02-pull-request` | Create a draft pull or merge request | `01-pull-request` | | `03-release-tag` | Cut a semver release with annotated tag and notes | `01-release-tag` | | `04-issue-create` | Create an issue in the configured ticketing tool | `01-issue-create` | diff --git a/plugins/aidd-vcs/CATALOG.md b/plugins/aidd-vcs/CATALOG.md index 96fe0251e..93dd51901 100644 --- a/plugins/aidd-vcs/CATALOG.md +++ b/plugins/aidd-vcs/CATALOG.md @@ -41,7 +41,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-message.md](skills/01-commit/actions/02-message.md) | - | | `actions` | [03-commit.md](skills/01-commit/actions/03-commit.md) | - | | `assets` | [commit-template.md](skills/01-commit/assets/commit-template.md) | `VCS commit message template` | -| `-` | [SKILL.md](skills/01-commit/SKILL.md) | `Create atomic conventional commits, safely repair scoped hook failures, and optionally push. Use when the user wants to commit changes, optionally pushing the branch. Not for amending, rebasing, opening a pull request, or tagging a release.` | +| `-` | [SKILL.md](skills/01-commit/SKILL.md) | `Create atomic conventional commits; safely retry scoped hook fixes; optionally push. Use when the user wants to commit changes, optionally pushing the branch. Not for amending, rebasing, opening a pull request, or tagging a release.` | #### `skills/02-pull-request` diff --git a/plugins/aidd-vcs/README.md b/plugins/aidd-vcs/README.md index cac53a1f8..55566ca53 100644 --- a/plugins/aidd-vcs/README.md +++ b/plugins/aidd-vcs/README.md @@ -17,7 +17,7 @@ Covers all external artifact creation: repo init, commits, pull/merge requests, | Bracket ID | Skill | Description | |---|---|---| | [3.0] | [repo-init](skills/00-repo-init/SKILL.md) | Initialize a repo: git init, default branch, bootstrap commit, CONTRIBUTING.md, optional remote. | -| [3.1] | [commit](skills/01-commit/SKILL.md) | Create atomic conventional commits, safely repair scoped hook failures, and optionally push. | +| [3.1] | [commit](skills/01-commit/SKILL.md) | Commit atomically; safely retry scoped hook fixes. | | [3.2] | [pull-request](skills/02-pull-request/SKILL.md) | Create PR (GitHub) or MR (GitLab) with filled template. | | [3.3] | [release-tag](skills/03-release-tag/SKILL.md) | Create and push a semantic version git tag with release notes. | | [3.4] | [issue-create](skills/04-issue-create/SKILL.md) | Create issues in the configured ticketing tool. | diff --git a/plugins/aidd-vcs/skills/01-commit/SKILL.md b/plugins/aidd-vcs/skills/01-commit/SKILL.md index fe5c9e730..98ecd3533 100644 --- a/plugins/aidd-vcs/skills/01-commit/SKILL.md +++ b/plugins/aidd-vcs/skills/01-commit/SKILL.md @@ -1,22 +1,22 @@ --- name: 01-commit -description: Create atomic conventional commits, safely repair scoped hook failures, and optionally push. Use when the user wants to commit changes, optionally pushing the branch. Not for amending, rebasing, opening a pull request, or tagging a release. +description: Create atomic conventional commits; safely retry scoped hook fixes; optionally push. Use when the user wants to commit changes, optionally pushing the branch. Not for amending, rebasing, opening a pull request, or tagging a release. argument-hint: paths | auto | push --- # Commit -Stage the right changes, write the message, commit, and report what happened. `01 → 02 → 03`. +Stage, message, commit. `01 → 02 → 03`. ## Actions -| # | Action | Step | -| --- | --------- | ------------------------------------------------------------------ | -| 01 | `collect` | Review the change and stage what belongs in one commit | -| 02 | `message` | Write the conventional message | -| 03 | `commit` | Commit, recover from scoped failures, report, and push when asked | +| # | Action | Step | +| --- | --------- | ---------------------------------------------- | +| 01 | `collect` | Stage one concern | +| 02 | `message` | Write the conventional message | +| 03 | `commit` | Commit, safely retry scoped fixes, push if asked | -Several concerns means several commits: repeat the chain, one concern at a time, then emit one combined report. +Several concerns means several commits: repeat the chain, one concern at a time. Before running an action, read its file in `actions/`, not only the table or assets. ## Transversal rules @@ -25,9 +25,8 @@ Before running an action, read its file in `actions/`, not only the table or ass - One concern per commit. Imperative mood. The body says why, not what. - Reference the issue in the body when there is one. - Never `--force` push; `--force-with-lease` only when explicitly asked. -- Keep a run ledger of correction cycles and created commits. Emit it after the last concern, not after every commit. -- Repair a rejecting hook only when the correction is deterministic and bounded to the current commit's files. Never broaden the change to make a check pass. -- `auto` never prompts and stops on scope ambiguity. `interactive` asks when the scope is ambiguous and confirms before staging and before each split. +- Retry a rejected hook only for deterministic changes within the current commit's files. Never broaden the change to make a check pass. +- `auto` never prompts. `interactive` confirms before staging and before each split. - Commits locally by default; pushes as well only when the push option is set. ## Assets diff --git a/plugins/aidd-vcs/skills/01-commit/actions/01-collect.md b/plugins/aidd-vcs/skills/01-commit/actions/01-collect.md index 97d1cbb36..ed6c1d34f 100644 --- a/plugins/aidd-vcs/skills/01-commit/actions/01-collect.md +++ b/plugins/aidd-vcs/skills/01-commit/actions/01-collect.md @@ -4,24 +4,19 @@ Review the working change and stage what belongs in one atomic commit. ## Input -Optional paths to restrict the commit, the changes made during the current conversation, and the mode (`interactive` default, or `auto`). +Optional paths to restrict the commit, and the mode (`interactive` default, or `auto`). ## Output -An ordered commit plan and the staged set for its first concern. +The staged set for one commit, and the concern it covers. ## Process -1. **Resolve.** Determine the authorized change set in this order: explicit paths, already staged changes, then changes made during the current conversation. - - Never add other unstaged changes merely because they are present. - - When conversation ownership or the requested scope is ambiguous, ask in `interactive`; stop with the ambiguity in `auto`. -2. **Group.** Review the authorized diff and build an ordered plan with one concern per commit. -3. **Pick.** Stage the first concern only. Keep an existing atomic staged set as-is; otherwise stage exact paths or use `git add -p` when a file contains several concerns. -4. **Confirm.** In `interactive`, show each proposed split with its scope and reason, then wait for approval. In `auto`, proceed only when every split is unambiguous. +1. **Read.** Look at the diff and group it by concern. +2. **Pick.** Stage the files for one concern. With explicit paths, stage exactly those; otherwise keep what is already staged, never adding unstaged files on your own. +3. **Split.** When several concerns are mixed, stage one at a time with `git add -p`. In `interactive`, propose each split (its scope and why) and wait for approval. ## Test - The staged set covers one concern, nothing unrelated. - Files the user did not name or stage are left untouched. -- Ambiguity is surfaced, never resolved by silently staging more files. -- When all authorized changes are requested, distinct concerns remain distinct commits. diff --git a/plugins/aidd-vcs/skills/01-commit/actions/03-commit.md b/plugins/aidd-vcs/skills/01-commit/actions/03-commit.md index 9361a12d7..2b7cabce2 100644 --- a/plugins/aidd-vcs/skills/01-commit/actions/03-commit.md +++ b/plugins/aidd-vcs/skills/01-commit/actions/03-commit.md @@ -1,50 +1,25 @@ # 03 - Commit -Record each atomic commit, recover from safe scoped failures, then report and optionally push the run. +Record the commit, safely retry scoped hook fixes, and push when asked. ## Input -The commit plan and staged set from `01-collect`, the message from `02-message`, the run ledger, and whether to push (a trailing `push` argument). +The staged set from `01-collect`, the message from `02-message`, and whether to push (a trailing `push` argument). ## Output -The branch, push outcome, correction summary, and one final row per created commit. +The commit sha, branch, correction count, and push outcome. ## Process 1. **Commit.** Run `git commit` with the message. -2. **Classify.** When a hook rejects the commit, identify the failing check, its decisive error, and every file changed by the hook. -3. **Recover.** Correct and retry only when the fix is deterministic and can be restricted to the current commit's files. - - Re-stage only in-scope files changed by the hook or the correction. - - A message-policy failure loops through `02-message`; a path-bounded format or lint failure may use its specific fixer. - - Never run a repository-wide fixer, alter unrelated changes, or guess at a semantic, product, security, or architecture decision. - - Append the cycle's problem, correction, and result to the run ledger. - - Stop when the same failure repeats without meaningful progress, the correction needs broader authority, or the retry after the third correction still fails. -4. **Record.** After success, read the commit timestamp, short sha, subject, and committed file count from the created commit itself, then append them to the run ledger. Render the timestamp in the user's local timezone when known; otherwise preserve git's recorded offset. -5. **Repeat.** Return to `01-collect` for the next planned concern, preserving the ledger. -6. **Push.** After the last concern, push once when asked. Use `--force-with-lease` only when explicitly required, never `--force`. -7. **Report.** Emit the correction summary followed by the commit table. Do not add a validation column. - -If no correction was needed: - -> No correction needed. - -If corrections were made: - -| Cycle | Problem detected | Correction applied | Result | -| ---: | --- | --- | --- | -| 1 | `` | `` | `` | - -Always finish with: - -| Date and time | Commit | Message | Files | -| --- | --- | --- | ---: | -| `` | `` | `` | `` | +2. **Retry.** On hook rejection, re-stage and retry only a deterministic correction within the current commit's files. Stop and report the hook and error when it needs judgment, leaves scope, makes no progress, or fails three times. +3. **Push.** When asked, push the branch. Use `--force-with-lease` only when explicitly required, never `--force`. +4. **Report.** Return the short sha, subject, file count, correction count, and push outcome. ## Test - `git rev-parse HEAD` returns the new sha and its message matches the project convention. -- Every correction and re-staged file belongs to the current commit's authorized scope. -- A repeated, ambiguous, semantic, out-of-scope failure, or a failure after the third correction leaves no commit for that concern and reports the blocker. -- The correction summary contains exactly the cycles that changed something; the final table contains exactly the commits created by this run. +- Every correction and re-staged file belongs to the current commit's staged files. +- An ambiguous, out-of-scope, no-progress, or third failed correction leaves no commit and reports the blocker. - When pushed, the remote branch shows the final sha.