# Investigation: RECORDING_INTEGRITY Install Path

**Date**: 2026-03-07
**Investigator**: Rex (nw-troubleshooter)
**Methodology**: Toyota 5 Whys with anti-bias protocol

## Problem Statement

User (Marcus) updated nWave to v2.1.0 (which contains the RECORDING_INTEGRITY fix in execute.md) but at 17:09 reports the DES hook STILL blocks with missing RECORDING_INTEGRITY.

---

## Evidence Collection

### Track 1: Source File Verification

**E1.1** `nWave/tasks/nw/execute.md:118-123` -- RECORDING_INTEGRITY section confirmed present in source:
```
# RECORDING_INTEGRITY
Valid Skip Prefixes: NOT_APPLICABLE, BLOCKED_BY_DEPENDENCY, APPROVED_SKIP, CHECKPOINT_PENDING
Anti-Fraud Rules:
- NEVER write EXECUTED for phases you did not actually perform
- NEVER invent timestamps — DES CLI generates real UTC timestamps
- DES audits all entries; integrity violations block finalize
```

**Finding 1**: The fix IS in the source file. ✅

### Track 2: DES Hook Validation Path

**E2.1** `src/des/adapters/drivers/hooks/claude_code_hook_adapter.py` -- PreToolUse hook fires on Agent tool invocation.

**E2.2** `src/des/application/pre_tool_use_service.py:563` -- Prompt extracted from `tool_input.get("prompt", "")`. This is the prompt the **orchestrator** (main session) passes to the Agent tool.

**E2.3** `src/des/application/validator.py:54-64` -- `MandatorySectionChecker` validates that `# RECORDING_INTEGRITY` appears in the extracted prompt string.

**Finding 2**: The DES hook validates the **orchestrator's prompt**, not the execute.md file. The prompt must contain all 9 mandatory sections INLINE. ✅

### Track 3: The Smoking Gun — deliver.md Contradiction

**E3.1** `nWave/tasks/nw/deliver.md:96` -- Phase 2 instructions say:
> "IMPORTANT: Use DES Prompt Template from execute.md | Include DES markers (DES-VALIDATION|DES-PROJECT-ID|DES-STEP-ID) + 9 mandatory sections"

**E3.2** `nWave/tasks/nw/deliver.md:159-181` -- Task Invocation Pattern shows an **abbreviated** prompt:
> "Read full DES Prompt Template from ~/.claude/commands/nw/execute.md"

This abbreviated pattern does NOT inline the 9 mandatory sections. It delegates reading to the sub-agent.

**E3.3** The DES PreToolUse hook fires BEFORE the sub-agent starts. The hook validates the prompt that the orchestrator passes — which, if following the abbreviated pattern, contains only 3 DES markers and a reference to execute.md, NOT the 9 mandatory sections.

**Finding 3**: `deliver.md` contains TWO CONFLICTING patterns:
1. Line 96: "Include 9 mandatory sections" (correct, but prose instruction)
2. Lines 159-181: Abbreviated template that omits sections (incorrect, but concrete code example)

When the orchestrator follows the concrete example (as LLMs typically do), the DES hook blocks because the 9 sections are missing from the prompt. **This is the root cause.**

### Track 4: Distribution Path Verification

**E4.1** `pyproject.toml` -- Wheel packages: `["src/des", "scripts/install"]`. `nWave/` directory NOT in the wheel.

**E4.2** `.github/workflows/release-prod.yml:589-637` -- rsync excludes do NOT exclude `nWave/tasks/`. The `execute.md` IS synced to the public `nwave-ai/nwave` repo.

**E4.3** The installer uses a plugin system that copies `nWave/tasks/nw/*.md` to `~/.claude/commands/nw/`.

**Finding 4**: The distribution path is correct. execute.md reaches users' installations. The issue is NOT in packaging.

---

## Toyota 5 Whys

**WHY 1**: Marcus's DES hook blocks with "MISSING: Mandatory section 'RECORDING_INTEGRITY' not found" after updating to v2.1.0.

**WHY 2**: The DES hook validates the prompt passed to the Agent tool. The prompt does not contain `# RECORDING_INTEGRITY`.

**WHY 3**: The orchestrator (main session running `/nw:deliver`) follows the Task Invocation Pattern in `deliver.md` (lines 159-181), which uses an abbreviated prompt that tells the sub-agent to "Read full DES Prompt Template from execute.md" — it does NOT inline the 9 mandatory sections.

**WHY 4**: `deliver.md` contains a concrete abbreviated template example (lines 159-181) that contradicts the prose instruction at line 96 ("Include 9 mandatory sections"). LLMs follow concrete examples over prose instructions.

**WHY 5**: The `deliver.md` Task Invocation Pattern was written before the DES PreToolUse hook existed. When the hook was added, the deliver.md pattern was not updated to inline the full template. The execute.md was updated but deliver.md still delegates template reading to the sub-agent — which is too late for the hook to validate.

**ROOT CAUSE**: `deliver.md` Task Invocation Pattern (lines 159-181) uses an abbreviated prompt that does not inline the 9 mandatory DES sections. The DES PreToolUse hook validates the prompt BEFORE the sub-agent reads execute.md, so the abbreviated prompt always fails validation.

---

## Hypothesis Evaluation

| Hypothesis | Verdict | Evidence |
|-----------|---------|----------|
| H1: Fix not included in v2.1.0 release | **REFUTED** | rsync excludes don't block execute.md; file IS in source |
| H2: Installer doesn't copy execute.md properly | **REFUTED** | commands_plugin copies all nWave/tasks/nw/*.md files |
| H3: Section header format mismatch (## vs #) | **REFUTED** | execute.md uses `#` inside code block; validator searches for `# SECTION_NAME` |
| H4: deliver.md abbreviated pattern causes validation failure | **CONFIRMED** | deliver.md:159-181 shows minimal prompt; DES hook fires before sub-agent reads execute.md |
| H5: Claude session caching old template | **REFUTED** | Issue persists across new sessions after reinstall |

---

## Fix Required

**Primary fix**: Update `deliver.md` Task Invocation Pattern (lines 159-181) to inline the full DES template from execute.md, including all 9 mandatory sections.

**Alternative**: Modify the DES PreToolUse hook to recognize a "delegated template" pattern and skip section validation when the prompt references execute.md. This is more fragile and NOT recommended.

---

## Confidence Assessment

| Finding | Confidence | Reasoning |
|---------|------------|-----------|
| Root cause (deliver.md abbreviated pattern) | **HIGH** | Direct code path: deliver.md pattern → prompt → DES hook → validation failure |
| Fix location (deliver.md lines 159-181) | **HIGH** | Only one concrete template example in deliver.md |
| Distribution path is correct | **HIGH** | rsync excludes verified; no nWave/tasks/ exclusion |
