diff --git a/.github/instructions/zsh/scripting.instructions.md b/.github/instructions/zsh/scripting.instructions.md index d0f21f35a..2ce8c2d6c 100644 --- a/.github/instructions/zsh/scripting.instructions.md +++ b/.github/instructions/zsh/scripting.instructions.md @@ -466,7 +466,12 @@ Do not repurpose a Zsh special parameter name for unrelated local or scratch data. Check the Special Parameters inventory before declaring a new name. For example, `status` is read-only, and `path` is tied to `PATH`; assignment can fail or change command lookup. Use purpose-specific names such as -`command_status` and `candidate_paths`. +`command_status` and `candidate_paths`. Even `local path` with no assignment +costs time: restoring the caller's value on return runs the `path` setter +again, which empties the command hash table, so the next command lookup or +completion rescans every `PATH` directory. `local PATH` does the same; +localizing `fpath`, `cdpath` or `manpath` does not rescan, but still changes +their lookups. Use names such as `dir`, `entry` or `fpath_entry`. ### `zsh/parameters/capture-before-localizing` @@ -747,6 +752,10 @@ value=$(critical_command) || exit - Enforcement: `runtime-test` Declare trap form and scope, and restore caller trap state where required. +An `EXIT` trap set inside a function, including an anonymous function, runs +when that function returns, not when the script exits. A cleanup trap meant +for a whole sourced file belongs at that file's top level; keep the setup +itself in an anonymous function with `emulate -L zsh`. ### `zsh/cleanup/use-always` diff --git a/automation/ci/test_validate_zsh_standard_policy.py b/automation/ci/test_validate_zsh_standard_policy.py index 09ff38237..b4f4ed9ff 100644 --- a/automation/ci/test_validate_zsh_standard_policy.py +++ b/automation/ci/test_validate_zsh_standard_policy.py @@ -1992,7 +1992,7 @@ def test_repair_2_consumer_parser_outputs_match_frozen_golden(self) -> None: self.assertEqual( digest, - "7e904244848331b7e2471354db7ccb4c8c0ab317c9a071d2ca0d05a0ed40edfb", + "02d1b1b2c86cd1d745ef348701876bf27086b3782daf3c93ddd594214e06fade", msg=( "The frozen golden covers the parsed output of every path in " f"{paths}. Editing any of them changes this digest, which is " diff --git a/knowledge/domains/ci/index.md b/knowledge/domains/ci/index.md index bc616d707..b52a2ef87 100644 --- a/knowledge/domains/ci/index.md +++ b/knowledge/domains/ci/index.md @@ -10,6 +10,8 @@ Select this domain for GitHub Actions authoring, review, workflow changes and sh | Audit scheduled organization automation | [Recurring operations](../governance/recurring-operations.md) | | Use maintained action documentation | [Setup Zsh](setup-zsh-action.md), [commit action](commit-action.md) and [rclone action](rclone-action.md); verify inherited examples against the actual action and current workflow contract | +This repository's GitHub Pages site uses `build_type: workflow`, so the `source` branch shown in its Pages settings is inert and `.github/workflows/static.yml` is what publishes it. + Role profiles are optional entrypoints. Required permissions, pinning, concurrency and verification come from the canonical contract and project checks. Use [quality](../quality/index.md) for test selection and [governance](../governance/index.md) for publication gates. For native packages, historical records, implementation and supporting files in this domain, use [repository resources](repository-resources.md). Each file has an imported source or retained-owner reference in the checked repository inventory. diff --git a/knowledge/domains/governance/sub-issues.md b/knowledge/domains/governance/sub-issues.md index 6d56850cd..2aae276f2 100644 --- a/knowledge/domains/governance/sub-issues.md +++ b/knowledge/domains/governance/sub-issues.md @@ -22,6 +22,8 @@ Add another level only when a separately owned outcome genuinely needs it. - Keep a parent and its sub-issues in the owning repository when the outcome is repository-local. - Keep each implementation sub-issue in the repository that owns its change. + File it before naming the implementation branch, and name the branch after + that sub-issue, never after the organization parent. - Apply `meta:initiative` to the parent only. Never apply it to a sub-issue. - Apply the normal work-type and area labels during triage. A cross-repository parent also qualifies for `meta:org-tracked` under the tracker policy. diff --git a/knowledge/domains/zsh/index.md b/knowledge/domains/zsh/index.md index 3f494891c..5908149d4 100644 --- a/knowledge/domains/zsh/index.md +++ b/knowledge/domains/zsh/index.md @@ -17,3 +17,5 @@ For native packages, historical records, implementation and supporting files in Structured policy owned by this domain: - [zsh-standard-policy.json](data/zsh-standard-policy.json) + +Test the policy validator with `cd automation/ci && python3 -m unittest test_validate_zsh_standard_policy` (111 tests, about 45 seconds on 2026-10-19); the `ExternalConsumerTests` class alone takes about a second. diff --git a/knowledge/domains/zsh/scripting.md b/knowledge/domains/zsh/scripting.md index cc33c2cea..cdfd8ab0b 100644 --- a/knowledge/domains/zsh/scripting.md +++ b/knowledge/domains/zsh/scripting.md @@ -462,7 +462,12 @@ Do not repurpose a Zsh special parameter name for unrelated local or scratch data. Check the Special Parameters inventory before declaring a new name. For example, `status` is read-only, and `path` is tied to `PATH`; assignment can fail or change command lookup. Use purpose-specific names such as -`command_status` and `candidate_paths`. +`command_status` and `candidate_paths`. Even `local path` with no assignment +costs time: restoring the caller's value on return runs the `path` setter +again, which empties the command hash table, so the next command lookup or +completion rescans every `PATH` directory. `local PATH` does the same; +localizing `fpath`, `cdpath` or `manpath` does not rescan, but still changes +their lookups. Use names such as `dir`, `entry` or `fpath_entry`. ### `zsh/parameters/capture-before-localizing` @@ -743,6 +748,10 @@ value=$(critical_command) || exit - Enforcement: `runtime-test` Declare trap form and scope, and restore caller trap state where required. +An `EXIT` trap set inside a function, including an anonymous function, runs +when that function returns, not when the script exits. A cleanup trap meant +for a whole sourced file belongs at that file's top level; keep the setup +itself in an anonymous function with `emulate -L zsh`. ### `zsh/cleanup/use-always` diff --git a/runbooks/sub-issues.md b/runbooks/sub-issues.md index e3e5902ee..625d51dc8 100644 --- a/runbooks/sub-issues.md +++ b/runbooks/sub-issues.md @@ -26,6 +26,8 @@ Add another level only when a separately owned outcome genuinely needs it. - Keep a parent and its sub-issues in the owning repository when the outcome is repository-local. - Keep each implementation sub-issue in the repository that owns its change. + File it before naming the implementation branch, and name the branch after + that sub-issue, never after the organization parent. - Apply `meta:initiative` to the parent only. Never apply it to a sub-issue. - Apply the normal work-type and area labels during triage. A cross-repository parent also qualifies for `meta:org-tracked` under the tracker policy.