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(commits2ed71d0+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.
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).
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.
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.
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.
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.
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.
docs/design/2026-04-30-ars-v3.6.7-step-6-orchestrator-hooks-spec.md:In scripts/test_check_v3_6_7_pattern_protection.py (or a new sibling test file):
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.
Target: ≤55 lines (5-line buffer under the 60-line gate). Structure:
### 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.
python3 scripts/check_spec_consistency.py and pytest scripts/test_v3_6_7_phase_6_6.py must pass; line count ≤639.
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?
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.
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.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.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.