From 752da228861d0114052b49a378e13fc0b1d87fee Mon Sep 17 00:00:00 2001 From: Sal <59910950+ss-o@users.noreply.github.com> Date: Mon, 19 Oct 2026 01:35:39 +0100 Subject: [PATCH 1/3] docs(knowledge): record zsh scope, Pages and sub-issue branch rules Localizing path, PATH, cdpath, fpath or manpath empties the command hash table on return and forces a full PATH rescan; an EXIT trap set inside a function fires when that function returns. The zsh domain index names the policy validator tests, the CI index says static.yml publishes Pages (build_type workflow), and implementation branches are named after their repository sub-issue. The frozen consumer-parser digest is updated for the scripting instruction change (#588). --- .github/instructions/zsh/scripting.instructions.md | 11 ++++++++++- automation/ci/test_validate_zsh_standard_policy.py | 2 +- knowledge/domains/ci/index.md | 2 ++ knowledge/domains/governance/sub-issues.md | 2 ++ knowledge/domains/zsh/index.md | 2 ++ knowledge/domains/zsh/scripting.md | 11 ++++++++++- runbooks/sub-issues.md | 2 ++ 7 files changed, 29 insertions(+), 3 deletions(-) diff --git a/.github/instructions/zsh/scripting.instructions.md b/.github/instructions/zsh/scripting.instructions.md index d0f21f35a..faa1792d5 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. The same applies to `PATH`, +`cdpath`, `fpath` and `manpath`; 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..f60147e9a 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", + "2d2eb52a29b7ce849e9e318be48e4b492514084e145d6e02242df3214e632ec7", 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..8c52ba7a4 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` (about two minutes); the `ExternalConsumerTests` class alone takes about a second. diff --git a/knowledge/domains/zsh/scripting.md b/knowledge/domains/zsh/scripting.md index cc33c2cea..23648738f 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. The same applies to `PATH`, +`cdpath`, `fpath` and `manpath`; 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. From 5442fdc29beef84f44267bb77437c98d763cce8a Mon Sep 17 00:00:00 2001 From: Sal <59910950+ss-o@users.noreply.github.com> Date: Mon, 19 Oct 2026 01:53:58 +0100 Subject: [PATCH 2/3] docs(knowledge): limit the hash rescan note to path and PATH strace on zsh 5.9.2 shows a local path or PATH doubling the PATH directory scans (86 against 43 getdents64 calls), while a local fpath, cdpath or manpath does not rescan. The frozen consumer-parser digest follows the instruction change (#588). --- .github/instructions/zsh/scripting.instructions.md | 6 +++--- automation/ci/test_validate_zsh_standard_policy.py | 2 +- knowledge/domains/zsh/scripting.md | 6 +++--- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/instructions/zsh/scripting.instructions.md b/.github/instructions/zsh/scripting.instructions.md index faa1792d5..2ce8c2d6c 100644 --- a/.github/instructions/zsh/scripting.instructions.md +++ b/.github/instructions/zsh/scripting.instructions.md @@ -469,9 +469,9 @@ fail or change command lookup. Use purpose-specific names such as `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. The same applies to `PATH`, -`cdpath`, `fpath` and `manpath`; use names such as `dir`, `entry` or -`fpath_entry`. +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` diff --git a/automation/ci/test_validate_zsh_standard_policy.py b/automation/ci/test_validate_zsh_standard_policy.py index f60147e9a..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, - "2d2eb52a29b7ce849e9e318be48e4b492514084e145d6e02242df3214e632ec7", + "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/zsh/scripting.md b/knowledge/domains/zsh/scripting.md index 23648738f..cdfd8ab0b 100644 --- a/knowledge/domains/zsh/scripting.md +++ b/knowledge/domains/zsh/scripting.md @@ -465,9 +465,9 @@ fail or change command lookup. Use purpose-specific names such as `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. The same applies to `PATH`, -`cdpath`, `fpath` and `manpath`; use names such as `dir`, `entry` or -`fpath_entry`. +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` From ee32b0cebec888eab444f6b811480d811867d5a2 Mon Sep 17 00:00:00 2001 From: Sal <59910950+ss-o@users.noreply.github.com> Date: Mon, 19 Oct 2026 01:59:36 +0100 Subject: [PATCH 3/3] docs(knowledge): state the measured validator test time --- knowledge/domains/zsh/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/knowledge/domains/zsh/index.md b/knowledge/domains/zsh/index.md index 8c52ba7a4..5908149d4 100644 --- a/knowledge/domains/zsh/index.md +++ b/knowledge/domains/zsh/index.md @@ -18,4 +18,4 @@ 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` (about two minutes); the `ExternalConsumerTests` class alone takes about a second. +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.