docs(execution-modes): document --fast-dirty (FEAT-13)

Extends the user-facing docs that lagged behind 1304885 with --fast-dirty
coverage in execution-modes.md (5-mode table, mermaid diagram, dedicated
section with use cases, clean-tree semantics, untracked handling, mutual
exclusion and composition with FEAT-1/FEAT-3), the three CLI command
pages (flow, flows, job), the configuration pages that list valid
 values (hooks, jobs, flows), and the README execution-modes
bullet and flags table.

Closes the last open checkbox of FEAT-13.

Author: Test

README.md

@@ -187,7 +187,7 @@ return [
 * **Hooks** map git events (`pre-commit`, `pre-push`, etc.) to flows and jobs. Supports conditional execution by branch (`only-on` / `exclude-on`) and staged file patterns (`only-files` / `exclude-files`).
 * **Flows** are named groups of jobs with shared options (`fail-fast`, `processes`, `time-budget`, `memory-budget`, `reports`). Reusable across hooks and directly executable from CLI. Meta-flows (`flows.<X>.flows`) compose other flows in a single run.
 * **Jobs** are individual QA tasks. Each declares a `type` and its arguments. Jobs can inherit from other jobs with `extends`. When `executable-path` is omitted, GitHooks auto-detects the binary in `vendor/bin/`. Per-job thresholds (`warn-after`, `fail-after`, `memory`, `cores`) cap regressions.
-* **Execution modes**: `full` (default), `--fast` (only staged files), `--fast-branch` (only files changed vs base branch), `--files` / `--files-from` (explicit list).
+* **Execution modes**: `full` (default), `--fast` (only staged files), `--fast-branch` (only files changed vs base branch), `--fast-dirty` (unified working tree: dirty vs `HEAD` ∪ untracked — ideal for AI agentic hooks), `--files` / `--files-from` (explicit list).
 
 See the [documentation site](https://wtyd.github.io/githooks/) for the full configuration reference.
 
@@ -233,7 +233,7 @@ Two ways to run non-PHP tools:
 
 | Flag | Purpose |
 |---|---|
-| `--mode=full\|fast\|fast-branch` / `--fast` / `--fast-branch` | Select execution mode. `fast` filters to staged files, `fast-branch` to files changed vs base branch. |
+| `--mode=full\|fast\|fast-branch\|fast-dirty` / `--fast` / `--fast-branch` / `--fast-dirty` | Select execution mode. `fast` filters to staged files, `fast-branch` to files changed vs base branch, `fast-dirty` to the unified working tree (dirty vs `HEAD` ∪ untracked). |
 | `--files=a,b,c` / `--files-from=PATH` / `--exclude-pattern=glob` | Run against an explicit list of files (CSV, manifest, or with exclusion patterns). |
 | `--processes=N`, `--fail-fast`, `--only-jobs=a,b`, `--exclude-jobs=a,b`, `--dry-run` | Control parallelism, fail-fast behaviour, and job selection. |
 | `--format=text\|json\|junit\|sarif\|codeclimate` | Output format on stdout. JSON v2 schema is stable. |

docs/cli/flow.md

@@ -23,7 +23,8 @@ githooks flow <name> [options]
 | `--no-reports` | Ignore the `reports` section from config (CLI `--report-*` flags still apply). PHPUnit `--no-coverage` style. |
 | `--fast` | Fast mode — accelerable jobs analyze only staged files. See [Execution Modes](../execution-modes.md). |
 | `--fast-branch` | Fast-branch mode — analyze files that differ from the main branch. The branch name comes from the [`main-branch` option](../configuration/options.md#available-options); see [Execution Modes](../execution-modes.md) and [Fast-branch fallback](../execution-modes.md#fast-branch-fallback). |
-| `--files=a,b,c` | Files mode — accelerable jobs analyze only the explicit list (CSV). Mutually exclusive with `--files-from`. Wins over `--fast`/`--fast-branch`. See [How-To: --files / --files-from](../how-to/files-flag.md). |
+| `--fast-dirty` | Fast-dirty mode — analyze the unified working tree: tracked files modified vs `HEAD` (staged or unstaged) ∪ non-ignored untracked. Ideal for AI agentic hooks and mid-review checks. Clean tree → all accelerable jobs skipped, exit 0 (no fallback to `full`). Mutually exclusive with `--fast`, `--fast-branch`, `--files`, `--files-from`. See [Fast-dirty mode](../execution-modes.md#fast-dirty-mode-fast-dirty). |
+| `--files=a,b,c` | Files mode — accelerable jobs analyze only the explicit list (CSV). Mutually exclusive with `--files-from`, `--fast`, `--fast-branch`, `--fast-dirty`. See [How-To: --files / --files-from](../how-to/files-flag.md). |
 | `--files-from=PATH` | Files mode — read the list of paths from `PATH` (one per line; `#` comments and blanks ignored; UTF-8 + CRLF tolerated). Use this when the list exceeds the shell `ARG_MAX` or comes from `git diff --name-only`. |
 | `--exclude-pattern=glob1,glob2` | Drop input paths that match any glob (`*`, `**`, `?`). Requires `--files` or `--files-from`. See [How-To: --files / --files-from](../how-to/files-flag.md#-exclude-pattern). |
 | `--monitor` | Show thread usage report after execution. See [Options: Thread budget](../configuration/options.md#thread-budget). |
@@ -58,6 +59,7 @@ githooks flow qa --report-sarif=reports/qa.sarif --report-junit=reports/junit.xm
 githooks flow qa --format=json --no-reports         # AI/script: JSON to stdout, no side-effect files
 githooks flow qa --fast                             # Only staged files
 githooks flow qa --fast-branch                      # Only branch diff files
+githooks flow qa --fast-dirty                       # Working tree diff vs HEAD ∪ untracked
 githooks flow qa --files=src/User.php               # Files mode: explicit single file
 githooks flow qa --files-from=changed.txt           # Files mode: from manifest
 githooks flow qa --files-from=changed.txt --exclude-pattern='**/*Test.php'
@@ -69,7 +71,7 @@ githooks flow qa --config=qa/custom-githooks.php    # Use custom config
 
 ## Structured output
 
-- **`--format=json`** emits JSON v2: top-level `version`, `executionMode` (reflects the actual `--fast`/`--fast-branch` flag), `passed`, `failed`, `skipped`, and a `jobs` array with `type`, `exitCode`, `paths`, `skipped`, `skipReason`, `fixApplied`, `command` and `output`. Jobs cancelled by `--fail-fast` appear with `skipped: true` and `skipReason: "skipped by fail-fast"`.
+- **`--format=json`** emits JSON v2: top-level `version`, `executionMode` (reflects the actual `--fast`/`--fast-branch`/`--fast-dirty` flag), `passed`, `failed`, `skipped`, and a `jobs` array with `type`, `exitCode`, `paths`, `skipped`, `skipReason`, `fixApplied`, `command` and `output`. Jobs cancelled by `--fail-fast` appear with `skipped: true` and `skipReason: "skipped by fail-fast"`.
 - **`--format=junit`** emits JUnit XML compatible with `mikepenz/action-junit-report` and similar. Skipped jobs emit `<skipped>` elements.
 - **`--format=codeclimate`** emits a GitLab Code Quality JSON array. `location.path` is relative to the CWD.
 - **`--format=sarif`** emits a SARIF 2.1.0 report for GitHub Code Scanning. `artifactLocation.uri` is relative to the CWD.

docs/cli/flows.md

@@ -32,7 +32,7 @@ Single-flow degenerate runs (`flows qa` with `qa` a normal flow) produce **the s
 
 ## Options
 
-The same flag set as [`flow`](flow.md): `--fail-fast`, `--processes`, `--exclude-jobs`, `--only-jobs`, `--format`, `--output`, `--report-*`, `--no-reports`, `--fast`, `--fast-branch`, `--fast-branch-fallback`, `--files`, `--files-from`, `--exclude-pattern`, `--monitor`, `--no-ci`, `--show-progress`, `--config`, `--dry-run`. Only the positional argument changes (variadic instead of single).
+The same flag set as [`flow`](flow.md): `--fail-fast`, `--processes`, `--exclude-jobs`, `--only-jobs`, `--format`, `--output`, `--report-*`, `--no-reports`, `--fast`, `--fast-branch`, `--fast-dirty`, `--fast-branch-fallback`, `--files`, `--files-from`, `--exclude-pattern`, `--monitor`, `--no-ci`, `--show-progress`, `--config`, `--dry-run`. Only the positional argument changes (variadic instead of single).
 
 `--exclude-jobs` and `--only-jobs` apply to the **merged deduplicated list** of jobs after meta-flow expansion, not per source flow. `--files` / `--files-from` build a **single** `ExecutionContext` shared by every job.
 

docs/cli/job.md

@@ -21,7 +21,8 @@ githooks job <name> [options]
 | `--no-reports` | Ignore the `reports` section from config (CLI `--report-*` flags still apply). |
 | `--fast` | Fast mode — analyze only staged files. See [Execution Modes](../execution-modes.md). |
 | `--fast-branch` | Fast-branch mode — analyze branch diff files. The branch name comes from the [`main-branch` option](../configuration/options.md#available-options); see [Execution Modes](../execution-modes.md) and [Fast-branch fallback](../execution-modes.md#fast-branch-fallback). |
-| `--files=a,b,c` | Files mode — explicit list (CSV). Mutually exclusive with `--files-from`. Wins over `--fast`/`--fast-branch`. See [How-To: --files / --files-from](../how-to/files-flag.md). |
+| `--fast-dirty` | Fast-dirty mode — analyze the unified working tree (tracked files modified vs `HEAD`, staged or unstaged, ∪ non-ignored untracked). Clean tree → job skipped, exit 0 (no fallback to `full`). Mutually exclusive with `--fast`, `--fast-branch`, `--files`, `--files-from`. See [Fast-dirty mode](../execution-modes.md#fast-dirty-mode-fast-dirty). |
+| `--files=a,b,c` | Files mode — explicit list (CSV). Mutually exclusive with `--files-from`, `--fast`, `--fast-branch`, `--fast-dirty`. See [How-To: --files / --files-from](../how-to/files-flag.md). |
 | `--files-from=PATH` | Files mode — read paths from a manifest file (one per line). |
 | `--exclude-pattern=glob1,glob2` | Drop input paths that match any glob. Requires `--files` or `--files-from`. |
 | `--no-ci` | Disable auto-detection of CI annotations. See [CI Annotations](../how-to/ci-cd.md#ci-annotations). |
@@ -43,6 +44,7 @@ githooks job phpunit_all --format=json    # JSON v2 output to stdout
 githooks job phpstan_src --format=sarif   # SARIF 2.1.0 to stdout
 githooks job phpstan_src --format=sarif --output=reports/phpstan.sarif   # SARIF to a file
 githooks job phpcs_src --fast             # Only staged files
+githooks job phpcs_src --fast-dirty       # Working tree diff vs HEAD ∪ untracked
 githooks job phpstan_src --files=src/User.php   # Files mode: single explicit file (IDE on-save)
 githooks job phpstan_src --files-from=changed.txt   # Files mode: read paths from manifest
 githooks job phpunit_all -- --filter=testFoo          # Pass extra args to the tool

docs/configuration/flows.md

@@ -97,7 +97,7 @@ Each entry in `flows.<X>.jobs` can be either a plain string (job name) **or** an
 ],
 ```
 
-When the flow runs in `--fast` / `--fast-branch`, each entry's rules are evaluated against the change set:
+When the flow runs in `--fast`, `--fast-branch` or `--fast-dirty`, each entry's rules are evaluated against the change set:
 
 - A file `F` **admits** the job when `match(only-files, F) AND NOT match(exclude-files, F)`.
 - The job **runs** if at least one file admits it; otherwise it appears in the output as `skipped: true` with a clear `skipReason` (consistent with JSON / SARIF / JUnit reporting).
@@ -180,7 +180,7 @@ In `master` the mode is `full` (FEAT-1's `only-files` rules become no-op). In a
 
 The effective mode is decided in this order (first that produces a value wins):
 
-1. `--fast` / `--fast-branch` CLI flags.
+1. `--fast` / `--fast-branch` / `--fast-dirty` CLI flags.
 2. `flows.<X>.on` matched against the current branch.
 3. `flows.<X>.execution`.
 4. `flows.options.execution` (global default).
@@ -230,7 +230,7 @@ Same semantics as FEAT-1's `only-files` / `exclude-files`:
 
 ### Scope and caveats
 
-- **Per-flow only.** Multi-flow runs (`githooks flows X Y`) ignore per-flow `on` (matches the existing CON-001/002 for flow-level options). The mode comes from `--fast/--fast-branch` or `flows.options.execution`.
+- **Per-flow only.** Multi-flow runs (`githooks flows X Y`) ignore per-flow `on` (matches the existing CON-001/002 for flow-level options). The mode comes from `--fast`/`--fast-branch`/`--fast-dirty` or `flows.options.execution`.
 - **`execution` is the only supported attribute today.** The object shape leaves room for `time-budget` / `fail-fast` to be added later without breaking the surface.
 - **`PHP collapses duplicate map keys.** `'master' => …, 'master' => …` cannot be detected — PHP keeps only the last entry.
 
@@ -308,7 +308,7 @@ When there is no JS in the change set, both skip by `only-files` (FEAT-1) — co
 
 ### Composition with `on` (FEAT-2)
 
-The execution mode chosen by `on` does not affect `needs`. Dependencies are structural — they hold in `full`, `fast`, and `fast-branch` alike.
+The execution mode chosen by `on` does not affect `needs`. Dependencies are structural — they hold in `full`, `fast`, `fast-branch`, and `fast-dirty` alike.
 
 ### Overriding in `githooks.local.php`
 

docs/configuration/hooks.md

@@ -71,7 +71,7 @@ Hook refs can include conditions that control when a flow/job is executed:
 | `exclude-on` | Array of branch names or glob patterns. The ref is skipped if the current branch matches any pattern. **Always prevails over `only-on`**. Can be used alone. |
 | `only-files` | Array of file glob patterns. The ref is skipped if no staged files match any pattern. |
 | `exclude-files` | Array of file glob patterns. Staged files matching any pattern are excluded from triggering execution. **Always prevails over `only-files`**. Can be used alone. |
-| `execution` | String. Per-hook-ref execution mode override (`full`, `fast`, `fast-branch`). |
+| `execution` | String. Per-hook-ref execution mode override (`full`, `fast`, `fast-branch`, `fast-dirty`). |
 
 When multiple conditions are present, they are **AND-ed** — all must be satisfied for the ref to execute.
 
@@ -119,7 +119,7 @@ Hook refs can specify an execution mode that overrides the default:
 ],
 ```
 
-See [Execution Modes](../execution-modes.md) for details on `full`, `fast`, and `fast-branch`.
+See [Execution Modes](../execution-modes.md) for details on `full`, `fast`, `fast-branch` and `fast-dirty`.
 
 !!! info
     For `pre-commit` events, fast mode is activated automatically — you don't need to specify `'execution' => 'fast'`.

docs/configuration/jobs.md

@@ -45,7 +45,7 @@ The following keywords are available for all job types (except `custom`, which h
 | `ignore-errors-on-exit` | Boolean | Job returns exit 0 even with problems. Default `false`. |
 | `fail-fast` | Boolean | Stop remaining jobs in the flow if this one fails. Default `false`. |
 | `accelerable` | Boolean | Override `--fast` behavior. Default depends on type. |
-| `execution` | String | Per-job execution mode override: `full`, `fast`, or `fast-branch`. |
+| `execution` | String | Per-job execution mode override: `full`, `fast`, `fast-branch`, or `fast-dirty`. |
 | `executable-prefix` | String | Per-job prefix override. Set to `null` or `''` to opt out of the global prefix. |
 | `cores` | Integer | Reserve N cores in the [thread budget](options.md#thread-budget). See [Reserving cores explicitly](#reserving-cores-cores-or-the-tools-native-flag) below. |
 | `memory` | Integer or Object | Per-job memory threshold (MB) — and 2D allocator reservation when given as a short integer. See [Per-job memory threshold](#per-job-memory-threshold-memory) below. |