feat(zcode-parity): step 1 — emit-wrapper infra + end-of-turn-reminder B2-C + B1 latent fix

[artyhoo]

Summary

ZCode parity step 1 — ship three concrete deliverables from plan-v3 (Phase -1 round 3 dual Opus reviewer GO, advisory fixes integrated). Plan: /tmp/zcode-parity-orch/plan-v3.md.

1. Mechanism 1 — _zcode-emit additive helper (NEW infrastructure, zero adopters — declared follow-up umbrella for migration). Sourced _ze_classify + _ze_emit functions providing a universal adapter between plain-stdout CC semantics and strict-JSON ZCode semantics.
2. Bespoke feat: audit fixes Phase 1+2+3 (R2/R11 drift, manifest SSOT, depcruise integration) #1 — end-of-turn-reminder B2-C fix. The only runtime-DEAD Stop hook on ZCode (pre-fix: L52 grep '"type":"assistant"' returned 0 lines on ZCode synthetic transcripts). Part A: grep -E '"(type|role)":"assistant"' alternation (both arms load-bearing). Part B: ZCode-gated thin-recap branch emitting {decision:"block", reason, systemMessage} (T-ZP-B: reason, NOT additionalContext).
3. B1 — inject-project-digest.sh env-first REPO_ROOT (source-level). Subshell-aware latent-bug fix preparing for future plugin-channel shipping; twin NOT shipped in this umbrella.

Honest scope: 9 files per plan-v3 scope table + 2 in-flight scope additions (install-sh baseline regen after hook content change + principles/24 parallel-gate extension, both documented below). ZERO existing twins migrated to source _zcode-emit. NO Mechanism 2 (twin auto-derivation — rejected). NO Bespoke #2 (warn-subagent-report ZCode variant — rejected).

Acceptance criteria (T20: every checkbox cites a concrete artifact)

• All 9 plan-v3 scope files created/edited + 2 scope additions (principles/24-plugin-manifest-integrity.test.ts + tests/install-sh/baselines/* regen). Evidence: git diff --stat origin/staging..HEAD = 22 files, ~1050 insertions.
• <CHECK_ALL> green at end of each stage AND finally. Evidence: make self-audit final run = GREEN, 311+ tests across 34+ files.
• _zcode-emit.test.ts unit tests pass (Mechanism 1 forward+backward). Evidence: npx vitest run hooks/_zcode-emit.test.ts = 17/17 pass.
• end-of-turn-reminder.test.ts Part A both arms tested in isolation + Part B reason field asserted. Evidence: npx vitest run hooks/end-of-turn-reminder.test.ts = 37/37 pass; zcode_synthetic_transcript_last_line_extracted_via_role (role arm) + cc_transcript_last_line_extracted_via_type (type arm) + thin_recap_emits_reason_not_additional_context all pass.
• inject-project-digest.test.ts B1 env-first resolution + fallback. Evidence: npx vitest run hooks/inject-project-digest.test.ts = 10/10 pass; mutation-gate proof (reverting L27 → only env_var_first_resolution_reads_consumer_root fails) documented in research-patch.
• tests/plugin/hook-paths.test.sh extended with _zcode-emit skip-list + case (h) repo_root_resolution_form sweep over 8 twins. Evidence: bash tests/plugin/hook-paths.test.sh = PASS=68 FAIL=0 (was 53); case (h) asserts all 8 in-sweep twins.
• tests/install-sh/snapshot.sh baselines regenerated after hook-content change. Evidence: SNAPSHOT_MODE=compare bash tests/install-sh/snapshot.sh = 11/11 PASS (8 npm stacks × {green,brown} + 3 python).
• docs/meta-factory/research-patches/2026-07-18-zcode-parity-step1.md written with all required sections.
• §1.7 forward + backward tables copied verbatim into PR body (below) + §1.7 applied sections with file:line citations (below).
• PR base = staging. Evidence: gh pr create --base staging.

Twin byte-identity (T-ZP-A)

diff .claude/hooks/end-of-turn-reminder.sh plugin/hooks/end-of-turn-reminder = ZERO. Was byte-identical pre-edit (verified at Stage 1); remains so post-edit (Part A + Part B mirrored byte-for-byte).

Plan deviations (3) + scope additions (1)

#	Item	Rationale
1	Added packages/core/principles/24-plugin-manifest-integrity.test.ts V8 skip-list extension (10th file vs plan-v3's 9).	Plan-v3 scope named only hook-paths.test.sh as gate-compat edit, but the repo runs a SECOND parallel marker gate in principles/24 V8 with the same skip-set. Without extending it, [V8] hook _zcode-emit: missing marker fails. Same T-ZP-C rationale. Stage 1 self-audit caught it.
2	_ze_classify uses jq -r 'keys[0]' + bash case for allowed-key check instead of regex on serialized form.	Plan-v3 did not pin implementation. A regex anchored on ^" would miss {"key":…} (leading {); keys[0] extraction is robust to pretty-printing + key order. Same external behaviour.
3	Restored §7 active-AI-traps enumeration in kickoff.md (was stashed pre-branch).	Required by principles/12-ai-laziness-traps.test.ts gate. Stash was a branch-creation artifact; restoration is bookkeeping.
4 (scope)	Regenerated tests/install-sh/baselines/{react-native,react-next,react-spa,ts-server}/{greenfield,brownfield}.fingerprint (8 files).	These baselines fingerprint the installed consumer tree, which ships .claude/hooks/end-of-turn-reminder.sh + .claude/hooks/inject-project-digest.sh. Both hooks had content changes in this PR → fingerprint sha256 legitimately rotates. Regenerated via SNAPSHOT_MODE=capture bash tests/install-sh/snapshot.sh; CI shard C (install-sh battery) was red until this regen. This is expected maintenance when a shipped hook changes (per tests/install-sh/snapshot.sh:8-12).

Full details in docs/meta-factory/research-patches/2026-07-18-zcode-parity-step1.md §"Plan deviations".

Non-goals (DO NOT expect in this PR)

• Mechanism 2 (twin auto-derivation) — DROPPED, conflicts with hand-maintained-twin SSOT at render-harness-config.mjs:333.
• Bespoke feat: self-application + meta-factory foundation (Phase 0.5–3) #2 (warn-subagent-report ZCode variant) — REJECTED, SubagentStop not in ZCODE_EVENTS, already declared CC-only.
• Migration of 9 existing plugin twins to source _zcode-emit — declared follow-up umbrella.
• inject-project-digest plugin twin shipping — declared follow-up umbrella.
• L43/L45 anchor-extraction grep fixes — documented as honest degradation (Part C).
• SubagentStart loud-declaration renderer-side — documented in research-patch only.

---

§1.7 Forward-check applied

This PR ships three fixes; each one is paired with a firing test that proves the fix works (the §1.7 Forward-check table below restates the full mapping verbatim from plan-v3 §1.7). Forward-check evidence of fix→test pairing, by file:line: (a) plugin/hooks/_zcode-emit:84 _ze_emit() ZCode-gated passthrough ↔ packages/core/hooks/_zcode-emit.test.ts:non_zcode_passthrough_cat (17 unit tests total); (b) .claude/hooks/end-of-turn-reminder.sh:69,230 grep -E '"(type|role)":"assistant"' alternation ↔ packages/core/hooks/end-of-turn-reminder.test.ts:zcode_synthetic_transcript_last_line_extracted_via_role + cc_transcript_last_line_extracted_via_type (both arms tested in isolation, 37 tests total); (c) .claude/hooks/end-of-turn-reminder.sh:123-124 emits decision:"block" + reason: field ↔ thin_recap_emits_reason_not_additional_context (asserts reason: key present, additionalContext: key absent); (d) .claude/hooks/inject-project-digest.sh:27 env-first REPO_ROOT="${CLAUDE_PROJECT_DIR:-…}" ↔ packages/core/hooks/inject-project-digest.test.ts:env_var_first_resolution_reads_consumer_root (10 tests total). The plan-v3 forward-check tables are reproduced verbatim below this section.

§1.7 Backward-check applied

Each "fix removed →" row in the §1.7 Backward-check table below is a mutation gate (test fails without the fix). Sibling-sweep applied to existing repo artefacts under the new rules' scope: (a) tests/plugin/hook-paths.test.sh:107 case (h) repo_root_resolution_form sweeps all 8 plugin twins that read repo files (Form A env-first OR Form B cd-guard, enumerated by name) — a future hand-added twin without the guard would fail the sweep (T21 done right); (b) packages/core/principles/24-plugin-manifest-integrity.test.ts:213 if (f.startsWith('_zcode-')) continue skip-list extension ensures the sourced-helper _zcode-emit is exempt from the @dual-pair/@cc-only-rationale marker gate across BOTH parallel marker gates; (c) tests/install-sh/snapshot.sh + regenerated baselines sweep the installed-tree fingerprint across 8 npm stacks × {greenfield,brownfield} + 3 python, byte-identical — a future drift between shipped hook and baseline fails CI shard C. The plan-v3 backward-check table is reproduced verbatim below this section.

---

§1.7 — Forward-check + Backward-check (PR-body draft)

§1.7 Forward-check (each fix has a firing test that proves the fix works)

Fix	Test (file:name)	Asserts
Mechanism 1 wrapper pass-through	_zcode-emit.test.ts :: passthrough_valid_json_allowed_key	stdin {"system":[…]} → stdout byte-identical
Mechanism 1 wrapper plain-text wrap	_zcode-emit.test.ts :: wrap_plain_text	stdin hello → stdout {"additionalContext":"hello"}
Mechanism 1 wrapper empty silent	_zcode-emit.test.ts :: empty_silent_exit0	empty stdin → exit 0, no stdout
Mechanism 1 wrapper edge cases	_zcode-emit.test.ts :: multiline_trailing_newline / zero_allowed_keys / double_wrap_prevention	correct classification, no double-wrap
Mechanism 1 non-ZCode gate	_zcode-emit.test.ts :: non_zcode_passthrough_cat	ZCODE_PROJECT_DIR unset → _ze_emit cats stdin unchanged (no-op)
Mechanism 1 gate-compat	tests/plugin/hook-paths.test.sh (existing)	_zcode-emit extensionless + in skip-list; gate green
Bespoke #1 Part A ZCode arm	end-of-turn-reminder.test :: zcode_synthetic_transcript_last_line_extracted_via_role	synthetic {role:assistant,type:text,…} → last_line non-empty (matched via role arm)
Bespoke #1 Part A CC arm	end-of-turn-reminder.test :: cc_transcript_last_line_extracted_via_type	CC fixture (outer "type":"assistant") → last_line non-empty (matched via type arm)
Bespoke #1 Part B thin-recap	end-of-turn-reminder.test :: zcode_long_markdown_emits_block_decision_with_reason_field	>500 chars markdown under _is_zcode → {decision:"block", reason:"<nudge>"} (NOT additionalContext)
Bespoke #1 Part B gate	end-of-turn-reminder.test :: non_zcode_skips_thin_recap	under non-ZCode env, thin-recap branch does not fire
B1 source-level rewrite	inject-project-digest.test :: env_var_first_resolution_reads_consumer_root	under CLAUDE_PROJECT_DIR=/consumer, fixture at /consumer/.claude/session-bootstrap.md IS read
B1 source-level fallback	inject-project-digest.test :: dogfood_fallback_when_env_unset	CLAUDE_PROJECT_DIR unset → $0-fallback resolves correctly (dogfood behavior preserved)

§1.7 Backward-check (each test fails without the fix — mutation-gate)

For each "fix removed →" row, the named test must fail. Plus sibling-sweep (T21 counter #2 — #backward-check-restates-not-sweeps):

Fix removed →	Test that catches the regression
Mechanism 1 wrapper absent (helper deleted)	_zcode-emit.test.ts :: passthrough_valid_json_allowed_key etc. — all unit tests fail (function undefined)
Mechanism 1 helper not sourced by adopter	n/a (no adopter in v3 — but integration test in follow-up umbrella will cover)
Gate skip-list not extended	tests/plugin/hook-paths.test.sh fails: _zcode-emit swept, no marker → check (b) fails
Bespoke #1 Part A role arm dropped (keep type only)	end-of-turn-reminder.test :: zcode_synthetic_transcript_last_line_extracted_via_role fails: synthetic line has no outer type → last_line empty (current runtime-DEAD state). Strengthened vs v2 (reviewer-B MAJOR): both arms tested in isolation.
Bespoke #1 Part A type arm dropped (keep role only)	end-of-turn-reminder.test :: cc_transcript_last_line_extracted_via_type fails: CC line's outer type is the matchable field; role-only misses it on CC
Bespoke #1 Part A both arms dropped	either test fails (current runtime-DEAD state)
Bespoke #1 Part B branch absent	end-of-turn-reminder.test :: zcode_long_markdown_emits_block_decision_with_reason_field fails: no {decision:"block"} emitted
Bespoke #1 Part B uses additionalContext instead of reason	NEW (reviewer-A NM-2): assert emitted JSON contains reason: key, NOT additionalContext: key. Test: end-of-turn-reminder.test :: thin_recap_emits_reason_not_additional_context — fails if field swapped
Bespoke #1 Part B _is_zcode gate absent	end-of-turn-reminder.test :: non_zcode_skips_thin_recap fails: branch fires on CC dogfood → regression
B1 rewrite absent (env-first arm removed)	inject-project-digest.test :: env_var_first_resolution_reads_consumer_root fails: $0→plugin payload dir, fixture absent, silent exit 0. Strengthened vs v2: assertion is "fixture IS read with rewrite; fixture is NOT read without rewrite" — distinguishes guard-present-file-missing from guard-absent-wrong-dir.
B1 fallback absent (env-first unconditional)	inject-project-digest.test :: dogfood_fallback_when_env_unset fails: dogfood CC env without env-var can't resolve $0-relative path

Sibling-sweep assertions (T21):

• B1 sweep — env-first form invariant: all 9 plugin twins that read repo files must carry REPO_ROOT="${CLAUDE_PROJECT_DIR:-…}" (or PROJECT_DIR rename). Extend tests/plugin/hook-paths.test.sh with a new check (or sibling test file) that asserts this invariant across the 9 verified twins (list above). Catches future regressions when new twins are hand-added without the guard. This is an EDIT to existing gate file (file chore(meta-factory): Phase 3 Step 0 retrofit + 3 MAJOR fixes #3 already counted), not a new file — scope estimate holds at 9.
• B2 sweep — warn-subagent-report CC-only containment: no test added — the existing render-harness-config.mjs:256 declaration is the SSOT; a gate-test asserting the renderer's own declaration would be tautological. Honest scope decision, documented here. If a future contributor adds warn-subagent-report to plugin twins by mistake, hook-paths.test.sh check (b) catches it (would need @dual-pair or @cc-only-rationale marker; the existing @cc-only-rationale at .claude/hooks/warn-subagent-report.sh:7 documents the design intent).