[ss-o]

Summary

• Add the advisory Zsh syntax and AST reviewer role at knowledge/domains/zsh/roles/zsh-syntax-reviewer.md under ADR-0014 portable instruction delivery.
• Register its source-to-target mapping in knowledge/delivery.json, generate .github/agents/zsh-syntax-reviewer.agent.md, and route the optional surface for syntax, AST, dialect, parser-gap, rule-proposal and code reviews.
• Update the Zsh domain index and repository resource inventory.
• Use the canonical five execution profiles and function-scoped option isolation; explicitly reject setopt local_options at sourced top level as caller-state protection.

Refs #475 for the portable instruction architecture.

Instruction impact review

1. Classification: This is an optional advisory reviewer role, not a new mandatory policy or enforcement surface. The existing Zsh scripting standard and machine-readable policy own its language and profile contracts.
2. Consumers and contexts: GitHub Copilot custom-agent consumers receive .github/agents/zsh-syntax-reviewer.agent.md from this repository. Other runtimes may explicitly read the canonical role. No downstream installation or runtime invocation is claimed by the inventory.
3. Canonical owner: knowledge/domains/zsh/roles/zsh-syntax-reviewer.md owns the role, and knowledge/delivery.json maps its generated consumer. Organization policy remains in AGENTS.md and the canonical Zsh standard.
4. Duplication and contradictions: The role links the canonical standard and keeps its checklist advisory. The review corrections replace undefined execution profiles and the misleading top-level option-isolation advice. The plugin reviewer remains responsible for plugin-specific lifecycle compliance.
5. Manifest routes: Add agent-zsh-syntax-reviewer to .github/instruction-surfaces.json, its source-to-target mapping to knowledge/delivery.json, and its imported disposition to knowledge/repository-files.json. No downstream route changes are needed for this optional organization-hosted role.
6. Mandatory delivery: Mandatory rules continue through the existing baseline and routed Zsh guidance. This optional role is not the sole delivery path for any required rule. Live Copilot agent discovery and invocation remain unverified.
7. Generated output and limits: knowledge-delivery.py --check verifies all 57 consumers, knowledge-coverage.py verifies 362 files with zero unclassified files, and agent-policy validation passes the repository's inventory and size checks.

Verification

• python3 -B automation/knowledge/knowledge-delivery.py --check: passed, 57 consumers.
• python3 -B automation/knowledge/knowledge-coverage.py: passed, 362 files, zero unclassified.
• python3 -B automation/agents/validate-agent-policy.py: passed.
• python3 -B automation/agents/org-routing.py validate: passed.
• python3 -B automation/governance/decision-records.py --check: passed.
• python3 -B automation/ci/validate-zsh-standard-policy.py: passed.
• trunk check --no-fix --ci knowledge/domains/zsh/roles/zsh-syntax-reviewer.md: passed.
• git diff --check: passed.
• Zsh 5.9.2 runtime probe: sourced top-level local_options leaves sh_word_split enabled; an anonymous function beginning with builtin emulate -L zsh restores the caller's option state.
• Execution-profile comparison: the role lists exactly the five profiles declared by the canonical machine-readable policy.
• Live Copilot discovery and invocation: unverified.

Agent handoff

Both initial review findings are corrected and the published head 5d92e809 has been re-reviewed with no actionable findings. All 12 hosted checks pass, and the maintainer-elected fresh review of record is posted on that head. Merge remains a separate maintainer decision.

[ss-o]

Fallback review under ADR-0026: maintainer elected, no Copilot request on 7bbeaaf

Findings

No actionable findings.

Scope: Reviewed commit 7bbeaaf and complete diff (+254, -0 across 7 files) for PR #789.

Note

This is a maintainer-elected self-review, not an independent review or approval to merge.

Validation

• Passed:
  • python3 automation/knowledge/knowledge-delivery.py --check: verified 57 delivered consumers match source files byte-for-byte.
  • python3 automation/knowledge/knowledge-coverage.py: verified 362 files (57 imported, 305 referenced, 0 unclassified).
  • python3 automation/agents/validate-agent-policy.py: validated instruction surface metadata and schema conformance.
  • python3 automation/agents/org-routing.py validate: validated organization instruction surface routes and inventory.
  • python3 automation/governance/decision-records.py --check: verified decision records.
  • python3 automation/ci/validate-zsh-standard-policy.py: verified Zsh standard policy data.
  • git diff --check: verified clean whitespace and diff formatting.
  • Character set scan: verified zero U+2014 em dash characters across all created and modified files.
  • Hosted GitHub Actions checks: all 12 checks passed on head commit 7bbeaaf (Commit Lint, Agent Instruction Validation, Org Routing, Lychee, CodeQL).
• Skipped or unavailable:
  • Live hosted GitHub Copilot chat agent discovery in a browser/IDE UI remains unexercised locally as it requires a live Copilot chat session.

Checklist verdicts and supporting evidence

• Instruction architecture (ADR-0014): pass. The canonical role source lives under knowledge/domains/zsh/roles/, is declared in knowledge/delivery.json, generated via knowledge-delivery.py into .github/agents/zsh-syntax-reviewer.agent.md, and routed via .github/instruction-surfaces.json without modifying the root AGENTS.md or introducing vendor files.
• Surface routing and task mapping: pass. Surface agent-zsh-syntax-reviewer declares advisory authority, copilot consumer, and specific tasks (zsh-syntax-review, zsh-ast-review, zsh-dialect-review, zsh-lint-parser-gap, zsh-lint-rule-proposal, code-review).
• Domain coverage and catalog: pass. Registered in knowledge/repository-files.json as imported and referenced in knowledge/domains/zsh/index.md and repository-resources.md.
• Security and read-only invariants: pass. The role instructions explicitly require read-only auditing, evaluate syntax via zsh -f -n, forbid unreviewed eval, and mandate reporting without local modifications.

Limits and follow-up

• Hosted Copilot discovery requires interactive client evaluation.
• Staging and merge operations remain separately authorized.

[ss-o]

Fallback review under ADR-0026: maintainer elected, no Copilot request on 5d92e80

Findings

No actionable findings on the reviewed head. Both initial review findings are resolved: the role now selects the canonical five execution profiles and requires function-scoped option isolation while rejecting sourced top-level local_options as caller-state protection.

Scope: Re-reviewed the delta from 7bbeaaf6e32b80fdb89a01a144615e8f725e2f47 to 5d92e809, then checked the corrected role against its canonical contracts and delivery map. The full PR remains seven files, with 246 additions, against merge base eef8360a6defc1afe449b23169df33c817c7d2f6; the observed base tip is bb533df520010a19ce9cb780778001258dbc1cfc.

Note

This review includes corrections authored in the reviewing session. Merge authority remains a separate maintainer decision.

Checklist verdicts

• Profile classification: pass. The role's profile set exactly matches execution_profiles in knowledge/domains/zsh/data/zsh-standard-policy.json, including startup-file and test-fixture.
• State preservation: pass. The option check cites zsh/options/localize and zsh/options/no-top-level-leak, requires a function beginning with builtin emulate -L zsh for reusable work, and explicitly rejects top-level local_options as isolation. A Zsh 5.9.2 runtime probe confirmed that sourced top-level local_options leaks sh_word_split, while the localized anonymous function restores it. The released Zsh manual defines restoration at function return.
• Ownership and generated delivery: pass. The editable source remains under knowledge/domains/zsh/roles/; the delivered agent is regenerated through knowledge/delivery.json. All 57 consumers match their generated content, and the repository inventory covers all 362 files.
• Routing and scope: pass. The manifest declares an optional advisory Copilot surface and appropriate review task selectors. The role remains read-only and defers language authority to the canonical standard and released Zsh manual. No mandatory policy is delegated solely to this role.
• Documentation: pass. The domain index and imported resource record remain consistent with the delivery map. The PR description answers all seven instruction-impact questions and explicitly marks live discovery unverified.

Validation

• Passed: python3 -B automation/knowledge/knowledge-delivery.py --check, python3 -B automation/knowledge/knowledge-coverage.py, python3 -B automation/agents/validate-agent-policy.py, python3 -B automation/agents/org-routing.py validate, python3 -B automation/governance/decision-records.py --check, and python3 -B automation/ci/validate-zsh-standard-policy.py.
• Passed: source-only trunk check --no-fix --ci knowledge/domains/zsh/roles/zsh-syntax-reviewer.md, full merge-base git diff --check, execution-profile comparison, and local verification of the new commit's signature.
• Passed: all 12 hosted checks on 5d92e80930dc032be97448b6e002f8cb1502217f, covering Agent Instruction Validation, Org Routing, Commit Lint, link checking and CodeQL.
• No review threads exist at the time of review.

Limits

Live Copilot custom-agent discovery and invocation remain unverified. The runtime probe covers Zsh 5.9.2; it does not establish a compatibility matrix or measure reviewer behavior. Desktop and narrow-width rendered review inspection is unavailable in this session.