dotnet-production-agent-skills 0.3.0 → 0.3.2

package/README.md

@@ -163,7 +163,7 @@ The catalog is grouped by task so agents can load only the guidance relevant to
 | :--- | :--- | :--- |
 | [`task-router`](skills/task-router/SKILL.md) | Classify requests to select the smallest proportionate workflow when the path forward is ambiguous. | — |
 | [`context-reset`](skills/context-reset/SKILL.md) | Reorient safely when user instructions interrupt, pivot, or invalidate an in-progress coding task. | — |
-| [`safe-terminal`](skills/safe-terminal/SKILL.md) | Execute shell commands safely, handle failures, and prevent accidental mutations or credential leaks. | — |
+| [`safe-terminal`](skills/safe-terminal/SKILL.md) | Execute shell commands safely, handle failures, and prevent accidental mutations or credential leaks. | [shell-recovery](skills/safe-terminal/references/shell-recovery.md) |
 | [`poc-development`](skills/poc-development/SKILL.md) | Build bounded, explicit spikes or prototypes to answer technical questions without cutting production corners prematurely. | — |
 
 ### 2. 🏗️ Architecture & Core Implementation
@@ -293,6 +293,8 @@ The CLI installs and manages guidance; it does not route prompts or load every s
 
 The initial policy blocks force-push, destructive Git reset/clean/branch deletion, broad recursive deletion, and direct access to common credential-bearing files. Safe commands continue normally. Host configuration is written to `.codex/hooks.json`, `.github/hooks/dotnet-production-agent-skills.json`, `.claude/settings.json`, `.cursor/hooks.json`, or `.agents/hooks.json` for Antigravity.
 
+Terminal recovery guidance keeps commands anchored to the intended repository, separates executable lookup from repository selection, and forbids moving into Git/tool installation directories as a workaround. Copilot project instructions include the critical rules so they are available even before the focused `safe-terminal` skill is selected. Skills and instructions guide the model; the existing hooks do not enforce these directory/recovery rules. See the skill's [shell recovery examples](skills/safe-terminal/references/shell-recovery.md) for diagnostics and primary sources.
+
 Copilot project installs manage only the text between `<!-- dotnet-production-agent-skills:start -->` and `<!-- dotnet-production-agent-skills:end -->`. Existing team instructions outside those markers remain intact. Uninstall removes only the managed section. User-scope Copilot installs install skills into `~/.copilot/skills`; repository instructions apply only to project scope.
 
 ```sh

package/RELEASE_NOTES.md

@@ -1,5 +1,32 @@
 # Release notes
 
+## v0.3.2 — Repository-safe terminal recovery
+
+Prepared for publication; this version has not yet been published to npm.
+
+### Improved
+
+- Keep terminal commands anchored to the intended project. Never recover a failed project command by moving into Git or another tool's installation directory.
+- Separate executable lookup from repository selection. Verify the intended Git root before mutations, preserve linked-worktree support, and inspect relevant Git overrides when an explicit project path selects an unexpected repository.
+- Diagnose the submitted/executed command and first actionable error before retrying. Submit plain command text, preserve requested arguments, and avoid speculative shell, PATH, profile, configuration, or installation changes.
+- Include the core recovery rules in managed Copilot project instructions and global engineering guidance, and connect Git workflows to `safe-terminal`.
+
+### Documentation
+
+- Add `references/shell-recovery.md` with PowerShell, Command Prompt, and Bash diagnostics, quoting/invocation examples, failure classification, and primary documentation sources.
+- Advertise the reference in both the README and hosted skills catalog.
+- Refresh the website release-notes page with clearer publication status and a new layout.
+
+### Compatibility and upgrade
+
+- CLI targets, scopes, flags, and copy/link modes are unchanged.
+- These changes strengthen agent guidance; existing hooks do not enforce the new repository-directory recovery rules.
+- After publication, update installed skills with `npx dotnet-production-agent-skills@0.3.2 update --target all`. Run the update in project scope (`--scope project`) to refresh that project's managed Copilot instructions and installed skills. Review local edits before updating.
+
+### Validation
+
+`npm run validate` passed: 31 skills validated and 21 tests passed. Five recovery scenarios were evaluated independently as proposed commands; Windows commands were not executed on Windows. Catalog metadata, reference paths, and whitespace checks passed.
+
 ## v0.3.0 — Multi-agent hooks and Antigravity
 
 ### New
@@ -19,6 +46,15 @@
 - GitHub release tags are authoritative for release-triggered npm publishes. A `v0.3.0` release aligns both package files to `0.3.0` before checking npm availability or publishing, even when the tagged commit still contains an already-published version.
 - The workflow now fails early if the resolved tag version and `package.json` ever disagree, preventing an old package version from being checked or published accidentally.
 
+## v0.3.1 — Safe terminal diagnostics
+
+Released in [`dotnet-production-agent-skills@0.3.1`](https://www.npmjs.com/package/dotnet-production-agent-skills/v/0.3.1).
+
+### Improved
+
+- Updated `safe-terminal` to distinguish malformed or control-character input from an executable that is unavailable in the current shell.
+- Added read-only executable lookup guidance for PowerShell, Command Prompt, and POSIX shells, plus evidence-based retry and environment-change safeguards.
+
 ## Unreleased — Redis caching skill
 
 Proposed in [PR #6](https://github.com/dprakash2101/dotnet-production-agent-skills/pull/6); this change is not yet published to npm.

package/copilot/production-instructions.md

@@ -6,3 +6,5 @@ Never log secrets or sensitive payloads. Add operationally useful logs, and limi
 Do not introduce retries automatically. Add them only when requested or required by existing architecture, and only for safe transient operations.
 When behavior changes, check whether existing tests need updating. Avoid redundant tests that slow CI.
 Run the smallest appropriate validation, build, or test command after changing code.
+
+Before terminal commands, apply the safe-terminal skill and verify the actual shell and project working directory. After a failure, inspect the submitted/executed command and first actionable error before choosing a correction. Never add terminal control sequences or move into Git/tool installation folders as a workaround. Executable location and repository location are separate: keep commands in the project, verify Git's intended repository with `git -C "<project-path>" rev-parse --show-toplevel`, and use same-session executable lookup only for a genuine command-not-found error. Do not guess binary paths, switch shells, edit PATH/profiles/configuration, or reinstall tools to escape an unexplained failure. Retry only after an evidence-based correction; stop after at most three distinct corrections.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotnet-production-agent-skills",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Portable production .NET engineering skills for coding agents",
   "license": "MIT",
   "author": {

package/skills/git-workflow/SKILL.md

@@ -5,6 +5,8 @@ description: Perform safe Git branch, stage, commit, and push operations for eng
 
 # Fast, safe Git workflow
 
+Apply `safe-terminal` before execution and on command failure. Keep the working directory in the intended project, verify the repository root when context is not established, and never recover by moving into Git's installation folder. Executable lookup does not select the repository. Split diagnostic recovery from the mutation sequence below; resume only when the cause is corrected and repository context is verified.
+
 Minimize terminal calls and token-heavy output without weakening review. Batch compatible Git commands into the fewest practical invocations, and reuse branch, status, diff, validation, and remote facts already established in the current task when no intervening operation could have changed them. Do not issue one tool call per Git command by default.
 
 For a fresh preflight, prefer one combined inspection such as `git status --short --branch` instead of separate status and branch commands. Inspect only the relevant diff; do not repeat a full diff review that was just completed.

package/skills/safe-terminal/SKILL.md

@@ -1,59 +1,50 @@
 ---
 name: safe-terminal
-description: Run and recover from terminal commands safely, especially after malformed, corrupted, or unexpectedly failing CLI commands. Use for shell troubleshooting or commands that could affect tools, credentials, configuration, or data.
+description: Apply before terminal or Git execution and when recovering from malformed commands, executable lookup failures, wrong working directories, or shell errors. Preserve repository context, diagnose the actual error, and prevent speculative installation-path or environment workarounds.
 ---
 
 # Safe terminal
 
-Before execution, verify the command, working directory, resolved target, quoting, and likely side effects. Prefer read-only inspection before mutation and narrow explicit paths over broad globs or unresolved variables.
+Before execution, verify the command, shell, working directory, resolved target, quoting, and likely side effects. Prefer read-only inspection before mutation and narrow explicit paths over broad globs or unresolved variables.
 
-## Automatic command correction
+## Keep executable location separate from repository context
 
-When a command is about to be executed or has just failed, detect and fix the problem **before** escalating to environment changes. Common causes include but are not limited to:
+Keep the working directory anchored to the user's project. The directory containing `git.exe`, a shell executable, or other CLI binaries is **not** the repository. Never `cd` into a tool installation directory or set the terminal tool's `cwd`/`workdir` there to recover a project command. Never use Git's installation directory as `git -C`, `--git-dir`, or `--work-tree`.
 
-- **Control-character prefixes** — Agent hosts sometimes prepend `^Q` (XON), `^C`, `^M`, `^[`, or other stray bytes. For example `^Qgit add .` resolves to a nonexistent executable and the shell may search tool installation directories instead of running `git`. Strip the prefix, log what was removed, and re-execute.
-- **Typos and misspellings** — `gti status`, `dontnet build`, `nmp install`. Map to the obvious intended command.
-- **Wrong or missing flags** — `git commit` without `-m`, `dotnet test --filtre` instead of `--filter`.
-- **Quoting and escaping errors** — Unmatched quotes, unescaped special characters, or shell-expansion issues.
-- **Wrong working directory** — Command assumes a project root but the shell is in a subdirectory or vice versa.
-- **Missing arguments** — Required positional arguments omitted.
-- **Stale or incorrect paths** — File or directory references that do not exist or have moved.
+- Use the terminal tool's explicit working-directory parameter when available. Otherwise use shell-correct navigation to the verified project path and stop if navigation fails. Do not assume a previous terminal call's `cd` persists.
+- For Git repository operations, establish the intended project from workspace/task evidence, then verify `git -C "<project-path>" rev-parse --show-toplevel`. Confirm that the returned root is the intended repository before mutation; a successful command in an unrelated repository is not success. Allow a subdirectory or linked worktree; do not require `.git` to be a directory.
+- If a command fails with “not a git repository,” Git already started. Investigate the project path and repository context, not installation or `PATH`. If the root is unknown or ambiguous, stop and ask for the project location; do not search installation folders, initialize a repository, or guess another checkout.
+- A resolved absolute executable path may be used only after same-session lookup establishes a genuine executable-resolution problem. Invoke that binary **from the project directory**, retain the requested arguments, and use the actual shell's quoting/invocation syntax. Do not confuse invoking an installed binary with running a project command from its installation folder.
+- If an explicit project path still selects an unexpected repository, inspect only relevant overrides (`GIT_DIR`, `GIT_WORK_TREE`, `GIT_COMMON_DIR`), without dumping the environment. Do not clear them, set replacement overrides, or edit configuration without understanding their purpose and obtaining authorization where required.
 
-In every case, correct only what is broken and preserve the original intent.
+## Inspect what the shell actually ran
 
-## Feedback loop
+When a command fails, compare the submitted text, the command displayed by the terminal, and the executable named in the error. A copied command can contain invisible bytes or terminal control sequences, while the shell or tool host may strip or interpret them before execution. A caret rendering such as `^X` is a clue to inspect, not proof that it reached the shell as part of the executable name.
 
-Follow a structured inspect → classify → correct → retry → verify cycle for every failure instead of retrying blindly or escalating to environment changes.
+- If a leading or embedded control character, escape sequence, pasted prompt, line break, or malformed token **survived into the executable or arguments**, reconstruct a clean command from the intended tokens. Show the meaningful correction and retry once.
+- If the error names the expected executable, do not claim a prefix caused the failure merely because the submitted text contains one. Diagnose that executable's availability in the actual shell and process environment.
+- Treat multiple visible anomalies independently. Removing one does not establish that the next failure has the same cause.
 
-```text
-┌──────────────────────────────────────────────────┐
-│  1. INSPECT  — Read the exact command and error  │
-│     ↓                                            │
-│  2. CLASSIFY — Identify the single root cause:   │
-│     control-char prefix? typo? quoting? flags?   │
-│     wrong directory? missing arg? env problem?   │
-│     ↓                                            │
-│  3. CORRECT  — Fix only the identified cause     │
-│     ↓                                            │
-│  4. RETRY    — Execute the corrected command     │
-│     ↓                                            │
-│  5. VERIFY   — Did the retry succeed?            │
-│     • YES → Continue with the task               │
-│     • NO  → Return to step 1 with the new error  │
-│             (max 3 iterations, then report)      │
-└──────────────────────────────────────────────────┘
-```
+Check typos, flags, quoting, shell-specific syntax, working directory, paths, and missing arguments only where the command or output supports them. Preserve the user's requested operation and options; do not drop build, restore, test, or safety flags just to make the command run.
 
-### Feedback-loop rules
+Submit plain command text. Do not prepend terminal keyboard shortcuts, control bytes, escape sequences, or copied prompt text to clear or repair a command line. If submitted and executed text differ repeatedly, inspect the terminal/tool transport or report that blocker; do not keep adding control sequences.
 
-- **At most 3 correction attempts** for the same logical command. After three failures, stop retrying and report the full error chain—each attempted command and its output—to the user.
-- **Each iteration must identify a different root cause.** Retrying the same fix is not a correction.
-- **Never escalate to environment mutation** (changing `PATH`, installing packages, editing shell profiles, modifying credentials) unless the loop conclusively shows a genuine environment gap **and** the user explicitly approves the change.
-- **Preserve original intent.** If the corrected command differs in meaning from what was requested, confirm with the user before executing.
+## Diagnose an unavailable executable
 
-## Environment protection
+For a command-not-found error, use read-only checks in the **same shell/session** that failed. In PowerShell, use `Get-Command <name> -All` and, where useful, `where.exe <name>`; in cmd use `where <name>`; in POSIX shells use `command -v <name>`. Check the current `PATH` without printing credentials or unrelated environment values. If the tool is found, distinguish a typo or wrong shell from an executable that is present but absent from that process's `PATH`. If it is not found, report that the tool is unavailable in this environment; do not guess its installation path or repeatedly run the same command.
 
-Do not respond to malformed input by changing `PATH`, shell profiles, installations, credentials, authentication, or tool configuration. Require evidence and appropriate permission before any such change.
+Use an already configured shell or approved tool runner only when evidence shows it resolves the issue without changing project configuration; preserve and reverify the project directory in that environment. Do not switch shells just to bypass a parsing error, execution policy, or approval. Do not respond to a malformed command by installing software, editing `PATH` or shell profiles, changing credentials, or changing tool configuration. Require evidence and appropriate authorization for environment changes.
+
+Use [shell recovery examples](references/shell-recovery.md) when choosing shell-specific diagnostics or distinguishing executable lookup from repository/path failures.
+
+## Correct, retry, verify
+
+1. Inspect the exact attempted command and first actionable error; distinguish shell parsing, executable lookup, and tool-level failure.
+2. Make the smallest evidence-based correction. State what changed when it is material.
+3. Retry only if the cause is corrected and the original operation is authorized. Check the new output as a new failure, rather than assuming the previous diagnosis still applies.
+4. Stop after a bounded number of distinct corrections (at most three for the same logical command). Report the unresolved blocker and the relevant checks without dumping secrets or verbose logs.
+
+Never silently substitute a different operation. Ask before a correction changes the requested result or has new side effects.
 
 ## Destructive-action safety
 

package/skills/safe-terminal/references/shell-recovery.md

@@ -0,0 +1,39 @@
+# Shell recovery examples
+
+Use these as diagnostic patterns, not commands to run unconditionally. Replace placeholders only with paths established from task/workspace evidence. Keep checks read-only and in the failing shell; do not print the full environment.
+
+## Choose the diagnostic for the actual shell
+
+| Check | PowerShell | cmd.exe | Bash / POSIX shell |
+| --- | --- | --- | --- |
+| Current directory | `Get-Location` | `cd` | `pwd` |
+| Executable resolution | `Get-Command git -All` | `where git` | `command -v git` |
+| Verify project repository | `git -C "<project-path>" rev-parse --show-toplevel` | Same | Same |
+
+When navigation is required, use `Set-Location -LiteralPath '<project-path>' -ErrorAction Stop` in PowerShell, `cd /d "<project-path>"` in cmd (including drive changes), or `cd -- "<project-path>"` in Bash. Stop on failure; never run the project operation after failed navigation. Prefer a tool-provided working directory instead.
+
+If same-session lookup proves a bare executable name cannot resolve but identifies the installed binary, keep the project working directory and invoke the resolved executable. PowerShell requires `& '<resolved-git.exe-path>' -C '<project-path>' status`; cmd uses `"<resolved-git.exe-path>" -C "<project-path>" status`; Bash uses `"<resolved-git-path>" -C "<project-path>" status`. Pass arguments separately; do not evaluate a generated command string. These are conditional examples, not permission to guess binary locations.
+
+## Classify failures before recovery
+
+| Evidence | Next step | Do not infer or do |
+| --- | --- | --- |
+| Executed executable token contains pasted prompt/control text | Reconstruct plain intended tokens; retry once if authorized | Guess an installation path or alter PATH |
+| Submitted text looks corrupted, but error names the intended executable | Inspect actual executable resolution in that session | Assume the visible corruption caused command-not-found |
+| Git reports that the directory is not a repository | Verify workspace path and root using `git -C` | Reinstall Git, move into its installation, or run `git init` |
+| Quoted executable path produces a PowerShell parsing/invocation error | Correct invocation syntax with `&`; retain arguments and project path | Switch shells or concatenate executable and arguments into one string |
+| Project path has spaces or cmd is on another drive | Correct quoting/navigation, verify the resulting directory | Treat the executable's containing folder as the project |
+| Verified project returns an unexpected Git root | Inspect relevant repository overrides and workspace identity | Clear overrides blindly or mutate the other repository |
+| New session starts in a tool installation folder | Set explicit verified project context before repository operations | Assume a prior session's `cd` persisted |
+| Clean command still cannot resolve and no binary is found | Report tool unavailable in that shell/environment | Retry repeatedly or silently install/reconfigure |
+
+## Sources and enforcement boundary
+
+- [Git command options and environment](https://git-scm.com/docs/git): `-C` selects command context; executable location does not select a repository.
+- [Git repository-root inspection](https://git-scm.com/docs/git-rev-parse): `--show-toplevel` reports the working tree root.
+- [PowerShell call operator](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_operators#call-operator-): invoke a quoted executable with `&` and separate arguments.
+- [cmd directory navigation](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/cd): `/d` changes the drive as well as the directory.
+- [VS Code agent skills](https://code.visualstudio.com/docs/agent-customization/agent-skills) and [instructions](https://code.visualstudio.com/docs/agent-customization/custom-instructions): keep critical recovery rules in project instructions as well as the focused skill.
+- [VS Code hooks](https://code.visualstudio.com/docs/agent-customization/hooks): host-supported hooks can enforce policy independently of model guidance; schemas and behavior differ by harness.
+
+Treat this skill as behavioral guidance, not a sandbox or guaranteed block. Existing package hooks do not enforce repository-directory recovery. Verify hook support and actual payloads before adding enforcement; do not invent a portable hook format or claim instruction text guarantees compliance.