fix(package): address outstanding parser review findings

[ss-o]

Problem and change

Addresses the outstanding review findings in #514. Key-like text inside a quoted JSON value could select the wrong object, and surrogate escapes were decoded despite the documented preservation contract.

• Record member names at structural colons in the existing parser, including decoded key names, and use those records for object selection. Cover both manifest and _from callers.
• Preserve surrogate escapes and test malformed Unicode escapes through the shipped manifest lookup.
• Require complete conversation, review-summary, and thread inspection before merging. Replace the promotion template's administrator-bypass example with a merge bound to the reviewed head SHA.

Refs #513
Refs #514

Validation

• All 27 existing Zsh test scripts passed on Zsh 5.9.2 (Linux).
• New regression fails on the merged implementation. Removing either fix independently fails the expanded regression.
• Native syntax and temporary compilation passed for both changed Zsh files.
• Markdownlint, Prettier, diff checks, and commit hooks passed.
• Native macOS and older Zsh versions are unverified. Hosted CI is pending.

Instruction impact

1. Repository-specific review and merge guidance, not a new shared policy or enforcement service.
2. Applies to reviewers and agent runtimes consuming Zi's AGENTS.md, and maintainers using its promotion template.
3. Zi owns this repository-specific guidance; shared organization policy remains canonical.
4. The template follows the AGENTS.md merge gate; neither duplicates the shared review skill.
5. No manifest route changes are needed for existing instruction surfaces.
6. The merge gate is in AGENTS.md and does not depend on optional skill invocation.
7. No generated instruction output changes; size and formatting checks pass. Other runtime discovery remains unverified.

Agent handoff

The follow-up targets next and is ready for code-owner review. Do not resolve #514's threads solely because this PR exists: review the fix and record its disposition first. No merge or auto-merge is requested.

[Copilot]

🔵 Needs a closer look

Parser output can execute shell commands, while hosted and cross-version Zsh validation remains pending.

Pull request overview

Fixes JSON manifest parsing edge cases and strengthens merge-review safeguards.

Changes:

• Selects objects using structurally parsed, decoded member names.
• Preserves surrogate and malformed Unicode escapes with regression coverage.
• Requires complete review inspection and SHA-bound, non-bypassing promotion merges.

File summaries

File	Description
lib/zsh/install.zsh	Corrects key detection and surrogate handling.
tests/package-manifest-parsing.zsh	Adds parser regressions for both production callers.
AGENTS.md	Defines repository merge-review requirements.
.github/PULL_REQUEST_TEMPLATE/promotion.md	Aligns promotion checks and merge command.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 0
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.