Intel Dossier Graph Freshness Barrier

Goal

Guarantee that an intel dossier is synthesized only after its required intelligence-graph facets have been refreshed and their terminal freshness state has been captured. A dossier may still be produced when a required producer is unavailable, but that outcome must be explicitly degraded and must never masquerade as a normal fresh package.

AMENDED — the or explicitly degraded allowance is WITHDRAWN. This section’s terminal-snapshot machinery, identity validation, and three-output agreement stand unchanged and remain the contract. What no longer holds is the permission for synthesis to PROCEED on a degraded terminal snapshot. scripts/intel_package_runtime/admissibility.py:assess_intel_admissibility is now the single admissibility verdict: only an all-fresh snapshot is admissible evidence. A degraded terminal snapshot is a HARD BLOCK — compose_dossier_prompt writes no synthesis prompt, finalize_dossier persists no sidecar, and the verdict carries a forced cure aimed at the degradation CAUSE. Read every fresh or explicitly degraded phrase below as fresh, else BLOCK with a forced cure; a package_generated_degraded outcome is no longer a reachable clean terminal. A facet whose refresh producer FAILED also can no longer classify fresh — it classifies producer-blocked, which was already a terminal facet state this section admitted.

Root Cause

The current intel-package path is deliberately read-only. It asks the synthesis agent to run status and caveat stale tiers, while its runtime surface excludes refresh.

The reported ensure_fresh result covers compiler content hashes only; it does not cover independently versioned CPG, embedding, GDS, plan, history, RC-remark, AIMS, platform, ontology, or topology facets. Finalization then records an available graph as package_generated even when required derived facets remain stale.

The prototype-baseline dossier demonstrates the defect: synthesis finished before the first evidenced refresh, with the base code facet fresh but numerous derived facets stale. A default refresh alone is insufficient because some producers run asynchronously or under separate scopes, so the fix requires a dossier-specific required-facet policy and a foreground terminal-state barrier. The defect is demonstrated a second time by this section’s own recon substrate: the intel graph the dossier was synthesized from itself carries the false-fresh state the barrier forbids — ori-platform embedding is days stale (so the semantic-twin tier is dark for every barrier symbol) and the CPG facet is null, with the derived facets lagging the on-disk barrier edits.

The dossier’s symbol-terrain verdict is internally consistent: exact declarations and admitted call edges were usable, while derived ranking, clone, history, co-change, sibling-divergence, and test-topology conclusions were nominations. The failure is not that caveat; it is allowing generation and normal-package finalization before required facets reach a fresh or explicit degraded terminal state.

The typed post-barrier snapshot machinery already exists and is wired end to end: build_dossier_snapshot/validate_dossier_snapshot, a content-addressed snapshot_id, registry-driven required-facet validation, and per-facet dependency generations are all present, and the foreground bounded terminal-classified executor execute_dossier_refresh_policy is already written. The decisive gap is a contract inversion — run_dossier_freshness_barrier dispatches refreshes to a detached background process and returns immediately, while the barrier invariant requires a foreground bounded terminal result. The work is therefore a contract inversion plus a regression matrix over a mostly-scaffolded surface, not a build-out; the already-shipped snapshot machinery is reused unchanged, never re-implemented. Plan state and the working tree diverge: plan.json reports this section and its work items not-started, while the fix is largely landed on disk — run_dossier_freshness_barrier already calls the foreground execute_dossier_refresh_policy and re-polls status, the non-blocking pin is re-authored to blocking-to-terminal, and the ten-case matrix files exist. This is a verify-first pickup owned solely by this section: the first act is running the regression matrix to establish the true RED/GREEN baseline by case identity, never authoring from scratch or assuming not-started means unwritten.

The barrier has exactly one caller (compose_dossier_prompt), so the fix is localized: re-point the barrier body at execute_dossier_refresh_policy and re-poll status to a terminal state. The status read is currently scattered across four sites (_read_status, _call_status_fn, _default_status_fn, heal._current_graph_state); the cure is one causally-closed snapshot captured at the barrier and consumed everywhere else. finalize_dossier is the highest-coupled surface — it re-reads, identity-validates, and projects the captured snapshot into the envelope — so the three-output-agreement work concentrates there. The single admissibility verdict assess_intel_admissibility is consumed by THREE production sites, not just the barrier’s one caller: compose_dossier_prompt, finalize_dossier, and the serve-time heal_section_package gate that fronts /review-section and /continue-roadmap dossier heal. The review-section intel-enrichment path is a semantic twin of intel-package heal, so a false-fresh verdict degrades serve-time review-section dossiers too, not only /intel-package outputs — the single-verdict invariant must hold across all three consumers.

Invariants

• Freshness is evaluated per facet against that facet’s actual dependency generation, not inferred from the base code bit or an unrelated wrapper commit timestamp.
• Wrapper-only and plan-only commits do not invalidate unrelated compiler-derived facets; real facet dependencies do.
• Dirty in-scope compiler changes make the code facet stale even when the imported generation SHA equals compiler HEAD.
• Code-generation identity comparisons stay in the compiler repository domain; an unresolvable compiler HEAD yields unknown rather than falling back to wrapper HEAD.
• Dossier synthesis does not start before the barrier completes, times out, or returns a structured unavailable result.
• All refresh work is routed through scripts/intel-query.sh; intel-package does not bypass graph ownership boundaries.
• The durable Markdown, JSON envelope, and runtime exit describe the same post-barrier snapshot and degraded classification.
• Remaining stale, unavailable, or producer-blocked required facets force package_generated_degraded and name the exact remediation or unavailable producer.
• Background enrichment completing after finalization cannot retroactively make the captured dossier claim freshness.
• The barrier’s single captured snapshot is the canonical graph-state source; finalization and persistence consume that snapshot, never an additional live status sample — no fifth status-reader is added beside the existing _read_status/_call_status_fn/_default_status_fn/heal._current_graph_state cluster.
• Facet-specific dependency generations are their own single source of truth and do not overload should_regenerate; the wrapper-HEAD staleness decision stays single-responsibility.
• The three outputs project one snapshot_id through one degraded-classification function, making a fresh-Markdown-versus-degraded-exit disagreement unrepresentable.
• The existing non-blocking barrier pin is re-authored to a blocking-to-terminal pin in the same change as the new matrix; it is never deleted or skipped to reach green.
• Barrier and refresh orchestration stays in scripts/intel_package_runtime/; the consuming skill body remains a thin consumer of the structured snapshot and never lifts orchestration into a skill.
• The barrier is generic, cross-plan /intel-package infrastructure that gates every downstream bytecode-vm dossier AND the serve-time heal (heal_section_package) that fronts /review-section and /continue-roadmap dossiers; a false-fresh landing silently degrades every downstream dossier’s evidence — including serve-time review-section dossiers — so correctness of the gate dominates latency.
• The barrier fails closed: a degraded, producer-blocked, or timed-out required facet is a BLOCK verdict, never an admit, and every gate carries a falsifier that fails when the gate is reverted — inability to reach fresh is a BLOCK, not a silent degrade.
• The required-facet registry (FRESHNESS_FACETS) is a separate intel_repo ownership domain read through load_registry(); changing the required-facet set is a registry-owner policy decision, not a barrier edit. The registry must enumerate every real facet dependency of a dossier: a missing facet is a false-fresh hole (the verifying-trace soundness precondition — an unlisted dependency lets the barrier admit on stale evidence).

Success Criteria

The freshness-barrier regression matrix covers a fully fresh graph, stale code/CPG, dirty compiler files at a matching SHA, unavailable compiler HEAD, stale embeddings, detached GDS enrichment, unavailable RC/AIMS producers, refresh failure, timeout, and concurrent refresh-lock cases. It pins both orchestration order and durable package classification.

The end-to-end reproduction uses the bytecode-vm section that exposed the problem and proves there is no refresh event beginning only after dossier persistence.

Freshness for any specific facet is verified by reading the terminal snapshot’s per-facet facet_generations state — the barrier’s own re-polled observability from scripts/intel-query.sh status — never a coarse default status liveness read; a facet is proven fresh by its own dependency generation, not by an aggregate signal.

Work Items

• Verify-first: run the full freshness-barrier regression matrix (test_freshness_barrier_matrix.py, test_freshness_nonblocking.py, test_dossier_path_e2e_no_refresh_race.py, test_base_code_freshness_identity_domain.py, test_derived_facet_generation_freshness.py, test_freshness_policy.py) and confirm it covers, by case identity, all of: a fully fresh graph; stale code and CPG; dirty in-scope compiler files at a matching imported SHA; unavailable compiler HEAD; stale embeddings; detached GDS enrichment; unavailable RC and AIMS producers; refresh failure; bounded timeout; and concurrent refresh-lock outcomes. Confirm every case pins that dossier synthesis remains uncalled until the foreground barrier returns one immutable fresh or explicitly degraded terminal snapshot, and pins that no refresh first begins after dossier persistence. Treat any missing case, or any case weakened/deleted/skipped to reach green, as a regression to restore immediately (INVERTED-TDD ban).
• Verify the barrier’s non-blocking pin has already been re-authored: test_freshness_nonblocking.py:52 (test_barrier_executes_refresh_foreground_and_blocks_to_terminal) must assert the runner is used for the bounded FOREGROUND refresh execution and that the barrier returns only after a terminal FreshSnapshot/DegradedSnapshot — never assert dispatch-to-background-and-return-immediately. Confirm no other test in the file (or elsewhere in the freshness-barrier suite) still pins the old non-blocking/detached-dispatch contract. If a stale non-blocking pin is ever found, re-author it in the SAME change as any matrix work, per the section’s own invariant; retiring or deleting it to reach green is INVERTED-TDD:positive-test-modification.
• Verify base-code freshness stays in the compiler identity domain: test_base_code_freshness_identity_domain.py’s 8 tests must confirm dirty in-scope compiler changes classify stale when the imported SHA equals compiler HEAD, unknown is returned when compiler HEAD is unavailable (never falling back to wrapper HEAD), and the clean/dirty/unavailable-identity cases are all pinned at both the observed-state and refresh-policy layers. Confirm no regression reintroduces a wrapper-HEAD fallback for the code facet.
• Verify derived-facet freshness is driven by facet-specific dependency generations, never wrapper-HEAD timestamp invalidation: test_derived_facet_generation_freshness.py’s 6 tests must confirm each derived facet reads its own freshness bit independent of wrapper HEAD moves, a real dependency change makes only that facet stale, and one stale or unavailable derived facet never invalidates a fresh sibling facet. Confirm no regression reintroduces wrapper-HEAD-timestamp invalidation for any derived facet.
• Verify the contract-inversion fix is intact: run_dossier_freshness_barrier (dossier_snapshot.py:342) must call the foreground, bounded, terminal-classified execute_dossier_refresh_policy (freshness_policy.py:338) — never the retained-but-deprecated background dispatch_dossier_refresh_policy (freshness_policy.py:397) — and must re-poll scripts/intel-query.sh status after the refresh executes so each FacetSnapshot’s observed_generation and state reflect post-refresh reality. Confirm the already-shipped build_dossier_refresh_policy, load_registry(), build_dossier_snapshot()/validate_dossier_snapshot() machinery is consumed unchanged (never re-implemented). Confirm the runner=/dispatcher= seams remain the regression matrix’s real injection point (not seam-injected-only coverage) and the degrade-never-hang contract holds: every refresh route stays bounded by its REFRESH_ROUTES timeout, and a bounded-timeout/failed/producer-blocked outcome still yields a terminal DegradedSnapshot with a named remediation, never a hang.
• Verify dossier finalization requires the compose-time terminal snapshot artifact: finalize_dossier (compose_prompt.py:424) must validate the captured snapshot’s identity rather than replacing it with a late status sample, preserve captured facet states against later background enrichment, persist an agent-authored degraded package while retaining malformed and non-agent guards, and project the SAME snapshot identity, exact non-fresh facet reasons, producer outcomes, and remediations into the durable Markdown metadata, JSON envelope, and runtime result — confirmed by the existing test_compose_prompt.py pins (test_finalize_blocks_on_degraded_barrier_snapshot_and_persists_nothing, test_finalize_never_relabels_snapshot_after_live_graph_changes, test_finalize_rejects_missing_or_tampered_snapshot_artifact, test_compose_freshness_matrix_persists_terminal_snapshot_before_prompt_release). Confirm graph-unavailable or any remaining required stale/unknown/unavailable/producer-blocked facet yields package_generated_degraded consistently across all three outputs, making a fresh-Markdown-versus-degraded-exit disagreement structurally unrepresentable.
• Verify test_dossier_path_e2e_no_refresh_race.py’s test_intel_dossier_path_e2e_terminal_and_no_post_finalize_refresh_race continues to exercise the real run_dossier_freshness_barrier + finalize_dossier path (the identical logic _cmd_finalize_dossier’s CLI wrapper invokes) and continues to pin both a terminal FreshSnapshot/DegradedSnapshot outcome and that every refresh event precedes the persist event. Additionally drive the real production CLI entry point at least once (python -m scripts.intel_package_runtime finalize-dossier --target plan-section:bytecode-vm/s-16d824b7 ... against a real or injected-at-the-subprocess-boundary graph state) to close the residual L12 production-entry-point gap the function-level test alone does not fully close, per layer-coverage.md §1.3 L12.

Intel dossier — pointer and tier disposition

Dossier: intel-dossier-graph-freshness-barrier--s-16d824b7.intel.md (this section’s content/intel/ sidecar)

Read that dossier from line 1 through EOF before acting on this section. This block is a pointer and an audit record, never a substitute: not the BLUF, not a summary, not selected tiers.