bmad-module-ultracode-goal 3.0.0-rc.1 → 3.0.0

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.
@@ -19,7 +19,7 @@
19
19
  "name": "bmad-module-ultracode-goal",
20
20
  "source": "./",
21
21
  "description": "Supercharges BMAD with Claude Code's Auto Mode, Auto Memory, and hooks: autonomous Epic execution to a machine-checked, TEA-gated Definition-of-Done. Execute Epics. Accumulate Knowledge. Deliver Outcomes.",
22
- "version": "3.0.0-rc.1",
22
+ "version": "3.0.0",
23
23
  "author": {
24
24
  "name": "Armel"
25
25
  },
@@ -103,7 +103,7 @@ Each recall call is attempted once and never retried. A run whose recall turned
103
103
 
104
104
  The latch is how the guard knows a run is active. Only `mem_recall.py` changes it: `latch` writes or replaces it at Stage 1, and `unlatch` removes it at each exit (Finalize, a preflight STOP, or any other stop before Finalize, attended or headless), only when it carries that run's id.
105
105
 
106
- The latch never belongs in git. `latch` adds the line `.mem-state*` to the repository's `.git/info/exclude`, a local file git never commits, so on a project that tracks its artifacts folder the latch does not show in `git status`, does not trip preflight's clean-tree check, and is not staged by a `git add -A`. A latch git already tracks, which a run on an earlier release could commit, still shows as a change: `latch` then prints `NOTE recall-latch-visible`, and you untrack it once by hand.
106
+ The latch never belongs in git. `latch` adds a line for the latch to the repository's `.git/info/exclude`, a local file git never commits: `/<artifacts folder>/.mem-state*`, anchored to the implementation artifacts folder so no other file is hidden. So on a project that tracks its artifacts folder, the latch does not show in `git status`, does not trip preflight's clean-tree check, and is not staged by a `git add -A`. A latch git already tracks, which a run on an earlier release could commit, still shows as a change: `latch` then prints `NOTE recall-latch-visible`, and you untrack it once by hand, from a terminal of your own once no run is active: while a latch is present, the guard denies a command that names it.
107
107
 
108
108
  While a latch is present, whatever it records, the guard:
109
109
 
@@ -163,7 +163,7 @@ Each recall problem leaves a line in `.decision-log.md` and the run report: one
163
163
  | `NOTE recall-store-unset` | Stage 1: recall is `on` but the store key is unset, or is not a `~`, absolute or `{project-root}` path. | Set `cross_session_recall_store` in `[workflow]`. |
164
164
  | Red latch, `reason` `store-unwritable: <error>` | Stage 1: recall is `on` but the store folder could not be created or written. Recall is off for the run, and the run report repeats the reason. | Fix the folder (permissions, disk space, sandbox) or set the key to another folder. |
165
165
  | Red latch, `reason` `no-fingerprint` | Stage 1: the repo has no commit yet, or the session's working folder is not inside it, so its records have no folder. Recall is off for the run. | Make a first commit, or start the session from the project folder. |
166
- | `NOTE recall-latch-visible` | Stage 1: git can still see the latch, so it shows as a change and preflight's clean-tree check reads it. Either git already tracks it, committed by a run on an earlier release, or the repository's `.git/info/exclude` could not be written; the NOTE says which. | Untrack it once with `git rm --cached <the latch path>` and commit that, or fix the exclude file the NOTE names. |
166
+ | `NOTE recall-latch-visible` | Stage 1: git can still see the latch, so it shows as a change and preflight's clean-tree check reads it. Either git already tracks it, committed by a run on an earlier release, or the repository's `.git/info/exclude` could not be written; the NOTE says which. | Once no run is active, untrack it from a terminal of your own with `git rm --cached <the latch path>` and commit that, or fix the exclude file the NOTE names. While a latch is present, the guard denies a command that names it. |
167
167
  | A latch call that exits non-zero | Stage 1: the latch call failed (for example, the implementation artifacts folder cannot be written). It writes no latch, so Finalize also logs `NOTE recall-latch-missing`; the log holds what it printed. | Fix what the log names. |
168
168
  | A filter, drain or write call that exits non-zero | Stage 1 or Finalize: the call failed. The log and the run report hold what it printed, and the run goes on: a failed filter surfaces no advisories, a failed drain still lets the write run, and a failed write may leave no record. | Fix what the log names. |
169
169
  | `NOTE recall-read-refused` | Stage 1: the permission layer refused the latch or filter call. A refused latch call leaves no latch, so recall is off for the run and Finalize also logs `NOTE recall-latch-missing`. A refused filter call only skips the read: Finalize still writes the record. | Let the recall scripts' `uv run` calls through your permission mode. |
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://json.schemastore.org/package.json",
3
3
  "name": "bmad-module-ultracode-goal",
4
- "version": "3.0.0-rc.1",
4
+ "version": "3.0.0",
5
5
  "description": "BMAD module — Run a BMAD Epic autonomously to a machine-checked, TEA-gated Definition-of-Done.",
6
6
  "keywords": [
7
7
  "bmad",
@@ -69,7 +69,7 @@ uv run {skill-root}/scripts/mem_recall.py latch --impl-artifacts {workflow.imple
69
69
 
70
70
  The store value stays in single quotes, here and in every recall command, so the shell passes it as configured: a path with a space stays one argument, and a `$VAR` reaches the script unexpanded, where it counts as unset. The script itself expands a leading `~`, and resolves a project-root token against `--project-root`.
71
71
 
72
- It checks the knob, that the store key names a folder, this repo's fingerprint, and that the store can be written, then writes the latch in one atomic step, keeps it out of git (it adds `.mem-state*` to the repository's `.git/info/exclude`, so a tracked artifacts folder stays clean and a `git add -A` never stages the latch), and prints one JSON object, `{"latch": ..., "notes": [...], "reason": ...}`. The latch is **green** only when its `store_ok` is `true`, which takes recall `"on"`; with recall `"off"` it is written red on purpose. Log whether it is green, a red latch's `reason` and every line in `notes` to `.decision-log.md`. With `"on"` and no usable store key that line is `NOTE recall-store-unset`, naming the key, and Finalize's run report repeats it. With either knob, a `NOTE recall-latch-visible` line says git can still see the latch (git already tracks it, or the exclude file could not be written), so it reads as a change to preflight's `git_clean` check: carry it into the run report too, and leave the fix to the person, since untracking the latch is a change the run never makes. A red latch with recall `"on"` and no NOTE (its `reason` is `store-unwritable: ...` or `no-fingerprint`) is logged by that `reason`, which Finalize's run report repeats too. A latch call that exits non-zero writes no latch: log what it printed and go on with recall off. A latch another run left behind is replaced by this command and only by it: never delete the file, which the guard refuses while a latch is present.
72
+ It checks the knob, that the store key names a folder, this repo's fingerprint, and that the store can be written, then writes the latch in one atomic step, keeps it out of git (it adds a line for the latch, `/<artifacts folder>/.mem-state*`, to the repository's `.git/info/exclude`, so a tracked artifacts folder stays clean and a `git add -A` never stages the latch), and prints one JSON object, `{"latch": ..., "notes": [...], "reason": ...}`. The latch is **green** only when its `store_ok` is `true`, which takes recall `"on"`; with recall `"off"` it is written red on purpose. Log whether it is green, a red latch's `reason` and every line in `notes` to `.decision-log.md`. With `"on"` and no usable store key that line is `NOTE recall-store-unset`, naming the key, and Finalize's run report repeats it. With either knob, a `NOTE recall-latch-visible` line says git can still see the latch (git already tracks it, or the exclude file could not be written), so it reads as a change to preflight's `git_clean` check: carry it into the run report too, and leave the fix to the person, since untracking the latch is a change the run never makes. A red latch with recall `"on"` and no NOTE (its `reason` is `store-unwritable: ...` or `no-fingerprint`) is logged by that `reason`, which Finalize's run report repeats too. A latch call that exits non-zero writes no latch: log what it printed and go on with recall off. A latch another run left behind is replaced by this command and only by it: never delete the file, which the guard refuses while a latch is present.
73
73
 
74
74
  While the latch is present the guard denies every claude-mem call, and every tool call that names the store or would change the latch other than these two scripts; reading the latch stays allowed. If the guard denies a call, do not route it another way and do not try to remove the latch: the deny names the latch and says what the person, not the run, should do about it.
75
75
 
@@ -206,7 +206,7 @@ Do these in order; each must be asserted, not assumed:
206
206
  - `ULTRACODE_TEST_ARTIFACTS=<the resolved TEA test-artifacts root>` — deliberately **not** a `{workflow.…}` scalar: no such workflow key exists, and a `{workflow.test_artifacts}` placeholder would never be filled by config resolution. Inject the same root TEA config resolution yields (`scripts/preflight_check.py`, `_tea_artifacts_root`): the tea-config `test_artifacts` value with `{project-root}` substituted (a relative value resolves under the project root), defaulting to `{project-root}/_bmad-output/test-artifacts` when tea config names none. This is the directory the guard reads the story's `atdd-checklist-<story-id>.md` from; leave it unset and the un-skip proof below is out of scope and silently enforces nothing.
207
207
  - The same PreToolUse guard also enforces the Cross-Session Recall latch from `{workflow.implementation_artifacts}/.mem-state.json`: the merged hook reads it automatically, fail-closed, with no new env var to inject. While a latch is present, whatever its version or colour, it denies every claude-mem call; every tool call that names the recall store, except the two pinned recall scripts (`scripts/mem_recall.py` and `scripts/mem_observation.py` under `uv run` or python); and every tool call that would change the latch itself, except those same scripts. Reading the latch stays allowed. **It enforces nothing unless the matcher above covers every tool**, because most of what it denies is a file-tool or MCP call, and a group matched on `Bash` is never invoked for one. This is the invariant that makes the all-tools matcher load-bearing rather than tidy.
208
208
  - **Un-skip proof (production only).** With `ULTRACODE_TEST_ARTIFACTS` injected, the guard reads the **staged post-image** of every acceptance-test file the story's `atdd-checklist-<story-id>.md` enumerates (`git show :<path>`) and denies the commit while any of them still contains `test.skip(`. It proves the marker is absent from the blob being committed, so it fires on a story's *first* commit too, where there is no prior blob to diff against. Caveat worth stating plainly: **`test.skip(` is a JS/Vitest-specific token** (the Playwright/Vitest form TEA's ATDD generates today, which is web/JS-only) — a pytest (`@pytest.mark.skip`) or Go (`t.Skip()`) stack marks skips differently and this check would not see them. Under `--light` there is no atdd-checklist, so the check stays inert.
209
- - **The commit/push guard anchors on each segment's leading token (`fp-7ac2643`).** The guard splits the command into shell segments and flags one only when `git` is that segment's **leading** token, once leading `VAR=val` assignments, shell keywords and group openers (`if`/`then`/`else`/`fi`, `for`/`while`/`until`/`do`/`done`, `case`/`esac`, `!`, and `(`/`{`, whether spaced or glued to the command name), and known exec wrappers (`env`, `command`, `sudo`, `time`, `nice`, `nohup`, `timeout`, `setsid`, `stdbuf`, `ionice`, `doas`, plus the string payload of a `sh|bash|zsh|dash` invoked with any `-c`-bearing flag cluster, `-lc` and `-cx` included) are stripped, and the subcommand it would then run is exactly `commit` or `push`, or a git alias that runs one (a subcommand that is not one of git's own commands is looked up as an alias in git's configuration, and one the guard cannot resolve counts as both verbs). The keyword strip is what keeps a commit inside a compound command (`if true; then git commit …; fi`, `for … do git commit … done`, `( git commit … )`) reachable by the gates: without it a keyword sits in the leading position, the segment classifies as carrying no git write, and the protected-branch, tests-ran, freshness and empty-index gates are all skipped at once. Segment splitting covers `&&`, `||`, `;`, `|`, a newline, **and a lone `&`** (`npm run build & git commit …` is two segments, not one); those separator sets are applied as a **union** rather than merged into one regex, because splitting on `&` or a newline is quote-blind and a lone set would tear `git -c alias.x='a&b' commit` into fragments that each escape detection. So a verb merely *mentioned* inside an `echo`, a log line, or a here-string in a verification command is no longer denied, while a real `FOO=bar git commit`, `sudo git commit` or `timeout 30 git commit` still is: on a `{workflow.protected_branches}` branch both verbs are denied, and on the epic branch, before the story's `.tests-ran-<story_id>` marker exists, a real `git commit` is denied (the marker gate is commit-only: a real `git push` is never marker-gated). Residual, stated rather than hidden: a wrapper **not** on that list (`xargs git commit`, say) leaves a non-`git` leading token and is allowed through, so the tests-ran marker and the remote's branch protection are the nets behind this one. Three shapes still take the older matches-anywhere path and deny on a mention: a segment whose quoting cannot be parsed, one that hides its command inside a `$(…)` substitution or backticks, and, the newest, a **listed** shell wrapper (`sh|bash|zsh|dash`) whose command-string payload cannot be located at all, meaning no `-c`-bearing flag cluster with an operand after it, or nesting deeper than the shell-recursion cap. That third lane exists because locating the payload by the bare token `-c` alone missed every combined form (`bash -lc`, `sh -lc`, `bash -cx`, `zsh -ic`), and a wrapper whose payload went unread classified as carrying no git write and skipped all four commit gates. It is fail-closed in the same direction as the other two, and it has the same cost: `bash <script> "…git commit…"` now denies on the mention, so a verification command's own arguments must not spell a write verb. **Do not read the anchoring as having eliminated the false-positive class: it narrowed it, and the remainder bites prose about commits in particular.** Markdown prose names identifiers in backticks, and an apostrophe (`don't`) is unbalanced quoting, so a run-log line describing a commit denial routinely hits both fallbacks; a line that *leads* with the verb is a real verb-leading segment and denies on its own. The rule that avoids all of it: **write prose with Write/Edit, never a Bash heredoc.** The guard's git gates read **Bash command strings alone**, so a decision-log append made with the file tools reaches none of them and no phrasing of the log can trip a gate. Now that the group is armed for every tool, the hook IS invoked for a `Write`, and it does decide on file tools, but only through its Cross-Session Recall rules: it denies a file-tool call that names the recall store or would change the run latch, and a decision-log append is neither, so it passes. Do not narrow the matcher back to `Bash` on the strength of this clause: that would leave those rules enforcing nothing. Reserve Bash for commands you actually mean to run. (execute.md step 4 covers the narrower marker-written-in-the-same-compound-command trap.)
209
+ - **The commit/push guard anchors on each segment's leading token (`fp-7ac2643`).** The guard splits the command into shell segments and flags one only when `git` is that segment's **leading** token, once leading `VAR=val` assignments, shell keywords and group openers (`if`/`then`/`else`/`fi`, `for`/`while`/`until`/`do`/`done`, `case`/`esac`, `!`, and `(`/`{`, whether spaced or glued to the command name), and known exec wrappers (`env`, `command`, `sudo`, `time`, `nice`, `nohup`, `timeout`, `setsid`, `stdbuf`, `ionice`, `doas`, plus the string payload of a `sh|bash|zsh|dash` invoked with any `-c`-bearing flag cluster, `-lc` and `-cx` included) are stripped, and the subcommand it would then run is exactly `commit` or `push`, or any subcommand that is not one of git's built-in commands (spelled as git spells them), which counts as both, since what an alias runs, or whether an external `git-<name>` command shadows it, cannot be read from the command: so a git alias, even a read-only one (an alias `st` for `status`), and an external command run through git meet the commit and push gates, and the deny says to run the git command an alias stands for, or the external command by its own name. The keyword strip is what keeps a commit inside a compound command (`if true; then git commit …; fi`, `for … do git commit … done`, `( git commit … )`) reachable by the gates: without it a keyword sits in the leading position, the segment classifies as carrying no git write, and the protected-branch, tests-ran, freshness and empty-index gates are all skipped at once. Segment splitting covers `&&`, `||`, `;`, `|`, a newline, **and a lone `&`** (`npm run build & git commit …` is two segments, not one); those separator sets are applied as a **union** rather than merged into one regex, because splitting on `&` or a newline is quote-blind and a lone set would tear `git -c alias.x='a&b' commit` into fragments that each escape detection. So a verb merely *mentioned* inside an `echo`, a log line, or a here-string in a verification command is no longer denied, while a real `FOO=bar git commit`, `sudo git commit` or `timeout 30 git commit` still is: on a `{workflow.protected_branches}` branch both verbs are denied, and on the epic branch, before the story's `.tests-ran-<story_id>` marker exists, a real `git commit` is denied (the marker gate is commit-only: a real `git push` is never marker-gated). Residual, stated rather than hidden: a wrapper **not** on that list (`xargs git commit`, say) leaves a non-`git` leading token and is allowed through, so the tests-ran marker and the remote's branch protection are the nets behind this one. Three shapes still take the older matches-anywhere path and deny on a mention: a segment whose quoting cannot be parsed, one that hides its command inside a `$(…)` substitution or backticks, and, the newest, a **listed** shell wrapper (`sh|bash|zsh|dash`) whose command-string payload cannot be located at all, meaning no `-c`-bearing flag cluster with an operand after it, or nesting deeper than the shell-recursion cap. That third lane exists because locating the payload by the bare token `-c` alone missed every combined form (`bash -lc`, `sh -lc`, `bash -cx`, `zsh -ic`), and a wrapper whose payload went unread classified as carrying no git write and skipped all four commit gates. It is fail-closed in the same direction as the other two, and it has the same cost: `bash <script> "…git commit…"` now denies on the mention, so a verification command's own arguments must not spell a write verb. **Do not read the anchoring as having eliminated the false-positive class: it narrowed it, and the remainder bites prose about commits in particular.** Markdown prose names identifiers in backticks, and an apostrophe (`don't`) is unbalanced quoting, so a run-log line describing a commit denial routinely hits both fallbacks; a line that *leads* with the verb is a real verb-leading segment and denies on its own, and so does a line that leads with `git` and a word that is not one of git's commands. The rule that avoids all of it: **write prose with Write/Edit, never a Bash heredoc.** The guard's git gates read **Bash command strings alone**, so a decision-log append made with the file tools reaches none of them and no phrasing of the log can trip a gate. Now that the group is armed for every tool, the hook IS invoked for a `Write`, and it does decide on file tools, but only through its Cross-Session Recall rules: it denies a file-tool call that names the recall store or would change the run latch, and a decision-log append is neither, so it passes. Do not narrow the matcher back to `Bash` on the strength of this clause: that would leave those rules enforcing nothing. Reserve Bash for commands you actually mean to run. (execute.md step 4 covers the narrower marker-written-in-the-same-compound-command trap.)
210
210
  - **Allowlist.** Pre-populate the tool allowlist with `{workflow.allowlist_commands}` so the unattended run can run tests/lint/build/commit without a permission prompt that no one is there to approve. Write one `Bash(<entry>:*)` allow rule per entry, with the entry exactly as it stands (`Bash(git worktree:*)` for `git worktree`). That rule matches the entry alone, or the entry, a space and anything after it, which is how `git worktree` covers the gate's `git worktree add <tmp-path> <commit>`. A rule without `:*` matches one exact command, so the stage's own calls would stop for approval. The entries land in the same `settings.local.json`, so a refused write here follows the same rule.
211
211
 
212
212
  ### Launch briefing (interactive only)
@@ -33,8 +33,7 @@ staged path exactly, or be a directory holding one: `README.md` does not match
33
33
  a staged `docs/README.md` when a root `README.md` exists, and below the top
34
34
  level it does not match the top level's `README.md` when the project root
35
35
  holds one. On a filesystem that ignores case (Windows, macOS by default), the
36
- match is against the path as the work tree spells it, so `Src/Guard.py` names
37
- a staged `src/guard.py`. A named path that exists nowhere matches by its trailing segments
36
+ match ignores case too, so `Src/Guard.py` names a staged `src/guard.py`. A named path that exists nowhere matches by its trailing segments
38
37
  or as a directory anywhere in a staged path, so `guard.py` or `hooks/` still
39
38
  match `src/hooks/guard.py`.
40
39
 
@@ -186,30 +185,34 @@ def _project_relative(staged: list[str], prefix: str) -> list[str]:
186
185
  return [path[len(prefix) :] for path in staged if path.startswith(prefix)]
187
186
 
188
187
 
189
- def _true_case(bare: str, project_root: Path) -> str:
190
- """`bare` spelled as the work tree spells it, one segment at a time.
188
+ def _ignores_case(path: Path, project_root: Path) -> bool:
189
+ """Whether the filesystem holding `path`, which exists, ignores case.
191
190
 
192
- On a case-insensitive filesystem (Windows, and macOS by default) a text
193
- can name `Src/Guard.py` for the `src/guard.py` git stages, and exists()
194
- says yes to both. An exact entry wins at each segment, so a case-sensitive
195
- tree, where only the exact spelling exists, reads as it did. A segment with
196
- no entry, or with two that differ only in case, leaves `bare` as it was.
191
+ True when the same path with one segment's case swapped is the same file,
192
+ as on Windows and on macOS by default. The last segment below the project
193
+ root that holds a letter is swapped (`docs` for `docs/2024`); the root and
194
+ the folders above it, which can sit on another filesystem, are never
195
+ probed. A path with no such segment, or one that cannot be checked, reads
196
+ as case-sensitive, which keeps the exact match.
197
197
  """
198
- current = project_root
199
- parts: list[str] = []
200
- for part in bare.split("/"):
198
+ root = project_root.resolve()
199
+ try:
200
+ path = path.resolve()
201
+ except (OSError, RuntimeError):
202
+ return False
203
+ if not path.is_relative_to(root):
204
+ return False # `../x` names a path outside the project
205
+ for current in (path, *path.parents):
206
+ if current == root:
207
+ return False
208
+ swapped = current.name.swapcase()
209
+ if swapped == current.name:
210
+ continue
201
211
  try:
202
- names = os.listdir(current)
203
- except OSError:
204
- return bare
205
- if part not in names:
206
- folded = [name for name in names if name.casefold() == part.casefold()]
207
- if len(folded) != 1:
208
- return bare
209
- part = folded[0]
210
- parts.append(part)
211
- current = current / part
212
- return "/".join(parts)
212
+ return os.path.samefile(current, current.with_name(swapped))
213
+ except (OSError, ValueError):
214
+ return False
215
+ return False
213
216
 
214
217
 
215
218
  def _matches(named: str, staged: list[str], project_root: Path, prefix: str = "") -> bool:
@@ -218,10 +221,17 @@ def _matches(named: str, staged: list[str], project_root: Path, prefix: str = ""
218
221
  if any(path == bare or path.startswith(bare + "/") for path in local):
219
222
  return True
220
223
  if _known(bare, project_root, set(local)):
221
- # It names a real path: only that path, or a file under it, will do,
222
- # as the work tree spells it.
223
- real = _true_case(bare, project_root)
224
- return real != bare and any(path == real or path.startswith(real + "/") for path in local)
224
+ # It names a real path: only that path, or a file under it, will do.
225
+ # Where the filesystem ignores case, any spelling of it does, the work
226
+ # tree's and the index's alike (they differ after a case-only rename
227
+ # made without `git mv`).
228
+ full = project_root / bare
229
+ if not (full.exists() and _ignores_case(full, project_root)):
230
+ return False
231
+ folded = bare.casefold()
232
+ return any(
233
+ path.casefold() == folded or path.casefold().startswith(folded + "/") for path in local
234
+ )
225
235
  if prefix and any(path == bare or path.startswith(bare + "/") for path in staged):
226
236
  # Named from the top level (`app/src/a.py`).
227
237
  return True
@@ -145,7 +145,8 @@ def _allow() -> NoReturn:
145
145
  sys.exit(0)
146
146
 
147
147
 
148
- def _deny(reason: str) -> NoReturn:
148
+ def _deny(reason: str, hint: str = "") -> NoReturn:
149
+ reason += hint
149
150
  print(
150
151
  json.dumps(
151
152
  {
@@ -287,8 +288,8 @@ def _current_story(impl: Path | None) -> str | None:
287
288
  # keeps a verb merely MENTIONED (inside an `echo`, a log line, a here-string)
288
289
  # from being read as a real commit; matching the verb by exact token equality is
289
290
  # what keeps `git commit-tree`-style near-misses out, which a trailing `\b`
290
- # never did (`-` is itself a word boundary). A subcommand that is a git alias
291
- # counts as what the alias runs (_alias_write_verbs).
291
+ # never did (`-` is itself a word boundary). A subcommand that is not one git
292
+ # runs before any alias counts as both verbs (_unknown_subcommand_verbs).
292
293
 
293
294
  _WRITE_VERBS = frozenset({"commit", "push"})
294
295
 
@@ -317,6 +318,8 @@ _EXEC_WRAPPERS = frozenset(
317
318
  "stdbuf",
318
319
  "ionice",
319
320
  "doas",
321
+ "exec",
322
+ "builtin",
320
323
  }
321
324
  )
322
325
 
@@ -359,6 +362,10 @@ _SHELL_KEYWORDS = frozenset(
359
362
  # of their own.
360
363
  _GROUP_OPENERS = "({"
361
364
 
365
+ # A redirection operator, with its descriptor, at the start of a word; what
366
+ # follows it in the same word is its target.
367
+ _REDIRECTION = re.compile(r"^\d*(?:&>>|&>|>>|>&|>\||<<<|<<-|<<|<>|<&|>|<)")
368
+
362
369
  # Global `git` options taking a SEPARATE value. The value must be skipped along
363
370
  # with the option, or `git -C <path> commit` would read <path> as the
364
371
  # subcommand and wave a real commit through.
@@ -372,6 +379,8 @@ _GIT_VALUE_OPTIONS = frozenset(
372
379
  "--exec-path",
373
380
  "--config-env",
374
381
  "--super-prefix",
382
+ "--attr-source",
383
+ "--shallow-file",
375
384
  }
376
385
  )
377
386
 
@@ -382,7 +391,9 @@ _ASSIGNMENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")
382
391
  _SUBSTITUTION_MARKERS = ("$(", "`", "<(")
383
392
 
384
393
  # Depth cap on `sh -c` recursion: a bound, not a behavior anyone should rely on.
394
+ # Past it, a `git` the guard cannot read deeper counts as both verbs.
385
395
  _MAX_SHELL_DEPTH = 4
396
+ _GIT_WORD = re.compile(r"\bgit\b")
386
397
 
387
398
  # A short-option cluster that carries `-c`, whose operand is the command string.
388
399
  # Matching only the bare `-c` token was a fail-open: every real combined form
@@ -396,53 +407,77 @@ _MAX_SHELL_DEPTH = 4
396
407
  _PAYLOAD_FLAG = re.compile(r"^-[A-Za-z]*c[A-Za-z]*$")
397
408
 
398
409
 
399
- # --- git aliases ------------------------------------------------------------
400
- # `git ci` runs `git commit` when `alias.ci = commit`, so a git subcommand that
401
- # is not a write verb is looked up as an alias before its segment is cleared.
402
- # Git ignores an alias named like one of its own commands, so a name on this
403
- # list is never looked up. Only real git commands belong on it: a name that is
404
- # not one could still be an alias, and listing it would wave that alias through.
410
+ # --- git subcommands that are not git's own --------------------------------
411
+ # `git ci` runs `git commit` when `alias.ci = commit`, and nothing in the
412
+ # command says what an alias runs: git reads it from configuration the command
413
+ # can change before git starts. Whether `git <name>` is an external
414
+ # `git-<name>` command instead depends on PATH, which can differ between this
415
+ # hook and the shell that runs the command, or change inside it. So the guard
416
+ # reads neither. A git subcommand counts as no write only when it is one of
417
+ # git's built-in commands, which git runs before any alias and which nothing
418
+ # can move or shadow, spelled as git spells it (git matches its command names
419
+ # case-sensitively, so `git LOG` runs `alias.log`), or one of the commands git
420
+ # ships as scripts in its exec-path, while the command does not mention that
421
+ # path. Every other subcommand (an alias, an external command such as `git
422
+ # lfs`, a typo) counts as both verbs, so the commit and push gates judge it,
423
+ # and the deny names it (_unknown_hint). A built-in whose job is to run another
424
+ # git subcommand stays off the list (`for-each-repo`). Only commands built in on every
425
+ # supported build belong on the first list: none newer than Git 2.30, and no
426
+ # `whatchanged`, which Git 3.0 drops. A test checks both lists on both CI legs.
405
427
  _GIT_COMMANDS = frozenset(
406
428
  {
407
429
  "add", "am", "annotate", "apply", "archive", "bisect", "blame",
408
- "branch", "bundle", "cat-file", "check-attr", "check-ignore",
409
- "check-mailmap", "check-ref-format", "checkout", "checkout-index",
410
- "cherry", "cherry-pick", "clean", "clone", "column", "commit-graph",
411
- "commit-tree", "config", "count-objects", "credential", "describe",
412
- "diff", "diff-files", "diff-index", "diff-tree", "difftool", "fetch",
413
- "fetch-pack", "fmt-merge-msg", "for-each-ref", "format-patch", "fsck",
414
- "gc", "grep", "hash-object", "help", "index-pack", "init",
415
- "interpret-trailers", "log", "ls-files", "ls-remote", "ls-tree",
416
- "mailinfo", "mailsplit", "merge", "merge-base", "merge-file",
417
- "merge-tree", "mergetool", "mktag", "mktree", "mv", "name-rev",
418
- "notes", "pack-objects", "pack-refs", "prune", "pull", "range-diff",
419
- "read-tree", "rebase", "reflog", "remote", "repack", "replace",
420
- "rerere", "reset", "restore", "rev-list", "rev-parse", "revert", "rm",
421
- "send-pack", "shortlog", "show", "show-branch", "show-ref",
422
- "sparse-checkout", "stash", "status", "stripspace", "submodule",
423
- "switch", "symbolic-ref", "tag", "unpack-objects", "update-index",
424
- "update-ref", "update-server-info", "var", "verify-commit",
425
- "verify-pack", "verify-tag", "version", "whatchanged", "worktree",
430
+ "branch", "bugreport", "bundle", "cat-file", "check-attr",
431
+ "check-ignore", "check-mailmap", "check-ref-format", "checkout",
432
+ "checkout-index", "cherry", "cherry-pick", "clean", "clone", "column",
433
+ "commit-graph", "commit-tree", "config", "count-objects", "credential",
434
+ "describe", "diff", "diff-files", "diff-index", "diff-tree",
435
+ "difftool", "fast-export", "fast-import", "fetch", "fetch-pack",
436
+ "fmt-merge-msg", "for-each-ref", "format-patch",
437
+ "fsck", "gc", "grep", "hash-object", "help", "index-pack", "init",
438
+ "init-db", "interpret-trailers", "log", "ls-files", "ls-remote",
439
+ "ls-tree", "mailinfo", "mailsplit", "maintenance", "merge",
440
+ "merge-base", "merge-file", "merge-index", "merge-tree", "mktag",
441
+ "mktree", "multi-pack-index", "mv", "name-rev", "notes",
442
+ "pack-objects", "pack-refs", "patch-id", "prune", "prune-packed",
443
+ "pull", "range-diff", "read-tree", "rebase", "receive-pack", "reflog",
444
+ "remote", "repack", "replace", "rerere", "reset", "restore",
445
+ "rev-list", "rev-parse", "revert", "rm", "send-pack", "shortlog",
446
+ "show", "show-branch", "show-index", "show-ref", "sparse-checkout",
447
+ "stage", "stash", "status", "stripspace", "switch", "symbolic-ref",
448
+ "tag", "unpack-objects", "update-index", "update-ref",
449
+ "update-server-info", "upload-archive", "upload-pack", "var",
450
+ "verify-commit", "verify-pack", "verify-tag", "version", "worktree",
426
451
  "write-tree",
427
452
  }
428
453
  )
429
-
430
- # What a git subcommand the guard cannot resolve counts as: both verbs, so the
454
+ # Commands git ships as scripts in its exec-path, which it also runs before an
455
+ # alias of the name, unless the command moves that path (`--exec-path`,
456
+ # `GIT_EXEC_PATH`): a mention of it anywhere in the command, a nested shell's
457
+ # included, makes them count as both verbs too.
458
+ _GIT_SCRIPT_COMMANDS = frozenset({"filter-branch", "mergetool", "quiltimport", "request-pull", "submodule"})
459
+ _EXEC_PATH_TEXT = re.compile(r"exec[-_]path", re.IGNORECASE)
460
+
461
+ # What a git subcommand that is not git's own counts as: both verbs, so the
431
462
  # commit and push gates judge it, which is where the doubt belongs.
432
463
  _UNRESOLVED_VERBS = frozenset(_WRITE_VERBS)
433
464
 
434
- # A command that defines an alias (`git config alias.ci commit; git ci`,
435
- # `git -c alias.ci=commit ci`) or sets git's configuration through the
436
- # environment (`GIT_CONFIG_GLOBAL=<file> git ci`) can run an alias that the
437
- # configuration on disk does not show when the guard looks.
438
- _CONFIG_IN_COMMAND = re.compile(r"(?i:alias\.)|\bGIT_[A-Z0-9_]*=")
465
+ # A subcommand the deny's hint may quote: the shape of a command or alias name,
466
+ # so a fragment torn from a quoted argument never reaches the reason.
467
+ _NAME_SHAPE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
439
468
 
440
469
 
441
- class _AliasScope(NamedTuple):
442
- """Where a git alias is looked up, and whether the command makes that moot."""
470
+ class _CommandScope:
471
+ """What classifying one command collects and reuses along the way."""
443
472
 
444
- cwd: str | None
445
- unsure: bool
473
+ def __init__(self, command: str = "") -> None:
474
+ self.moves_exec_path = bool(_EXEC_PATH_TEXT.search(command))
475
+ # The subcommands counted as both verbs, in the order first met.
476
+ self.unknown: dict[str, None] = {}
477
+ # Each substitution body's verbs at a depth, so the four readings of a
478
+ # command, and their own readings of a nested body, classify it once
479
+ # there (a body met at the depth cap is read more shallowly elsewhere).
480
+ self.bodies: dict[tuple[str, int], set[str]] = {}
446
481
 
447
482
 
448
483
  def _tokenize(segment: str) -> list[str]:
@@ -462,8 +497,8 @@ def _strip_assignments(tokens: list[str]) -> list[str]:
462
497
  return tokens[index:]
463
498
 
464
499
 
465
- def _git_subcommand(tokens: list[str]) -> str | None:
466
- """The subcommand `git` would run, given the tokens that follow `git`."""
500
+ def _git_subcommand_index(tokens: list[str]) -> int | None:
501
+ """Where the subcommand `git` would run sits among the tokens after `git`."""
467
502
  index = 0
468
503
  while index < len(tokens):
469
504
  token = tokens[index]
@@ -473,76 +508,262 @@ def _git_subcommand(tokens: list[str]) -> str | None:
473
508
  if token.startswith("-"):
474
509
  index += 1
475
510
  continue
476
- return token.lower()
511
+ return index
477
512
  return None
478
513
 
479
514
 
480
- @functools.lru_cache(maxsize=32)
481
- def _git_alias(name: str, cwd: str | None) -> tuple[bool, str | None]:
482
- """`alias.<name>` as (answered, value); (True, None) when there is no alias.
515
+ def _unknown_subcommand_verbs(name: str, scope: _CommandScope | None) -> set[str]:
516
+ """Both verbs for `git <name> ...` when `name` is not one of git's own commands.
483
517
 
484
- `git config --get` exits 1 for a key that is not set (an invalid key name
485
- included, which cannot be an alias either). Any other outcome, a timeout
486
- or git missing among them, is not an answer, and the caller fails closed.
487
- Cached because each command is classified under three separator sets.
488
- """
489
- try:
490
- out = subprocess.run(
491
- ["git", "config", "--get", f"alias.{name}"],
492
- cwd=cwd or None,
493
- capture_output=True,
494
- text=True,
495
- errors="replace",
496
- timeout=10,
497
- )
498
- except (OSError, subprocess.SubprocessError):
499
- return False, None
500
- if out.returncode == 0:
501
- return True, out.stdout.rstrip("\r\n")
502
- if out.returncode == 1:
503
- return True, None
504
- return False, None
505
-
506
-
507
- def _alias_write_verbs(
508
- args: list[str], verb: str | None, depth: int, scope: _AliasScope | None
509
- ) -> set[str]:
510
- """The write verbs `git <args>` runs when its subcommand is an alias.
511
-
512
- Empty for a git command of its own, and for a name that is no alias (an
513
- external `git-<name>` command, or a typo git will refuse). An alias to
514
- another git command is classified as that command, alias chains included;
515
- a `!` alias as the shell command it runs, read both by segment and by the
516
- matches-anywhere scan, since a shell alias is often a function definition
517
- (`!f() { git commit "$@"; }; f`) whose segments lead with no `git`. Doubt
518
- resolves to both verbs: an option ahead of the subcommand (`-C`, `-c`,
519
- `--git-dir` can each change which configuration git reads), a command that
520
- itself defines an alias or sets git configuration (_CONFIG_IN_COMMAND), a
521
- lookup that does not answer, and a chain past the recursion cap.
518
+ Empty for a built-in command (_GIT_COMMANDS) and, while the command does
519
+ not mention git's exec-path, for one git ships as a script there
520
+ (_GIT_SCRIPT_COMMANDS). Anything else counts as both verbs and is recorded
521
+ on the scope, when it has a name's shape, for the deny's hint.
522
522
  """
523
- if verb is None or verb in _GIT_COMMANDS:
523
+ if name in _GIT_COMMANDS:
524
524
  return set()
525
- scope = scope or _AliasScope(None, False)
526
- if scope.unsure or args[0].lower() != verb or depth >= _MAX_SHELL_DEPTH:
527
- return set(_UNRESOLVED_VERBS)
528
- answered, value = _git_alias(verb, scope.cwd)
529
- if not answered:
530
- return set(_UNRESOLVED_VERBS)
531
- if value is None:
525
+ if name in _GIT_SCRIPT_COMMANDS and not (scope and scope.moves_exec_path):
532
526
  return set()
533
- if value.startswith("!"):
534
- body = value[1:]
535
- return _command_write_verbs(body, depth + 1, scope) | _anywhere_write_verbs(body)
527
+ if scope is not None and _NAME_SHAPE.match(name):
528
+ scope.unknown.setdefault(name, None)
529
+ return set(_UNRESOLVED_VERBS)
530
+
531
+
532
+ def _substitution_bodies(text: str) -> list[str]:
533
+ """The commands inside each `$(...)`, `<(...)`, `>(...)` and backtick pair.
534
+
535
+ Text in single quotes is skipped, since the shell substitutes nothing
536
+ there (`echo 'run `git ci` later'`), and so is a backslash-escaped
537
+ character; double quotes do not stop a substitution. Parentheses are
538
+ counted, not parsed, and a heredoc is read as plain text: a body that comes
539
+ out wrong is classified anyway, which can only add verbs.
540
+ """
541
+ bodies: list[str] = []
542
+ index = 0
543
+ in_double = False
544
+ while index < len(text):
545
+ char = text[index]
546
+ if char == "\\":
547
+ index += 2
548
+ elif char == "'" and not in_double:
549
+ end = text.find("'", index + 1)
550
+ index = len(text) if end == -1 else end + 1
551
+ elif char == '"':
552
+ in_double = not in_double
553
+ index += 1
554
+ elif text.startswith(("$(", "<(", ">("), index):
555
+ start = index = index + 2
556
+ level = 1
557
+ while index < len(text) and level:
558
+ if text[index] == "(":
559
+ level += 1
560
+ elif text[index] == ")":
561
+ level -= 1
562
+ index += 1
563
+ bodies.append(text[start : index - 1 if level == 0 else index])
564
+ elif char == "`":
565
+ end = text.find("`", index + 1)
566
+ end = len(text) if end == -1 else end
567
+ bodies.append(text[index + 1 : end])
568
+ index = end + 1
569
+ else:
570
+ index += 1
571
+ return bodies
572
+
573
+
574
+ # shlex's punctuation mode yields a run of these characters as one token (a
575
+ # newline is one of them, so it ends a segment as it does in bash). The run is
576
+ # split into bash's own operators, longest first: a control operator ends a
577
+ # segment (`;`, `&&`, `|&`, a newline, the `()` of a function definition, a
578
+ # process substitution's `<(` or `>(`, so `true;>(git commit)` reads its
579
+ # body), and a redirection (`>&`, `>|`, `<<`) stays in the segment it opens,
580
+ # where _strip_leading_noise reads it.
581
+ _PUNCTUATION = "();<>|&\n"
582
+ _OPERATORS = (
583
+ ";;&", "&>>", "<<<", "<<-", ";;", ";&", "&&", "||", "|&", "&>", ">>", ">&",
584
+ "<&", ">|", "<>", "<<", "<(", ">(", ";", "&", "|", "<", ">", "(", ")", "\n",
585
+ ) # fmt: skip
586
+ _CONTROL_OPERATORS = frozenset(
587
+ {";;&", ";;", ";&", "&&", "||", "|&", ";", "&", "|", "(", ")", "\n", "<(", ">("}
588
+ )
589
+
590
+
591
+ # Punctuation inside quotes, or escaped, is a word's text, not an operator, but
592
+ # shlex hands a quoted `')>'` back as `)>`, which reads as one. So it is masked
593
+ # before lexing, with a quote scan that follows shlex's own posix rules (a
594
+ # backslash escapes outside single quotes; single quotes take everything up to
595
+ # the next one; double quotes take an escaped character as it is), and unmasked
596
+ # in the tokens after.
597
+ _MASK_BASE = 0xE000
598
+
599
+
600
+ def _mask_quoted(text: str) -> str:
601
+ """`text` with each punctuation character inside quotes or escaped masked.
602
+
603
+ Unbalanced quotes leave the text as it is, for shlex to refuse.
604
+ """
605
+ out: list[str] = []
606
+ index = 0
607
+ size = len(text)
608
+
609
+ def masked(char: str) -> str:
610
+ return chr(_MASK_BASE + ord(char)) if char in _PUNCTUATION else char
611
+
612
+ while index < size:
613
+ char = text[index]
614
+ if char == "\\" and index + 1 < size:
615
+ out.append(char + masked(text[index + 1]))
616
+ index += 2
617
+ elif char == "'":
618
+ end = text.find("'", index + 1)
619
+ if end == -1:
620
+ return text
621
+ out.append("'" + "".join(masked(c) for c in text[index + 1 : end]) + "'")
622
+ index = end + 1
623
+ elif char == '"':
624
+ end = index + 1
625
+ body: list[str] = []
626
+ while end < size and text[end] != '"':
627
+ if text[end] == "\\" and end + 1 < size:
628
+ body.append(text[end] + masked(text[end + 1]))
629
+ end += 2
630
+ else:
631
+ body.append(masked(text[end]))
632
+ end += 1
633
+ if end >= size:
634
+ return text
635
+ out.append('"' + "".join(body) + '"')
636
+ index = end + 1
637
+ else:
638
+ out.append(char)
639
+ index += 1
640
+ return "".join(out)
641
+
642
+
643
+ def _unmask(token: str) -> str:
644
+ return "".join(
645
+ chr(ord(c) - _MASK_BASE) if _MASK_BASE <= ord(c) < _MASK_BASE + 128 else c for c in token
646
+ )
647
+
648
+
649
+ def _operators(token: str) -> list[str] | None:
650
+ """A run of punctuation as bash's operators, longest first; None for a word."""
651
+ if not token or not set(token) <= set(_PUNCTUATION):
652
+ return None
653
+ found: list[str] = []
654
+ index = 0
655
+ while index < len(token):
656
+ operator = next(op for op in _OPERATORS if token.startswith(op, index))
657
+ found.append(operator)
658
+ index += len(operator)
659
+ return found
660
+
661
+ # A heredoc's start, with its delimiter, quoted or not.
662
+ _HEREDOC_START = re.compile(r"<<-?[ \t]*(['\"]?)([A-Za-z_][A-Za-z0-9_]*)\1")
663
+
664
+
665
+ def _lexable(command: str) -> str:
666
+ """The command with what shlex reads unlike bash taken out, for a reading
667
+ of its own.
668
+
669
+ A comment (a `#` that starts a word, outside quotes, up to its line's end),
670
+ an ANSI-C string `$'...'`, whose backslash escapes shlex does not know and
671
+ in which nothing is substituted (it becomes an empty word), and a heredoc's
672
+ body (the lines up to its delimiter, which may hold any text, apostrophes
673
+ included). The rest is copied as it is, quotes and escapes included, for
674
+ shlex to read. Its reading of comments and heredocs is rough (a `#` after
675
+ `$(...)`, a `<<` in arithmetic), and a misread takes out text bash runs, so
676
+ this text is only ever read beside the command as it is
677
+ (_command_write_verbs): it can add a reading, never replace one.
678
+ """
679
+ out: list[str] = []
680
+ pending: list[str] = [] # heredoc delimiters whose bodies start at the next newline
681
+ index = 0
682
+ size = len(command)
683
+ word_start = True
684
+ while index < size:
685
+ char = command[index]
686
+ if char == "\\":
687
+ out.append(command[index : index + 2])
688
+ index += 2
689
+ word_start = False
690
+ elif command.startswith("$'", index):
691
+ end = index + 2
692
+ while end < size and command[end] != "'":
693
+ end += 2 if command[end] == "\\" else 1
694
+ out.append("''")
695
+ index = end + 1
696
+ word_start = False
697
+ elif char in "'\"":
698
+ end = index + 1
699
+ while end < size and command[end] != char:
700
+ end += 2 if char == '"' and command[end] == "\\" else 1
701
+ out.append(command[index : end + 1])
702
+ index = end + 1
703
+ word_start = False
704
+ elif char == "#" and word_start:
705
+ end = command.find("\n", index)
706
+ index = size if end == -1 else end
707
+ elif command.startswith("<<", index) and not command.startswith("<<<", index):
708
+ match = _HEREDOC_START.match(command, index)
709
+ if match:
710
+ pending.append(match.group(2))
711
+ out.append(command[index : match.end()])
712
+ index = match.end()
713
+ else:
714
+ out.append("<<")
715
+ index += 2
716
+ word_start = False
717
+ elif char == "\n":
718
+ out.append("\n")
719
+ index += 1
720
+ word_start = True
721
+ for delimiter in pending:
722
+ while index < size:
723
+ end = command.find("\n", index)
724
+ line = command[index : size if end == -1 else end]
725
+ index = size if end == -1 else end + 1
726
+ if line.lstrip("\t") == delimiter:
727
+ break
728
+ pending.clear()
729
+ else:
730
+ out.append(char)
731
+ index += 1
732
+ word_start = char in " \t;&|()<>"
733
+ return "".join(out)
734
+
735
+
736
+ def _quoted_segments(command: str) -> list[list[str]]:
737
+ """The command's segments as quote-aware tokens, or none when it cannot be read.
738
+
739
+ The quote-blind splits in _command_write_verbs tear a quoted `;`, `&&` or
740
+ `|` apart (`git ci -m 'fix: a; b'`), and each fragment then tokenizes to
741
+ nothing. shlex in punctuation mode keeps it inside its word.
742
+ """
743
+ lexer = shlex.shlex(_mask_quoted(command), posix=True, punctuation_chars=_PUNCTUATION)
744
+ lexer.whitespace = " \t\r" # a newline is punctuation, so it ends a segment
745
+ lexer.whitespace_split = True
746
+ lexer.commenters = "" # shlex would start one mid-word; bash does not
536
747
  try:
537
- expansion = _tokenize(value)
748
+ tokens = list(lexer)
538
749
  except ValueError:
539
- return _anywhere_write_verbs(f"git {value}")
540
- verbs = _token_write_verbs(["git", *expansion, *args[1:]], depth + 1, scope)
541
- return set(_UNRESOLVED_VERBS) if verbs is None else verbs
750
+ return []
751
+ segments: list[list[str]] = [[]]
752
+ for token in tokens:
753
+ operators = _operators(token)
754
+ if operators is None:
755
+ segments[-1].append(_unmask(token))
756
+ continue
757
+ for operator in operators:
758
+ if operator in _CONTROL_OPERATORS:
759
+ segments.append([])
760
+ else:
761
+ segments[-1].append(operator)
762
+ return [segment for segment in segments if segment]
542
763
 
543
764
 
544
765
  def _shell_payload_verbs(
545
- tokens: list[str], depth: int, scope: _AliasScope | None = None
766
+ tokens: list[str], depth: int, scope: _CommandScope | None = None
546
767
  ) -> set[str] | None:
547
768
  """Verbs written by the string payload of a `sh -c '…'`-style invocation.
548
769
 
@@ -556,8 +777,10 @@ def _shell_payload_verbs(
556
777
  """
557
778
  if depth >= _MAX_SHELL_DEPTH:
558
779
  # The cap is a recursion bound, not a verdict: refusing to look deeper
559
- # is exactly the "cannot read it" case, so it fails closed too.
560
- return None
780
+ # is exactly the "cannot read it" case, so it fails closed too, and a
781
+ # `git` in what it cannot read counts as both verbs (the
782
+ # matches-anywhere scan knows only the literal verbs, not an alias).
783
+ return set(_UNRESOLVED_VERBS) if any(_GIT_WORD.search(t) for t in tokens) else None
561
784
  for index, token in enumerate(tokens):
562
785
  if _PAYLOAD_FLAG.match(token) and index + 1 < len(tokens):
563
786
  return _command_write_verbs(tokens[index + 1], depth + 1, scope)
@@ -565,30 +788,49 @@ def _shell_payload_verbs(
565
788
 
566
789
 
567
790
  def _strip_leading_noise(tokens: list[str]) -> list[str]:
568
- """Drop leading `VAR=val` assignments, shell keywords and group openers.
791
+ """Drop leading `VAR=val` assignments, shell keywords, group openers and
792
+ redirections.
569
793
 
570
794
  Applied repeatedly because they nest: `if ! FOO=1 git commit …` puts three
571
- different kinds of noise ahead of the verb. Every strip here can only turn
572
- an unclassifiable segment into a classifiable one, so this direction is
573
- fail-closed by construction.
795
+ different kinds of noise ahead of the verb. A name after `function`, or
796
+ after `coproc` ahead of a group, names the function, not a command; a
797
+ redirection ahead of the command (`>/dev/null git commit`, `2>&1 git
798
+ commit`, `> out git commit`) is no command either. Every strip here can
799
+ only turn an unclassifiable segment into a classifiable one, so this
800
+ direction is fail-closed by construction.
574
801
  """
575
802
  while True:
576
803
  stripped = _strip_assignments(tokens)
577
804
  if stripped:
578
805
  head = stripped[0]
579
806
  bare = head.lstrip(_GROUP_OPENERS)
807
+ redirect = _REDIRECTION.match(head)
580
808
  if bare != head:
581
809
  # `(git commit …)` — opener glued to the command name.
582
810
  stripped = ([bare] + stripped[1:]) if bare else stripped[1:]
811
+ elif head == "function" and len(stripped) > 1:
812
+ stripped = stripped[2:]
813
+ elif head == "coproc" and len(stripped) > 2 and stripped[2] in ("{", "("):
814
+ stripped = stripped[2:]
583
815
  elif head.lower() in _SHELL_KEYWORDS:
584
816
  stripped = stripped[1:]
817
+ elif redirect:
818
+ # An operator alone (`>`, `2>&`) takes the next word as its
819
+ # target, unless that word is `git`: a quoted punctuation word
820
+ # (`exec -a ')>' git ci`) reads as an operator here, and the
821
+ # git after it must not be taken for its target.
822
+ alone = redirect.end() == len(head)
823
+ target_is_git = alone and len(stripped) > 1 and os.path.basename(stripped[1]).lower() == "git"
824
+ stripped = stripped[2:] if alone and not target_is_git else stripped[1:]
825
+ elif head.isdigit() and len(stripped) > 1 and _REDIRECTION.match(stripped[1]):
826
+ stripped = stripped[1:] # the descriptor of `2 >&1`, split by the quote-aware reading
585
827
  if stripped == tokens:
586
828
  return stripped
587
829
  tokens = stripped
588
830
 
589
831
 
590
832
  def _token_write_verbs(
591
- tokens: list[str], depth: int, scope: _AliasScope | None = None
833
+ tokens: list[str], depth: int, scope: _CommandScope | None = None
592
834
  ) -> set[str] | None:
593
835
  """Classify one tokenized segment: which write verbs would it actually run?
594
836
 
@@ -600,12 +842,21 @@ def _token_write_verbs(
600
842
  return set()
601
843
  head = os.path.basename(tokens[0]).lower()
602
844
  if head == "git":
603
- verb = _git_subcommand(tokens[1:])
604
- if verb in _WRITE_VERBS:
605
- return {verb}
606
- return _alias_write_verbs(tokens[1:], verb, depth, scope)
845
+ index = _git_subcommand_index(tokens[1:])
846
+ if index is None:
847
+ return set()
848
+ if tokens[1 + index].lower() in _WRITE_VERBS:
849
+ return {tokens[1 + index].lower()}
850
+ return _unknown_subcommand_verbs(tokens[1 + index], scope)
607
851
  if head in _SHELL_WRAPPERS:
608
852
  return _shell_payload_verbs(tokens[1:], depth, scope)
853
+ if head == "eval":
854
+ # `eval` runs its arguments, joined, as a command of its own, after a
855
+ # `--` it skips.
856
+ if depth >= _MAX_SHELL_DEPTH:
857
+ return set(_UNRESOLVED_VERBS) if any(_GIT_WORD.search(t) for t in tokens) else None
858
+ args = tokens[2:] if tokens[1:2] == ["--"] else tokens[1:]
859
+ return _command_write_verbs(" ".join(args), depth + 1, scope)
609
860
  if head in _EXEC_WRAPPERS:
610
861
  # Every wrapper has its own option grammar (`timeout 30 …`, `nice -n 10
611
862
  # …`, `sudo -u u …`, `stdbuf -oL …`), and modelling them one by one is
@@ -615,7 +866,7 @@ def _token_write_verbs(
615
866
  # parsing the wrapper.
616
867
  for index in range(1, len(tokens)):
617
868
  name = os.path.basename(tokens[index]).lower()
618
- if name == "git" or name in _SHELL_WRAPPERS or name in _EXEC_WRAPPERS:
869
+ if name in ("git", "eval") or name in _SHELL_WRAPPERS or name in _EXEC_WRAPPERS:
619
870
  return _token_write_verbs(tokens[index:], depth, scope)
620
871
  return set()
621
872
 
@@ -626,29 +877,82 @@ def _anywhere_write_verbs(segment: str) -> set[str]:
626
877
  return {match.group("verb").lower()} if match else set()
627
878
 
628
879
 
629
- def _segment_write_verbs(segment: str, depth: int, scope: _AliasScope | None = None) -> set[str]:
880
+ def _body_verbs(segment: str, depth: int, scope: _CommandScope | None) -> set[str]:
881
+ """The write verbs of each substitution body in the segment, each read as a
882
+ command of its own, once per body and depth; past the depth cap, both verbs
883
+ for a `git` the guard cannot read deeper."""
884
+ if depth >= _MAX_SHELL_DEPTH:
885
+ return set(_UNRESOLVED_VERBS) if _GIT_WORD.search(segment) else set()
886
+ verbs: set[str] = set()
887
+ for body in _substitution_bodies(segment):
888
+ if scope is None:
889
+ verbs |= _command_write_verbs(body, depth + 1, scope)
890
+ continue
891
+ key = (body, depth)
892
+ if key not in scope.bodies:
893
+ scope.bodies[key] = set() # a body that holds itself stops here
894
+ scope.bodies[key] = _command_write_verbs(body, depth + 1, scope)
895
+ verbs |= scope.bodies[key]
896
+ return verbs
897
+
898
+
899
+ def _without_comments(segment: str) -> str:
900
+ """The segment with its line continuations joined and each line's trailing
901
+ `#` comment, and a trailing backslash, taken out. Read quote-blind, so it
902
+ can cut a quoted `#` too: it is only ever an extra reading."""
903
+ lines = segment.replace("\\\n", " ").split("\n")
904
+ return "\n".join(re.sub(r"(^|\s)#.*$", r"\1", line) for line in lines).rstrip().rstrip("\\")
905
+
906
+
907
+ def _uncommented_verbs(segment: str, depth: int, scope: _CommandScope | None) -> set[str]:
908
+ """The verbs of the segment read without its comments, when it does not
909
+ tokenize as it is: an apostrophe in a trailing comment (`git ci # it's`)
910
+ leaves no tokens, and the matches-anywhere scan knows no alias."""
911
+ stripped = _without_comments(segment)
912
+ if stripped == segment:
913
+ return set()
914
+ try:
915
+ tokens = _tokenize(stripped)
916
+ except ValueError:
917
+ return set()
918
+ return _token_write_verbs(tokens, depth, scope) or set()
919
+
920
+
921
+ def _segment_write_verbs(segment: str, depth: int, scope: _CommandScope | None = None) -> set[str]:
630
922
  if any(marker in segment for marker in _SUBSTITUTION_MARKERS):
631
923
  # The real command hides inside the substitution; anchoring would read
632
- # the outer word and allow it. Fall back rather than fail open.
633
- return _anywhere_write_verbs(segment)
924
+ # the outer word and allow it. Fall back rather than fail open. Each
925
+ # substitution's body is classified as a command of its own, and the
926
+ # outer words too where they tokenize, so a git alias inside one
927
+ # (`echo "$(git ci)"`) or around one (`git ci -m "$(date)"`) is seen.
928
+ verbs = _anywhere_write_verbs(segment) | _body_verbs(segment, depth, scope)
929
+ try:
930
+ tokens = _tokenize(segment)
931
+ except ValueError:
932
+ return verbs | _uncommented_verbs(segment, depth, scope)
933
+ return verbs | (_token_write_verbs(tokens, depth, scope) or set())
934
+ # An output process substitution's body is a command too. It is read on its
935
+ # own, not through the matches-anywhere scan, which would deny a read whose
936
+ # words name a verb (`git log --grep=push > >(cat)`).
937
+ verbs = _body_verbs(segment, depth, scope) if ">(" in segment else set()
634
938
  try:
635
939
  tokens = _tokenize(segment)
636
940
  except ValueError:
637
941
  # Unbalanced quotes: there are no trustworthy tokens, so fall back to
638
- # the legacy scan rather than wave the segment through. Letting the
639
- # exception escape would exit non-zero, which is neither a clean allow
640
- # nor a clean deny.
641
- return _anywhere_write_verbs(segment)
642
- verbs = _token_write_verbs(tokens, depth, scope)
643
- if verbs is None:
942
+ # the legacy scan rather than wave the segment through, and read the
943
+ # segment once more without its comments. Letting the exception escape
944
+ # would exit non-zero, which is neither a clean allow nor a clean deny.
945
+ return verbs | _anywhere_write_verbs(segment) | _uncommented_verbs(segment, depth, scope)
946
+ found = _token_write_verbs(tokens, depth, scope)
947
+ if found is None:
644
948
  # A listed shell wrapper whose payload could not be located. Same
645
949
  # treatment as the two lanes above: scan the raw segment rather than
646
950
  # let an unreadable invocation classify as carrying no write.
647
- return _anywhere_write_verbs(segment)
648
- return verbs
951
+ return verbs | _anywhere_write_verbs(segment)
952
+ return verbs | found
649
953
 
650
954
 
651
- def _command_write_verbs(command: str, depth: int, scope: _AliasScope | None = None) -> set[str]:
955
+ def _command_write_verbs(command: str, depth: int, scope: _CommandScope | None = None) -> set[str]:
652
956
  verbs: set[str] = set()
653
957
  # Classified under BOTH separator sets, unioned. Neither alone is safe:
654
958
  #
@@ -691,18 +995,51 @@ def _command_write_verbs(command: str, depth: int, scope: _AliasScope | None = N
691
995
  ):
692
996
  for segment in re.split(separators, command):
693
997
  verbs |= _segment_write_verbs(segment, depth, scope)
998
+ # Quote-aware readings join the union: they keep a quoted separator inside
999
+ # its word (`git ci -m 'fix: a; b'`), which the three quote-blind splits
1000
+ # tear into fragments that classify as nothing, and like them they can
1001
+ # only add verbs. One reads the command as it is; the other reads it with
1002
+ # what shlex cannot lex taken out (_lexable: a comment holding an
1003
+ # apostrophe, `$'...'`, a heredoc body), and adds to the first, never
1004
+ # replaces it. A text shlex cannot read adds none.
1005
+ lexable = _lexable(command)
1006
+ for text in (command,) if lexable == command else (command, lexable):
1007
+ for tokens in _quoted_segments(text):
1008
+ verbs |= _token_write_verbs(tokens, depth, scope) or set()
694
1009
  return verbs
695
1010
 
696
1011
 
697
- def _git_writes(command: str, cwd: str | None = None) -> set[str]:
1012
+ def _classify(command: str) -> tuple[set[str], list[str]]:
1013
+ """The {'commit','push'} subset the command would perform, and the git
1014
+ subcommands that are not git's own it counted as both, for the git gates'
1015
+ deny hint (_unknown_hint)."""
1016
+ scope = _CommandScope(command)
1017
+ return _command_write_verbs(command, 0, scope), list(scope.unknown)
1018
+
1019
+
1020
+ def _git_writes(command: str) -> set[str]:
698
1021
  """Return the {'commit','push'} subset the command would perform.
699
1022
 
700
1023
  Classifies each shell segment independently, so a chained
701
- `git add && git commit` is still caught. A git alias is looked up in
702
- `cwd`'s configuration (_alias_write_verbs).
1024
+ `git add && git commit` is still caught. A git subcommand that is not one
1025
+ of git's own counts as both (_unknown_subcommand_verbs).
703
1026
  """
704
- scope = _AliasScope(cwd, bool(_CONFIG_IN_COMMAND.search(command)))
705
- return _command_write_verbs(command, 0, scope)
1027
+ return _classify(command)[0]
1028
+
1029
+
1030
+ def _unknown_hint(names: list[str]) -> str:
1031
+ """The note a git gate's deny adds when the command runs a subcommand that
1032
+ is not git's own: it may be why the command was denied, and what to do."""
1033
+ if not names:
1034
+ return ""
1035
+ shown = ", ".join(f"`git {name}`" for name in names[:3])
1036
+ return (
1037
+ f" Note: this command runs {shown}, which is not one of git's built-in "
1038
+ "commands, so this guard counts it as a commit and a push: it cannot tell "
1039
+ "what an alias runs. If that is why it was denied, run the git command an "
1040
+ "alias stands for, or an external command by its own name (`git-lfs pull` "
1041
+ "for `git lfs pull`)."
1042
+ )
706
1043
 
707
1044
 
708
1045
  # --- Marker freshness -------------------------------------------------------
@@ -2225,9 +2562,10 @@ def main() -> None:
2225
2562
  if not isinstance(command, str):
2226
2563
  _allow()
2227
2564
 
2228
- verbs = _git_writes(command, cwd)
2565
+ verbs, unknown = _classify(command)
2229
2566
  if not verbs:
2230
2567
  _allow()
2568
+ hint = _unknown_hint(unknown)
2231
2569
 
2232
2570
  protected = _protected_branches()
2233
2571
  branch = _current_branch(cwd)
@@ -2237,7 +2575,8 @@ def main() -> None:
2237
2575
  f"Protected-branch guard: refusing `git {'/'.join(sorted(verbs))}` "
2238
2576
  f"on '{branch}'. UltraCode-Goal commits one green story per commit "
2239
2577
  f"on an epic branch ('{os.environ.get('ULTRACODE_EPIC_BRANCH_PREFIX', 'ultracode/epic-')}<id>'), "
2240
- f"never on {protected}. Switch to the epic branch first."
2578
+ f"never on {protected}. Switch to the epic branch first.",
2579
+ hint,
2241
2580
  )
2242
2581
 
2243
2582
  if "commit" in verbs:
@@ -2253,7 +2592,8 @@ def main() -> None:
2253
2592
  "Tests-ran guard: refusing `git commit` — no tests-ran marker "
2254
2593
  f"for the current story ({story or 'unknown'}). Run the story's "
2255
2594
  f"test/lint/build to green and write {target} before committing. "
2256
- "Commit only at a verified-green story boundary."
2595
+ "Commit only at a verified-green story boundary.",
2596
+ hint,
2257
2597
  )
2258
2598
  _marker_freshness_gate(marker, baseline)
2259
2599
  if not _staged_index_nonempty(cwd):
@@ -2265,7 +2605,8 @@ def main() -> None:
2265
2605
  "distinct tool call. `git commit -a` and commit-time pathspecs "
2266
2606
  "are unsupported inside a story loop: the guard evaluates the "
2267
2607
  "command string before it runs, so anything they would stage "
2268
- "does not exist yet at that point."
2608
+ "does not exist yet at that point.",
2609
+ hint,
2269
2610
  )
2270
2611
  _unskip_gate(cwd, story)
2271
2612
 
@@ -119,19 +119,27 @@ def utc_now_iso() -> str:
119
119
  _SCHEME_RE = re.compile(r"^[a-zA-Z][a-zA-Z0-9+.\-]*://")
120
120
 
121
121
 
122
- def _git(cwd: Path, *args: str) -> tuple[int, str]:
123
- """Run git in cwd, returning (returncode, stdout-stripped). Never raises."""
122
+ def _git(cwd: Path, *args: str, strip: bool = True, errors: str = "replace") -> tuple[int, str]:
123
+ """Run git in cwd, returning (returncode, stdout). Never raises.
124
+
125
+ The output is stripped; with ``strip=False`` only its line ending goes, so
126
+ a leading space in a path it prints survives. It is read as UTF-8, as git
127
+ prints paths, not in the locale's encoding (a Windows code page would turn
128
+ `été` into another name); ``errors="surrogateescape"`` keeps the bytes of
129
+ a name that is not UTF-8, so it can be written back as git printed it.
130
+ """
124
131
  try:
125
132
  proc = subprocess.run(
126
133
  ["git", *args],
127
134
  cwd=str(cwd),
128
135
  capture_output=True,
129
- text=True,
136
+ encoding="utf-8",
137
+ errors=errors,
130
138
  check=False,
131
139
  )
132
140
  except (OSError, ValueError):
133
141
  return 1, ""
134
- return proc.returncode, proc.stdout.strip()
142
+ return proc.returncode, (proc.stdout.strip() if strip else proc.stdout.rstrip("\r\n"))
135
143
 
136
144
 
137
145
  def normalize_remote(url: str) -> str:
@@ -399,28 +407,48 @@ def write_state(impl_artifacts: str | os.PathLike[str], state: dict) -> Path:
399
407
  return path
400
408
 
401
409
 
402
- # The line exclude_state() adds to the repository's .git/info/exclude. It
403
- # matches the latch and the temporary file write_state() renames into it, so
404
- # neither shows in `git status` on a tracked artifacts folder (where the latch
405
- # would trip preflight's git_clean blocker on every run) and a `git add -A`
406
- # never stages them (the latch committed, then a tracked deletion once
407
- # unlatch removes it).
408
- STATE_EXCLUDE_PATTERN = ".mem-state*"
410
+ # The latch's line in the repository's .git/info/exclude, which
411
+ # exclude_state() adds: the latch's file name with a `*`, so it matches the
412
+ # latch and the temporary file write_state() renames into it, anchored to the
413
+ # artifacts folder so no other file of that name is hidden. Neither then shows
414
+ # in `git status` on a tracked artifacts folder (where the latch would trip
415
+ # preflight's git_clean blocker on every run), and a `git add -A` never stages
416
+ # them (the latch committed, then a tracked deletion once unlatch removes it).
417
+ _STATE_EXCLUDE_NAME = ".mem-state*"
409
418
  _STATE_EXCLUDE_COMMENT = "# UltraCode Goal run latch (mem_recall.py latch)"
419
+ # The unanchored line 3.0.0-rc.1 wrote under the same comment, which hid every
420
+ # `.mem-state*` file in the repository; exclude_state() replaces it.
421
+ _STATE_EXCLUDE_UNANCHORED = _STATE_EXCLUDE_NAME
422
+ # The characters an ignore pattern reads as a glob or an escape.
423
+ _IGNORE_SPECIAL = re.compile(r"([\\*?\[])")
424
+
425
+
426
+ def state_exclude_line(prefix: str) -> str:
427
+ """The exclude line for a latch whose folder sits at ``prefix`` in the work tree.
428
+
429
+ ``prefix`` is ``git rev-parse --show-prefix`` run in the artifacts folder:
430
+ its path from the work tree's top, with a trailing ``/``, or ``""`` at the
431
+ top itself. Glob characters in it are escaped, so a folder named
432
+ ``art[1]`` matches only itself.
433
+ """
434
+ return "/" + _IGNORE_SPECIAL.sub(r"\\\1", prefix) + _STATE_EXCLUDE_NAME
410
435
 
411
436
 
412
437
  def exclude_state(impl_artifacts: str | os.PathLike[str]) -> list[str]:
413
438
  """Keep the latch out of git; return the notes to print (none when it is out).
414
439
 
415
- Adds STATE_EXCLUDE_PATTERN to the exclude file of the repository holding
440
+ Adds state_exclude_line() to the exclude file of the repository holding
416
441
  ``impl_artifacts`` (``git rev-parse --git-path info/exclude``, so a linked
417
- worktree writes its main repository's file), once: a pattern already there
418
- is left alone. A folder git does not see (no repository, or outside the
419
- work tree) needs nothing and gets nothing. Exclusion cannot hide a latch
442
+ worktree writes its main repository's file), once: a line already there
443
+ is left alone, and the unanchored line 3.0.0-rc.1 wrote under the same
444
+ comment is removed. A folder git does not see (no repository, or outside
445
+ the work tree) needs nothing and gets nothing. Exclusion cannot hide a latch
420
446
  git already tracks, as a run on an older release could commit it: that one
421
447
  gets ``NOTE recall-latch-visible``, since untracking it is a change to the
422
- repository for the person to make. An exclude file that cannot be read or
423
- written gets the same note with its error. Never raises.
448
+ repository for the person to make, from their own terminal once no run is
449
+ active (while a latch is present the guard denies a command that names it).
450
+ An exclude file that cannot be read or written gets the same note with its
451
+ error. Never raises.
424
452
  """
425
453
  impl = Path(impl_artifacts)
426
454
  code, inside = _git(impl, "rev-parse", "--is-inside-work-tree")
@@ -432,24 +460,43 @@ def exclude_state(impl_artifacts: str | os.PathLike[str]) -> list[str]:
432
460
  if code == 0 and tracked:
433
461
  notes.append(
434
462
  f"{NOTE_RECALL_LATCH_VISIBLE}: git tracks the run latch {latch}, so it shows "
435
- "as a change in every run; untrack it once by hand with "
436
- f"`git rm --cached {latch}` and commit that"
463
+ "as a change in every run; once no run is active, untrack it from a "
464
+ f"terminal of your own with `git rm --cached {latch}` and commit that "
465
+ "(while a latch is present, the guard denies a command that names it)"
437
466
  )
467
+ # Unstripped: a strip() would drop a leading space from the folder name.
468
+ # The folder's bytes as git printed them, even where they are not UTF-8.
469
+ code, prefix = _git(impl, "rev-parse", "--show-prefix", strip=False, errors="surrogateescape")
470
+ if code != 0:
471
+ return notes
472
+ line = state_exclude_line(prefix)
438
473
  code, rel = _git(impl, "rev-parse", "--git-path", "info/exclude")
439
474
  if code != 0 or not rel:
440
475
  return notes
441
476
  exclude = Path(rel) if os.path.isabs(rel) else impl / rel
442
477
  try:
443
- text = exclude.read_text(encoding="utf-8") if exclude.is_file() else ""
444
- if STATE_EXCLUDE_PATTERN in text.splitlines():
478
+ text = exclude.read_text(encoding="utf-8", errors="surrogateescape") if exclude.is_file() else ""
479
+ lines = text.splitlines()
480
+ kept: list[str] = []
481
+ for entry in lines:
482
+ if entry == _STATE_EXCLUDE_UNANCHORED and kept and kept[-1] == _STATE_EXCLUDE_COMMENT:
483
+ kept.pop() # 3.0.0-rc.1's line, and its comment
484
+ continue
485
+ kept.append(entry)
486
+ if kept != lines:
487
+ if line not in kept:
488
+ kept += [_STATE_EXCLUDE_COMMENT, line]
489
+ exclude.write_text("\n".join(kept) + "\n", encoding="utf-8", errors="surrogateescape")
490
+ return notes
491
+ if line in lines:
445
492
  return notes
446
493
  lead = "" if not text or text.endswith("\n") else "\n"
447
494
  exclude.parent.mkdir(parents=True, exist_ok=True)
448
- with open(exclude, "a", encoding="utf-8") as handle:
449
- handle.write(f"{lead}{_STATE_EXCLUDE_COMMENT}\n{STATE_EXCLUDE_PATTERN}\n")
495
+ with open(exclude, "a", encoding="utf-8", errors="surrogateescape") as handle:
496
+ handle.write(f"{lead}{_STATE_EXCLUDE_COMMENT}\n{line}\n")
450
497
  except (OSError, ValueError) as exc: # ValueError: not UTF-8
451
498
  notes.append(
452
- f"{NOTE_RECALL_LATCH_VISIBLE}: could not add {STATE_EXCLUDE_PATTERN} to "
499
+ f"{NOTE_RECALL_LATCH_VISIBLE}: could not add {line} to "
453
500
  f"{exclude} ({exc}), so git can see the run latch {latch}"
454
501
  )
455
502
  return notes
@@ -15,12 +15,19 @@ drive_epic's default mode would have it refused. This script runs under
15
15
 
16
16
  Which folders. Every `node_modules` folder in the main tree, the root's and
17
17
  the nested ones (a workspace package's), but never one inside another
18
- `node_modules`: linking the outer one carries it. The walk skips `.git`, the
19
- worktree itself and any other gate worktree (`.gate-worktree-*`), which live
20
- under the implementation artifacts folder inside the main tree. `--dir` names
21
- a folder to link instead, relative to the project root, for a dependency
22
- folder of another name (`vendor`); repeat it for several. Given any `--dir`,
23
- nothing is discovered.
18
+ `node_modules`: linking the outer one carries it. The walk does not enter
19
+ `.git`, `__pycache__`, a repository or worktree nested in the tree (a folder
20
+ holding a `.git`: the gate worktrees under the implementation artifacts
21
+ folder, an agent worktree, a submodule, whose files the gate's worktree does
22
+ not check out), a Python virtual environment
23
+ (a folder holding `pyvenv.cfg`) or a cache folder (one holding `CACHEDIR.TAG`,
24
+ such as Cargo's `target`). None holds the project's own dependencies, and some
25
+ are large. A folder is judged by what it holds, not by its name, so a
26
+ workspace package named `target` or a JavaScript action under `.github/` is
27
+ still walked.
28
+ `--dir` names a folder to link instead, relative to the project root, for a
29
+ dependency folder of another name (`vendor`); repeat it for several. Given
30
+ any `--dir`, nothing is discovered.
24
31
 
25
32
  How each link is made. A directory symlink to the main tree's folder, at the
26
33
  same relative path in the worktree. On Windows, where a symlink needs a
@@ -48,26 +55,31 @@ import sys
48
55
  from pathlib import Path
49
56
 
50
57
  DEPENDENCY_DIR = "node_modules"
51
- _GATE_WORKTREE_PREFIX = ".gate-worktree-"
58
+ # Folders the walk never enters, by name.
59
+ _UNWALKED = frozenset({".git", "__pycache__"})
60
+ # A folder holding one of these is another repository or worktree (`.git`), a
61
+ # Python virtual environment, or a cache (the Cache Directory Tagging spec).
62
+ _UNWALKED_MARKERS = frozenset({".git", "pyvenv.cfg", "CACHEDIR.TAG"})
52
63
 
53
64
 
54
- def discover(project_root: Path, worktree: Path) -> list[str]:
55
- """Every `node_modules` folder under project_root, outermost only, sorted."""
56
- skip = os.path.normcase(os.path.realpath(worktree))
65
+ def discover(project_root: Path) -> list[str]:
66
+ """Every `node_modules` folder under project_root, outermost only, sorted.
67
+
68
+ The gate's own worktree, like every git worktree, holds a `.git` file, so
69
+ the marker check skips it with the other nested trees.
70
+ """
57
71
  found: list[str] = []
58
- for current, dirs, _files in os.walk(project_root):
72
+ for current, dirs, files in os.walk(project_root):
73
+ if current != str(project_root) and any(
74
+ marker in dirs or marker in files for marker in _UNWALKED_MARKERS
75
+ ):
76
+ dirs[:] = [] # a nested repository or worktree, a virtual environment, a cache
77
+ continue
59
78
  kept = []
60
79
  for name in dirs:
61
- full = os.path.join(current, name)
62
80
  if name == DEPENDENCY_DIR:
63
- found.append(Path(os.path.relpath(full, project_root)).as_posix())
64
- elif (
65
- name == ".git"
66
- or name.startswith(_GATE_WORKTREE_PREFIX)
67
- or os.path.normcase(os.path.realpath(full)) == skip
68
- ):
69
- continue
70
- else:
81
+ found.append(Path(os.path.relpath(os.path.join(current, name), project_root)).as_posix())
82
+ elif name not in _UNWALKED:
71
83
  kept.append(name)
72
84
  dirs[:] = kept
73
85
  return sorted(found)
@@ -152,7 +164,7 @@ def main(argv: list[str] | None = None) -> int:
152
164
  return 2
153
165
  rel_dirs.append(rel)
154
166
  else:
155
- rel_dirs = discover(project_root, worktree)
167
+ rel_dirs = discover(project_root)
156
168
  result = link_all(project_root, worktree, rel_dirs)
157
169
  print(json.dumps(result, indent=2, ensure_ascii=False))
158
170
  return 1 if result["failed"] else 0