# Phase 6.6 — Scoping Note

> **Status (2026-05-05 retrospective banner):** **The spec contradiction documented in §1/§2 of this note has been RESOLVED** via spec patch on branch `spec/v3.6.7-step6-phase-6.6-budget-reconciliation` (commits `2ed71d0` + `82fdf85` + `40ea9a8`, 4 codex review rounds to 0 P1). The §10 Phase 6.6 deliverable now reads "Insert a ~50-line decision-policy summary derived from §5.6" (was: "Insert §5.6 prompt template verbatim"); the §5.6 opener / §5.6 closing prose / §9.1 R3 risk entry / §10 verification gate all describe the same Path 2 split (prompt = decision-policy summary; spec §5.6 = implementation contract).
>
> **Read §1 and §2 below as historical / pre-patch context** — they cite the spec by line number and describe what the spec USED to say. The patch keeps the same line numbers ±5 (only narrative edits, no structural change). Implementation plan in §3–§7 remains the canonical guidance for the next session's Phase 6.6 work, except: **Step 0 (spec patch round) is DONE**; start from Step 1 (TDD lint test) directly.

**Author:** Cheng-I Wu (with Claude Opus 4.7)
**Date:** 2026-05-05
**Purpose:** Pre-implementation read-through and scope reconciliation for v3.6.7 Step 6 Phase 6.6 (orchestrator agent prompt update). NOT implementation — produces a plan to align spec contradictions before any prompt edit.

**Status:** Pre-implementation note (scope reconciliation). Step 0 of the implementation plan (spec patch round) shipped on the same date; Phase 6.6 implementation proper deferred to next session per §8 rationale.

---

## 1. The contradiction

Spec `docs/design/2026-04-30-ars-v3.6.7-step-6-orchestrator-hooks-spec.md` carries three numbers that do not reconcile:

| Location | Statement |
|---|---|
| Line 1670 (§5.6 closing prose) | "The subsection adds approximately **50 lines** to the orchestrator prompt." |
| Line 2219 (§9.1 R3 risk entry) | "§5.6 adds **approximately 50 lines** to the orchestrator prompt." |
| Line 2383 (§10 Phase 6.6 verification gate) | "orchestrator prompt is no more than **+60 lines** vs pre-Step-6 baseline" |
| Line 2457 (§10 phase deliverable table) | "+60" |
| Line 2377 (§10 Phase 6.6 includes) | "Insert the §5.6 prompt template **verbatim**" |

The actual fenced ` ```markdown ` block in §5.6 spans **line 1321 → line 1668 (≈347 lines of prompt-side text)**. Line 2379 explicitly excludes the 24-row Failure State Inventory table (7 P-PA-* + 17 P-PB-* rows, line 1672–1703) from the verbatim insert: "the inventory itself stays in this spec; the orchestrator prompt cites it as a load-bearing reference."

**347 lines (verbatim) ≠ 50 lines (prose claim) ≠ +60 lines (gate).**

## 2. Where the drift came from

Spec history on this file:

```
5945b15 Phase 6.3 — lint script (#56)
092a0b9 Phase 6.1 — wrapper (#55)
f594d3e Phase 6.5 — Schema 9 amendment (#54)
7bd0d7b §3.3 add item.started event + §5.2 wire L2-5 + cascade sweep (#53)
e65ec68 §6–§11 design — risks + impl plan (#51)
b76e626 §1–§5 design (#50)
```

§5.6 was authored at #50; §10 Phase 6.6 deliverable + verification gate at #51; cascade sweep at #53. The "approximately 50 lines" claim presumably matches the §5.6 fenced block size at #50 — before later rounds expanded Path A → A1.5 superseding-proposal preflight (F-070 closure), B1a tuple-match recovery (F-067 / F-069 / F-072 closures), B8a/B8b/B8c late freshness barriers, and the 24-row Failure State Inventory.

The R3 risk entry (§9.1) and Phase 6.6 verification gate (§10) both inherited the original 50-line / +60-line footprint from #50. They were not updated as §5.6 grew. This is the cascade-inconsistency pattern recorded in `feedback_cross_model_review_cascade_inconsistency.md`.

**This is a real spec bug, not a reading error.**

## 3. Three resolution paths

### Path 1 — Honor "verbatim" (line 2377), update R3 + verification gate

Implement Phase 6.6 as: copy the entire 347-line fenced block into `pipeline_orchestrator_agent.md` between §3 Checkpoint Management and §4 Transition Management. Rename section to `### 3.5 Audit Artifact Gate (v3.6.7 Step 6)`.

**Spec edits required:** update line 1670 prose ("approximately 50 lines" → "approximately 350 lines"); update §9.1 R3 line 2219; update §10 Phase 6.6 verification gate line 2383 from `+60` to `+350`; update §10 phase deliverable table line 2457 column from `+60` to `+350`. R3 risk discussion should reflect the larger context-cost realistically.

**Pros:**
- Faithful to "verbatim" instruction (line 2377).
- Phase IDs P-PA-* / P-PB-* appear naturally in their definitional context.
- Reviewer can audit gate procedure inside the prompt without cross-spec context-switching.

**Cons:**
- 60% growth on a 580-line orchestrator prompt is not bounded — every dispatch pays the token cost.
- Path A / Path B procedural detail is execution-mechanics, not orchestrator decision-policy. Implementation-level invariants (B1a/B8b/B8c crash-recovery semantics) belong in spec, not in an LLM prompt that just needs to know "run the gate, decide on verdict".
- Violates the original R3 budget that explicitly chose 50 lines.

### Path 2 — Honor +60-line gate (line 2383), summarize §5.6 in prompt

Implement Phase 6.6 as: a ~50-line `### 3.5 Audit Artifact Gate` subsection that states **what** the gate does (trigger condition, ship/block decision rule, hard rules, cross-references) and points to spec §5.6 for **how** the procedure works (Path A → Path B fall-through, A1–A7 / B1–B11 phases, P-PA-* / P-PB-* failure inventory).

**Spec edits required:** update line 2377 from "verbatim" to "summarize and reference"; clarify line 2379 about which content stays in spec vs prompt; possibly add a §5.6.1 "What enters the orchestrator prompt" subsection enumerating the 50-line summary scope.

**Pros:**
- Honors the R3 prompt-bloat risk envelope the spec self-identified.
- Phase IDs become referenceable handles in summary (the gate spec mandates) without dragging procedural detail into prompt.
- Aligns with the broader pattern: orchestrator prompt is a **decision-policy contract**, the spec is the **implementation contract**.

**Cons:**
- "verbatim" instruction (line 2377) becomes inaccurate; that line must be edited.
- Reviewer must context-switch to spec §5.6 for procedure detail (mitigated: the 50-line summary cites spec section anchors).
- Risk: prompt summary drifts from spec procedure over time. Mitigation: Phase 6.3 lint can grep for canonical phrases / phase IDs to detect drift.

### Path 3 — Defer Phase 6.6 to a brief preflight round

Open a preflight discussion (mirror the v3.6.6 §5 brief preflight pattern referenced in ROADMAP) that picks Path 1 or Path 2 as the canonical interpretation, then patches the spec inconsistencies before implementation.

**Pros:**
- Avoids implementing against contradicting spec.
- Documents the resolution decision for future spec readers.

**Cons:**
- Adds a meta-round to a phase that should be straightforward.

## 4. Recommendation

**Path 2** with a small spec patch round.

Reasoning:
1. The orchestrator prompt is the LLM-facing contract. Procedural detail (B1a tuple-match recovery, B8c snapshot integrity) is implementation invariant — useful for reviewers and lint scripts, not for the dispatched LLM. The LLM needs decision-policy ("on PASS proceed; on MATERIAL block; on MINOR ask user; never skip; runs before integrity gate"), not 350 lines of crash-recovery transactional semantics.
2. R3 explicitly chose 50 lines as the budget. The +60 verification gate honored that. The "verbatim" instruction at line 2377 is the outlier and was authored before §5.6 grew its later refinements.
3. Path 1's 350-line prompt addition would put `pipeline_orchestrator_agent.md` at ~930 lines. Every pipeline invocation pays that token cost. Pragmatic engineering says this is bad even before the R3 risk is considered.
4. Path 2 preserves Phase 6.6's core deliverable: §3.5 subsection exists, P-PA-* / P-PB-* are referenceable in prompt, the gate has hard rules. The procedural inventory remains a load-bearing spec reference, not a prompt addition.

## 5. Implementation plan (assuming Path 2)

### Step 0 — Spec patch round (one PR)

- Edit `docs/design/2026-04-30-ars-v3.6.7-step-6-orchestrator-hooks-spec.md`:
  - Line 1670: tighten prose: "The subsection adds approximately 50 lines to the orchestrator prompt **as a decision-policy summary; the full Path A → Path B procedure stays in this spec as the implementation contract**."
  - Line 2377: change "Insert the §5.6 prompt template verbatim" → "Insert a 50-line decision-policy summary derived from §5.6, citing P-PA-* / P-PB-* phase IDs as load-bearing references to spec §5.6."
  - Line 2383: keep "+60" verification gate; add: "the §5.6 inventory's phase IDs (P-PA-* / P-PB-*) appear at least once each in the prompt **as cross-references to spec, not as inline definitions**."
- Run codex iterative review on the spec patch only (small surface, expected 1–2 rounds to 0 P1).

### Step 1 — TDD: write the lint test first

In `scripts/test_check_v3_6_7_pattern_protection.py` (or a new sibling test file):

```python
def test_orchestrator_prompt_contains_audit_artifact_gate():
    text = read_file("academic-pipeline/agents/pipeline_orchestrator_agent.md")
    assert "### 3.5 Audit Artifact Gate" in text

def test_orchestrator_prompt_references_all_phase_ids():
    text = read_file("academic-pipeline/agents/pipeline_orchestrator_agent.md")
    required_ids = {
        "P-PA-precond", "P-PA-schema", "P-PA-gate",
        "P-PA-verdict-schema", "P-PA-verdict-mirror",
        "P-PA-stale-late", "P-PA-supersede-preempt",
        "P-PB-empty", "P-PB-supersede-missing", "P-PB-ambig",
        "P-PB-proposal-schema", "P-PB-audit-failed", "P-PB-gate",
        "P-PB-verdict-schema", "P-PB-verdict-mirror", "P-PB-stale-late",
        "P-PB-dup-early", "P-PB-dup-other", "P-PB-dup-late",
        "P-PB-snapshot", "P-PB-persisted-schema",
        "P-PB-passport-write", "P-PB-consume-fail", "P-PB-crash",
    }
    missing = {pid for pid in required_ids if pid not in text}
    assert not missing, f"Missing phase IDs: {missing}"

def test_orchestrator_prompt_has_audit_gate_hard_rules():
    text = read_file("academic-pipeline/agents/pipeline_orchestrator_agent.md")
    # Hard rule 1: cannot be skipped
    assert "cannot be skipped" in text or "no skip-audit option" in text
    # Hard rule 2: runs BEFORE collaboration_depth_agent + integrity_verification_agent
    assert "BEFORE collaboration_depth_agent" in text
    assert "BEFORE integrity_verification_agent" in text
    # Hard rule 3: PASS does not skip integrity
    assert "PASS does not imply integrity check is skipped" in text \
        or "Stage 2.5 / 4.5 integrity gates remain mandatory" in text

def test_orchestrator_prompt_size_within_budget():
    text = read_file("academic-pipeline/agents/pipeline_orchestrator_agent.md")
    # Pre-Step-6 baseline: 579 lines (commit 02b87ae)
    # +60 line budget per Phase 6.6 verification gate
    line_count = len(text.splitlines())
    assert line_count <= 579 + 60, f"prompt grew to {line_count} lines, exceeds +60 budget"
```

Run: `pytest scripts/test_v3_6_7_phase_6_6.py -v` → all four tests must FAIL before implementation.

### Step 2 — Write the §3.5 subsection

Target: ≤55 lines (5-line buffer under the 60-line gate). Structure:

```markdown
### 3.5 Audit Artifact Gate (v3.6.7 Step 6)

**Trigger.** At every stage transition where a v3.6.7 downstream agent
(synthesis_agent, research_architect_agent survey-designer mode, or
report_compiler_agent abstract-only mode) just completed a deliverable.

**Decision policy.** Read or merge an audit_artifact[] entry for the
just-completed deliverable, validate against eleven gating checks (§5.2
spec), apply ship/block per verdict status:
- PASS → proceed to next stage; append audit line to FULL checkpoint.
- MINOR → MANDATORY checkpoint; surface findings; user response: iterate.
- MATERIAL → BLOCK; surface findings; user response: another_round /
  ship_with_known_residue / abort_stage (per §5.4).

**Procedure.** Path A → Path B fall-through:
- Path A re-verifies an already-merged persisted entry (recovery on
  resume / re-transition). Failure phases: P-PA-precond, P-PA-schema,
  P-PA-gate, P-PA-verdict-schema, P-PA-verdict-mirror, P-PA-stale-late,
  P-PA-supersede-preempt — all fall through to Path B with reason carried.
- Path B merges a fresh proposal file (first-time merge or supersede a
  failed Path A entry). Failure phases: P-PB-empty, P-PB-supersede-missing,
  P-PB-ambig, P-PB-proposal-schema, P-PB-audit-failed, P-PB-gate,
  P-PB-verdict-schema, P-PB-verdict-mirror, P-PB-stale-late, P-PB-dup-early,
  P-PB-dup-other, P-PB-dup-late, P-PB-snapshot, P-PB-persisted-schema,
  P-PB-passport-write, P-PB-consume-fail, P-PB-crash — most are terminal
  BLOCK; some recover (B1 restart, A7 ship, B10 read existing).

Full procedural detail (A1–A7, B1–B11, A1.5 supersession preflight, B1a
tuple-match recovery, B8a/B8b/B8c late barriers, P-PA-* / P-PB-* failure
state inventory) lives in spec §5.6. Orchestrator follows that procedure
exactly; the inventory is the implementation contract.

**Hard rules.**
- Audit gate cannot be skipped — no "skip audit" option in checkpoint
  command vocabulary.
- Audit gate runs BEFORE collaboration_depth_agent observer dispatch and
  BEFORE integrity_verification_agent dispatch — first transition-time check.
- A verdict_status: PASS does NOT imply integrity check is skipped. Stage
  2.5 / 4.5 integrity gates remain mandatory per existing §3 Hard
  boundaries rule 9.

**Failure surfacing.** Any block message uses the standard FULL/MANDATORY
checkpoint visual (━━━ separator). Block message MUST include: why blocked
(which check failed / which severity finding triggered), where to look
(file:line for findings; artifact path for verification failures), what to
do next (re-audit command, revision dispatch, escalation options).

**Cross-references.**
- Spec: docs/design/2026-04-30-ars-v3.6.7-step-6-orchestrator-hooks-spec.md
- Audit template: shared/templates/codex_audit_multifile_template.md
- Schema: shared/contracts/passport/audit_artifact_entry.schema.json
- Wrapper: scripts/run_codex_audit.sh
```

This is approximately 50 lines. All 24 phase IDs are referenced. All three hard rules are present. Cross-references intact. Procedural detail off-loaded to spec.

### Step 3 — Run lint + size checks

`python3 scripts/check_spec_consistency.py` and `pytest scripts/test_v3_6_7_phase_6_6.py` must pass; line count ≤639.

### Step 4 — Codex iterative review

Run `codex review --base main` per `feedback_codex_iterative_spec_review_to_zero.md`. Iterate until 0 P1. Particular review concerns:
- Are all 24 phase IDs *meaningful* in summary form, or do some require their detailed semantics inline?
- Does the summary preserve P-PB-supersede-missing's distinct vs P-PB-empty distinction, or does the prompt collapse them?
- Does "decision policy" framing accurately delegate execution semantics (B1a/B8b/B8c crash recovery) to spec, without leaving LLM-facing ambiguity?

### Step 5 — Bundle with Phase 6.7 (per spec §10 line 2401 recommendation)

Phase 6.7 also touches agent prompts and the same lint script. Spec recommends bundling. After 6.6 is verified, do 6.7 in the same branch.

## 6. Open questions for next-session implementation

1. **Spec patch first, or implement under contradiction?** Recommend: spec patch first (Step 0 above) so impl PR doesn't carry a self-contradicting reference.
2. **Bundle 6.6 + 6.7 in one PR or split?** Recommend: split. 6.6 ships first; 6.7 second PR adjacent. Reduces review surface; smaller blast radius if impl rounds need iteration.
3. **Should `feedback_complex_spec_review_inventory_pattern.md` invariants index get amended for v3.6.7 Step 6?** That memory captures ARS v3.6.7 Step 6 as 18-round-converged. The Phase 6.6 spec drift discovered here suggests a Round 19+ cascade-sweep of §10 phase budgets vs §5.6 actual content size.

## 7. Memory backreferences

- `feedback_cross_model_review_cascade_inconsistency.md` — pattern: even after N-round 0-P1 review, cascade refinements in one section can drift from estimates baked into other sections.
- `feedback_complex_spec_review_inventory_pattern.md` — invariants index + state inventory pattern; 18-round convergence on this very spec.
- `feedback_codex_iterative_spec_review_to_zero.md` — iterate codex review to zero P1 before ship for high blast-radius spec changes (the spec patch in Step 0 qualifies).
- `feedback_codex_review_per_schema_increment.md` — Phase 6.6 implementation deserves a codex review at the prompt-change increment, not bundled into a larger PR.

## 8. Defer rationale

This note exists *because* I read §5.6 cold this session and discovered the drift. Without this preflight, Phase 6.6 implementation would have been one of:
(a) blindly inserting 347 lines verbatim, blowing the +60 line budget by ~580%, then arguing with codex review about which lines to cut;
(b) blindly inserting 50 lines and hoping the missing 297 lines do not contain load-bearing constraints;
(c) thrashing between (a) and (b) for multiple rounds without surfacing that the spec itself is the contradicting authority.

Surfacing the contradiction first lets the next session start from a coherent position.
