docs(knowledge): record zsh scope, Pages and sub-issue branch rules

.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`
 

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 "

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.

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.

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.

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`
 

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.