docs(agent-audit): enforce user edits precedence

- Forbid discard operations unless explicitly requested
- Remove guidance that implies user edits can be discarded by default
- Add warnings to git references and self-review command

Author: d-padmanabhan

commands/self-review.md

@@ -4,20 +4,23 @@ description: Comprehensive local code review comparing current branch to main -
 
 # SELF CODE REVIEW MODE ACTIVATED
 
-You are now in **SELF REVIEW** phase - performing a comprehensive local code review comparing the current branch to `main`, following the structured review approach from `100-core.mdc` and `050-workflow.mdc`.
+You are now in **SELF REVIEW** phase - performing a comprehensive local code review comparing the current branch to `main`, following the structured review approach from `100-core.mdc` and `010-workflow.mdc`.
 
 > [!IMPORTANT]
-> This is a **read-only analysis**. No commits or pushes will be made without explicit user authorization (see `060-agent-audit.mdc`).
+> This is a **read-only analysis**. No commits or pushes will be made without explicit user authorization (see `020-agent-audit.mdc`).
 
 ## Phase 1: Context Gathering & Audit Setup
 
-**Audit Requirements (from `060-agent-audit.mdc`):**
+**Audit Requirements (from `020-agent-audit.mdc`):**
 
 - Record baseline: `HEAD` SHA, branch name, timestamp
 - Document all commands with exit codes in audit report
 
 > [!NOTE]
-> **Checkpoints:** Only create checkpoints (`git stash`, rollback branch) if Phase 5 (Automated Fixes) will be applied. For read-only analysis, baseline recording is sufficient since formatting changes are easily reversible with `git restore` or `git checkout`.
+> **Checkpoints:** Only create checkpoints (`git stash`, rollback branch) if Phase 5 (Automated Fixes) will be applied.
+> For read-only analysis, baseline recording is sufficient.
+>
+> Do not discard user working-tree edits with `git restore` / `git checkout --` unless the user explicitly asks (see `020-agent-audit.mdc`).
 
 1. **Branch Information:**
    - Current branch name (`git branch --show-current`)
@@ -130,7 +133,7 @@ Generate a structured review report:
 ## Phase 5: Automated Fixes (Optional)
 
 > [!IMPORTANT]
-> **Before applying fixes:** Create checkpoints per `060-agent-audit.mdc`:
+> **Before applying fixes:** Create checkpoints per `020-agent-audit.mdc`:
 >
 > - `git stash push -u -m "checkpoint/<YYYYMMDD_HHMMSS>"`
 > - `git branch "checkpoint/<YYYYMMDD_HHMMSS>" <baseline-sha>`
@@ -149,7 +152,7 @@ Generate a structured review report:
 3. **Re-run linters:** Verify fixes resolved issues
 
 > [!TIP]
-> Formatting changes are easily reversible with `git restore <file>` or `git checkout -- <file>`, but checkpoints provide additional safety for complex changes.
+> If the user wants to revert formatting changes, propose the exact revert commands (for example `git restore <file>`), but do not run them unless the user explicitly asks. Checkpoints provide additional safety for complex changes.
 
 ## Phase 6: Verification & Audit Report
 
@@ -158,7 +161,7 @@ Generate a structured review report:
 3. **Diff summary:** Show final `git diff main...HEAD --stat`
 4. **Ready for PR:** Confirm all Critical issues resolved
 
-**Generate Audit Report (per `060-agent-audit.mdc`):**
+**Generate Audit Report (per `020-agent-audit.mdc`):**
 
 - Ensure `GIT_REPO_ROOT` is set, then write/append the report to `<GIT_REPO_ROOT>/extras/agent_reports/$(date +%F)-agent-report-<repo>-<branch>.md` (if `<GIT_REPO_ROOT>/extras/` exists and is gitignored) or `/tmp/$(date +%F)-agent-report-<repo>-<branch>.md`
 - Include:
@@ -179,7 +182,7 @@ Generate a structured review report:
 - Refactor code not part of current changes
 - Add features not in the current scope
 - Change APIs or break existing functionality
-- **Commit or push** without explicit user authorization (see `060-agent-audit.mdc`)
+- **Commit or push** without explicit user authorization (see `020-agent-audit.mdc`)
 - Perform any remote writes (git push, PR creation, etc.)
 
 ✅ **DO:**
@@ -230,7 +233,7 @@ If CodeRabbit is available and configured for the repository:
 
 **Integration:** This workflow aligns with:
 
-- `050-workflow.mdc` Review Phase
+- `010-workflow.mdc` Review Phase
 - `100-core.mdc` Code Review Mode standards
-- `060-agent-audit.mdc` Audit requirements
+- `020-agent-audit.mdc` Audit requirements
 - `110-git.mdc` Commit standards

rules/020-agent-audit.mdc

@@ -54,6 +54,19 @@ Minimum checkpoints:
 - **Rollback anchor**: create a local checkpoint reference:
   - `git branch "checkout-point/<id>" <baseline-sha>`
 
+> [!IMPORTANT]
+> **User edits always take precedence.**
+>
+> AI agents MUST NOT discard or overwrite a user's manual working-tree changes unless the user explicitly asks.
+> Treat these as destructive operations that require explicit user direction:
+>
+> - `git restore ...` (worktree discard)
+> - `git checkout -- ...` (worktree discard)
+> - `git reset --hard ...` (index + worktree discard)
+> - `git clean -fd ...` (untracked deletion)
+>
+> If the agent needs to revert *its own* changes, it must propose the exact commands and file list first and wait for approval.
+
 Checkpoint rules:
 - Each checkpoint MUST have a unique `<id>` (recommend `YYYYMMDD_HHMMSS`).
 - Every checkpoint MUST be recorded with a timestamp and identifier in the audit report.

rules/130-git.mdc

@@ -592,6 +592,10 @@ Git 2.23+ split the multi-purpose `checkout` into focused commands for clarity a
 | `git checkout -- file` | `git restore file` | Restore file from index |
 | `git checkout HEAD -- file` | `git restore -s HEAD file` | Restore file from commit |
 
+> [!IMPORTANT]
+> `git restore`, `git checkout -- <path>`, `git reset --hard`, and `git clean -fd` can discard local changes.
+> AI agents MUST NOT run discard operations unless the user explicitly requests it.
+
 **Why prefer `switch`?**
 
 `checkout` is a multi-purpose tool that does many different things: switch branches, create branches, restore files, detach HEAD. When you see `git checkout somename`, you cannot immediately tell if it is switching to a branch, restoring a file, or going to a specific commit.

skills/core-engineering/references/git-modern-commands.md

@@ -2,6 +2,10 @@
 
 Git 2.23+ split the multi-purpose `checkout` into focused commands for clarity and safety.
 
+> [!IMPORTANT]
+> Commands like `git restore`, `git checkout -- <path>`, `git reset --hard`, and `git clean -fd` can discard local changes.
+> If you are operating as an AI agent, do not run discard operations unless the user explicitly requests it.
+
 ## `git switch` vs `git checkout`
 
 | Old Command | New Command | Purpose |

skills/core-engineering/references/git-reflog.md

@@ -1,5 +1,9 @@
 # The Reflog: Git's Safety Net
 
+> [!IMPORTANT]
+> `git reset --hard` and similar commands can discard local changes.
+> If you are operating as an AI agent, do not run discard operations unless the user explicitly requests it.
+
 ## What is the Reflog?
 
 The **reflog** (reference log) is Git's time machine. While `git log` shows only commits reachable from branches/tags, the reflog records **every movement of HEAD** — every checkout, reset, commit, rebase, branch switch, and even "lost" commits.