Skip to content

feat(memory): reconcile existing uncertainty surfaces into one compression-stable stance contract #2559

Open

Description

@AlexStocks

Start Here and Theme

A resumed agent reads a derived summary (Handoff, Topic Memory, Dream output) as if every sentence were a settled fact. Summaries are model-written, and qualifier words ("probably", "I suspect", "unconfirmed") are the first thing a summarizer drops. An untested hypothesis can therefore be hardened into a fact the resumed agent acts on, or lost together with the investigative thread.

PowerContext already has several partial mechanisms for this — this task does not create one from nothing. On the inspected baseline, HandoffOmission is a schema-bound slot whose own docstring is "Known relevant material that was unavailable or not verified"; the Handoff prompt already says "Record relevant uncertainty or unavailable support as an omission"; Dream's revise_topic_memory already says "Preserve confirmed results, hypotheses, ruled-out causes, open questions, and next steps as distinct claims"; Topic Memory's content instructions already say "preserve uncertainty, negations and observed status"; and RFC 0014 already names working_note as the kind for information useful only to the current handoff.

What is missing is coherence and fidelity across those mechanisms, not their existence:

  • HandoffOmission conflates "material was unavailable" with "this claim is not verified"; a single text field has no separate basis, so areader cannot tell an evidence gap from a live hypothesis.
  • The four surfaces use four different words (omission, hypotheses, uncertainty, working_note) with no shared claim/basis shape and no guarantee that a second derived pass keeps the distinction.
  • The artifact body is JSON (HandoffService.render() returns content.model_dump_json(by_alias=True, indent=2)); ## Markdown sections exist only in the dashboard renderer. A labelled section is therefore a field/rendering decision, not a prompt-only edit.
  • The token UNVERIFIED is already a public enum value (Status1.UNVERIFIED = "unverified", http/_generated/models.py:817) meaning "no execution outcome or control failure has been observed". Reusing it as an epistemic label would create two meanings for one token.

Today: a turn containing "I suspect the offset is 12 degrees, not confirmed" is recorded either as an omission with no basis, as plain prose, or not at all — and a second derivation has no contract to keep whichever form was chosen. After this task: one agreed, schema-bound claim/basis shape carries the hypothesis through at least two derivation passes, with a name that does not collide with Status1.UNVERIFIED.

This task is design first. It must resolve a real contract conflict before any production change: RFC 0014 (docs/en/rfcs/0014_memory_layer_design.md:261) lists "unverified speculation" among things that must not be saved as a durable Memory entry, while :531-533 names working_note as the sanctioned short-term kind. The design note must say exactly which layer owns the stance, whether working_note or HandoffOmission is reused or extended, and why RFC 0014 is not violated.

Theme: Reconcile the existing uncertainty surfaces into one compression-stable, schema-bound stance contract — so a hypothesis is neither hardened into fact nor lost, without becoming a durable "fact" or an authority signal.

Contribution to the overall goal (2026-11-09 cross-system memory review): lowers the risk of a resumed agent acting on an unverified hypothesis by making the already-existing signals consistent and durable across re-derivation. It does not touch retrieval, Source capture, or public APIs.

Observable behavior that must appear:

  • A session containing qualified claims yields a derived summary where each uncertain claim is a structured claim + basis pair in the agreed field, not a fact in state / next_action / Topic detail.
  • A second derived pass over that summary preserves those pairs; they are not collapsed into facts or dropped.
  • Older artifacts without the agreed field remain valid and are not retroactively rewritten.
  • The stance is never fed into authority, verification, ranking, or access-control inputs, and is never confused with Status1.UNVERIFIED.

Invariants to keep:

  • Historical Sources and Artifacts stay immutable; no backfill, no re-materialization.
  • EvidenceManifest.incomplete (evidence-parse layer), MemoryEvidenceDeclaration (feat(memory): persist versioned Source evidence and neutral Atomic Memory projection #2004, authority layer), feat(capture): declare bounded projection coverage #2451 capture coverage (Source-projection layer), and Status1.UNVERIFIED (execution-observation status) each keep their own meaning.
  • The stance rule is interpolated only into the prompt that generates the summary — never into the system prompt or a persisted prefix, so the prompt-cache prefix is untouched.
  • The stance is a labelled structured slot with a claim and a basis, not free-form prose the model may silently rewrite.

Typical drift: adding a confidence: float to every Memory; reusing the UNVERIFIED token as a label; writing "we should probably check X" into a durable Atomic Memory and calling that stance preservation; assuming a ## Unverified / Working Hypotheses Markdown section exists in the artifact when it does not; changing only prompts.py and claiming a structured slot was added; or folding stance into capture coverage.

Contract version: 2026-11-09. Inspected baseline: remote master 2291237a7809410ea0dc8f19f2de149573af8378 (2026-11-09 20:13 +0800), re-verified 2026-11-09 21:15 +0800. Freeze this Issue body's hash at kickoff.

Background and Evidence

Verified on the baseline above (all assertions re-run with exact case and scope; an earlier draft's grep was truncated by head and incorrectly reported "only unrelated documentation hits"):

  • src/powercontext/builtin/artifacts/handoff/models.py:218-227 — HandoffOmission(_HandoffValue) with docstring "Known relevant material that was unavailable or not verified.", fields text (max_length) and optional citation, plus a require_text validator. HandoffGenerationOutput.omissions: tuple[HandoffGenerationOmission, ...] (handoff/generation.py:87-93) is schema-bound, not free text.
  • src/powercontext/builtin/artifacts/handoff/prompts.py:17-39 — HANDOFF_GENERATION_INSTRUCTIONS_VERSION = "powercontext.handoff.generate.v2" and the rule "Record relevant uncertainty or unavailable support as an omission; do not invent missing facts."
  • src/powercontext/builtin/dream/generation.py:46-48 — revise_topic_memory: "Preserve confirmed results, hypotheses, ruled-out causes, open questions, and next steps as distinct claims."
  • src/powercontext/builtin/artifacts/topic_memory/generation.py:342-343 — TOPIC_MEMORY_CONTENT_INSTRUCTIONS: "preserve uncertainty, negations and observed status".
  • src/powercontext/http/_generated/models.py:817 — Status1.UNVERIFIED = "unverified"; its meaning is documented at :4907 as "no execution outcome or control failure has been observed in this window". builtin/runtime/models.py:185 and schema.py:8507 use the same pair. A case-insensitive git grep "unverified" origin/master returns ~200 hits, so "no corresponding mechanism" was never a defensible premise.
  • src/powercontext/builtin/artifacts/handoff/service.py:356-367 — HandoffService.render() returns content.model_dump_json(by_alias=True, indent=2). Markdown ## sections appear only in src/powercontext/server/dashboard/markdown.py:101-103 (handoff_markdown, labels from CATALOGS[language], called at server/dashboard/routes.py:447).
  • RFC 0014: :257 routes handoff-only information to working_note; :531-533 lists working_note among the known Memory kinds "for short-term progress". RFC 1790 / feat(work): add source-backed working notes #1949 cover its generation. This is the pre-existing candidate answer to "which layer owns it".
  • Existing tests: tests/builtin/artifacts/handoff/test_generation.py, tests/builtin/artifacts/handoff/test_generation_metadata.py, tests/builtin/artifacts/topic_memory/test_generation.py, tests/e2e/test_handoff_prompt_provenance_api.py.
  • External, read-only evidence: Hermes agent/context_compressor_prompt_rules.py at 466591fe65d0... (an explicit labelled field inserted only into the summarizer prompt); Codex b8725c18 (#59902) keeps verified Q&A whole. Copy the principle, not the shape or the token.

Parent requirement: the 2026-11-09 review of Hermes 466591fe, Codex 8703d32b and PowerContext 2291237a memory mechanisms, summarized above. No local file or prior conversation is needed to execute this task.

Not in scope: retrieval changes, capture coverage (#2451), source evidence declarations (#2004), Receipt diagnostics (#2436), and any change to openapi/powercontext.yaml.

Baseline and Dependencies

Allowed

  • Phase 1 (required; no production edits): a design note delivered as an issue comment or a Markdown draft. It must decide and justify, with file-level evidence:

    1. Whether to reuse/extend HandoffOmission (add a basis and separate "unavailable" from "not verified") or introduce a distinct field; prefer reuse unless the note shows it cannot express a claim/basis pair.
    2. Which layer owns the stance (working_note, Handoff artifact, Topic Memory, or a documented split), and the explicit RFC 0014 compatibility argument. Proposal of a durable unverified entry requires owner approval.
    3. The exact field shape and the label string, which must not be UNVERIFIED because of Status1.UNVERIFIED.
    4. Whether the dashboard renderer needs a new ## section with bilingual CATALOGS[language] labels, or whether the JSON field alone is sufficient. Do not assume a Markdown section exists in the artifact.
    5. The cache-prefix boundary, behavior on missing/empty/malformed stance, the second-derivation guarantee, and the treatment of pre-existing artifacts.
    6. The frozen file set for Phase 2, chosen from the candidate list below. A design that only changes prompts.py cannot deliver a structured slot and must say so.

    "The existing surfaces are sufficient; standardize wording only" is a valid conclusion, provided the second-derivation and claim/basis requirements are still met or explicitly dropped by the owner.

  • Phase 2 (only after the owner accepts the Phase 1 note): changes limited to the file set frozen in the note. Candidates: builtin/artifacts/handoff/{models,generation,prompts,service}.py, builtin/artifacts/topic_memory/generation.py, builtin/dream/generation.py, server/dashboard/markdown.py (and its CATALOGS catalogs); focused behavior tests under tests/builtin/artifacts/handoff/, tests/builtin/artifacts/topic_memory/, tests/e2e/; matching English and Chinese documentation in the owning sections. Any module outside the frozen set requires a HOLD and a human decision.

  • Local edits, focused verification, and reporting are authorized. Commits, pushes, PR creation, merges, and GitHub comments beyond the design-note delivery require separate authorization.

Prohibited

  • Storing unverified speculation as a durable Atomic Memory / Topic Memory entry in violation of RFC 0014.
  • Rewriting, re-materializing, or backfilling historical Sources and Artifacts.
  • Reusing UNVERIFIED as the stance label, or mapping stance onto Status1.UNVERIFIED / ExtractionObservation.status.
  • Adding a global completeness/confidence flag to Memory, folding stance into MemoryEvidenceDeclaration authority/verification states (feat(memory): persist versioned Source evidence and neutral Atomic Memory projection #2004), or folding it into feat(capture): declare bounded projection coverage #2451 capture coverage.
  • Putting the rule into the system prompt, a persisted prefix, or any cached prefix.
  • Using stance as authority, verification, ranking weight, or access-control input; or letting a host-supplied string in the body set it.
  • Changing openapi/powercontext.yaml, generated clients, public DTOs, or the Receipt shape.
  • Claiming a structured slot was added while only prompt text changed; inventing a ## section in the artifact body that HandoffService.render() cannot produce.
  • Weakening an existing assertion, silently skipping a failing scenario, or claiming a stub-model run proves live-model behavior.

Verification and Acceptance

Scenario / risk Input and steps Expected result Environment Passing evidence
Qualified claim survives one derivation Handoff generation over a turn containing "probably / I suspect / unconfirmed" plus one confirmed fact Confirmed fact in the normal state; each uncertain claim in the agreed structured field as a claim + basis pair; no hypothesis restated as fact focused test, stub model test + output snapshot
Second derivation Feed the first derived summary into another derived pass Claim/basis pairs still present; no hardening, no disappearance focused test test
No hypotheses Turn with only settled facts Explicit empty marker in the agreed field; no fabricated hypothesis focused test test
Older artifact without the field Read/derive from a pre-change Handoff Accepted as-is, no retroactive rewrite, no parse failure focused test test
Evidence-gap vs hypothesis One unavailable-support case and one unverified-claim case They are distinguishable in the agreed shape; HandoffOmission's conflation is resolved or explicitly accepted focused test + note test + note section
Cache-prefix boundary Inspect the instruction surfaces at runtime Rule text appears only in the summary-generating prompt, never in the system prompt or a persisted prefix focused assertion diff/assertion
Name collision Search the label and Status1.UNVERIFIED Distinct tokens; the label never reaches an execution-status field focused test test
Stance is not authority Feed a labelled hypothesis through the extraction/verification path It changes no authority, verification, ranking, or access decision focused test test
Rendering surface Read HandoffService.render() and, if the note requires a section, handoff_markdown JSON field round-trips; a new ## section, if any, has both locale labels and is asserted through the real renderer focused test test
Prompt versioning Change the instruction text Version constant bumped consistently with the owning family's contract focused test test
RFC 0014 compatibility Read the design note Explicit cited argument including working_note; if a durable unverified field is proposed without owner approval, HOLD design review note section

Necessary checks, from the repository root:

uv run --locked pytest tests/builtin/artifacts/handoff/test_generation.py tests/builtin/artifacts/handoff/test_generation_metadata.py tests/builtin/artifacts/topic_memory/test_generation.py -q
uv run --locked pytest tests/e2e/test_handoff_prompt_provenance_api.py -q
uv run --locked ruff check <changed paths>
uv run --locked ruff format --check <changed paths>
git diff --check
  • This is a consistency/new-behavior task, not a bug fix, so no "failing baseline" regression pair is required. The Phase 1 note must still record the current behavior of all four existing surfaces on the qualified-claim fixture before any change.
  • Mock/real boundary: stub-model tests prove local schema, prompt and parse handling only. They do not prove a real summarizer emits claim/basis pairs. State this limit; do not claim live-model acceptance.
  • Missing environment: report BLOCKED with the command and output. Never substitute a silent skip for a passing result.

Two-Agent Checkpoints and Delivery

One coding agent (author of the note, then implementer after acceptance) and one independent verification agent in a separate context. The same pair may handle other tasks sequentially.

  • Kickoff: minimal plan, frozen contract-body hash, current SHA, the six Phase 1 decisions, the RFC 0014 conflict, and the case-sensitive grep evidence for the existing surfaces. The verification agent confirms the note will separate derived stance from durable entries and from Status1.UNVERIFIED.
  • Design checkpoint: the note and the frozen Phase 2 file set. The verification agent independently rules on the reuse decision, the rendering-surface claim, the name collision, and the "not authority" invariant. Implementation does not start before this feedback.
  • First verifiable slice (Phase 2): one family's schema/prompt change plus its regression fixture; the verification agent reads the actual diff and new files.
  • Delivery: final snapshot, tests, bilingual docs, remaining risks.

Each handoff carries the baseline SHA, diff, new-file inventory, contract-body hash, environment, commands, and raw-output locations. Direction and correctness are reported separately with CONTINUE / CORRECT / HOLD. HOLD is correct when the only viable design requires a durable unverified entry, a public API change, or a module outside the frozen file set. Passing a stage does not mean the whole task is accepted.

Delivery and Stop Conditions

Deliverables: the Phase 1 design note; Phase 2 (if accepted) the frozen-scope changes, focused tests, bilingual docs, and a short report. Save local evidence under untracked .powercontext/task-ISSUE/checkpoints/; do not commit runtime logs or real bodies by default.

Completion: the design note is accepted with an explicit RFC 0014 verdict and a frozen file set; every acceptance row is reported PASS / FAIL / BLOCKED / NOT_RUN against the final snapshot; no historical artifact was rewritten.

Stop and report rather than concluding if:

Publication of this Issue authorizes the design work only. It does not authorize an implementation PR, a commit, or a push.

Related tasks from the same review

This Issue is one of three tasks created from the 2026-11-09 cross-system memory review (Hermes 466591fe, Codex 8703d32b, PowerContext 2291237a). The other two are #2560 and #2561. They are not hard dependencies: each has its own baseline, file ownership and stop conditions, and may run in parallel where the stated start conditions allow.

Deliberately not turned into new Issues, after checking remote master and existing Issues:

Activity

  1. changed the title [-]feat(memory): design how derived summaries keep unverified hypotheses labelled[/-] [+]feat(memory): reconcile existing uncertainty surfaces into one compression-stable stance contract[/+] on Nov 9, 2026
  2. zzstar101 commented on Nov 9, 2026

    @zzstar101
    Contributor

    assign me plz

  3. AlexStocks commented on Nov 9, 2026

    @AlexStocks
    ContributorAuthor

    assign me plz

    done. thx for your enthusiam for pc.

  4. zzstar101 commented on Nov 9, 2026

    @zzstar101
    Contributor

    Design Note — #2559: Minimal Structured Uncertainty Contract

    Proposal and decisions required from the owner

    The objective is: context compression must not lose an existing hypothesis and its basis, or incorrectly promote a hypothesis into a fact. This task does not establish a hypothesis lifecycle, automatic closure, or verification system.

    Reuse HandoffOmission, adding only kind and basis. Handoff owns uncertainty needed for continuity; this proposal does not introduce new admission rules for speculative durable Atomic Memory or Topic Memory entries.

    Implementation status: HOLD. The following decisions require explicit owner approval:

    1. Allow the minimum public-field extension? The existing public HandoffOmission schema is a closed object. Changing only the internal model cannot leave the HTTP contract unchanged. The requested exception covers only kind/basis and the necessary generated-contract and HTTP-mapping synchronization; it does not pre-commit to Handoff v2 or a comprehensive client migration. Optional fields support new readers reading old data; they do not guarantee that old strict clients can read new fields. If this exception is rejected, the conflict between the structured goal and the public-contract freeze remains unresolved. Encoding a mini-format in text or changing prompts alone must not be presented as completion.
    2. Accept ordinary Handoff as the first implementation slice? First validate the minimal ordinary Handoff → Handoff path. Section 2 explains the relationship with Dream and Topic. Uncovered acceptance requirements do not become passing requirements, and this slice alone does not complete feat(memory): reconcile existing uncertainty surfaces into one compression-stable stance contract #2559. The owner may explicitly revise the issue scope or retain the other paths as required subsequent work.
    3. Approve the minimal conditional file set in Section 5? Public-contract files become eligible only after approval of item 1. Discovering another necessary file triggers HOLD and a new scope decision, not automatic expansion.

    No closure, supported/contradicted assessment states, persisted counter, global hypothesis IDs, historical resurrection detection, special Dream target-citation rules, or Dashboard grouping is introduced. This note reports no production changes, implementation authorization, or passing feature acceptance.

    1. Fields, empty results, and legacy data

    Proposed shape:

    class HandoffOmission:
        text: str
        citation: HandoffCitation | None
        kind: Literal["working_hypothesis", "evidence_gap"] | None
        basis: str | None
    • Preserve existing text/citation. For a hypothesis, text is the claim; do not introduce a duplicate hypothesis list.
    • Newly generated output must provide kind. A working_hypothesis requires a nonempty basis; an evidence_gap may omit it. Generation must validate the new fields rather than silently ignore and discard them.
    • If the source provides no supporting reason, the basis explicitly states “No supporting basis was supplied in the source.” Do not invent a reason. A citation locates the source; it is neither proof nor confidence.
    • Legacy reads allow missing kind/basis and retain an unclassified state. Do not infer evidence_gap or “no hypotheses.” No backfill, rematerialization, or changes to historical Artifact identity, body, or generation metadata. Reserializing legacy content must not inadvertently add new default fields and change its existing representation.
    • Newly generated output must explicitly include omissions, including [] when empty. When all entries are classified, no working_hypothesis entries means that this result records no hypotheses; no redundant counter is persisted. Historical results containing unclassified entries remain unknown, not zero hypotheses.
    • Reject new output with a missing kind, an empty/missing hypothesis basis, or an unknown category. Invalid new output must not fall back to legacy handling. Reading valid historical content and validating new generation are distinct boundaries.
    • This proposes only the minimum optional-field extension; public-contract version treatment remains an owner decision. No v2 upgrade is pre-approved. The new fields remain subject to existing text, item-count, and total-byte budgets; no unbounded input is introduced.

    2. Ownership, RFC 0014, and existing uncertainty surfaces

    Surface Existing behavior and treatment
    Handoff omission / generation Existing omission and uncertainty instructions lack a separate basis. Ordinary Handoff is the first structured end-to-end slice.
    Topic Memory Existing prompts preserve uncertainty, negation, and status; content remains title/summary/detail. The first slice does not change its production model or promise structured-pair preservation through Topic reduction.
    Dream revise_topic_memory distinguishes hypotheses; refresh_handoff uses Handoff content. Dream is not a separate storage family, and refresh is not the ordinary generation path. Compatibility must be tested; its structured-preservation guarantee requires a separately assessed slice, without introducing Review exceptions.
    working_note / RFC 0014 Durable entries prohibit unverified speculation. working_note is an ordinary kind for short-term progress, not an ephemeral-storage exemption or a way around that prohibition.

    The issue body's working_note names two distinct mechanisms, and this note reads RFC 0014:531 as the second one. The entry kind is the Atomic Memory kind at atomic_memory/extraction.py:141 (kind: Literal["fact", "preference", "decision", "constraint", "working_note"]); it is not a ContentSource flag and it does not relax RFC 0014 admission.

    The ContentSource flag is separate and already constrains the generation path in the direction this contract needs. content.py:101 declares working_note: bool = False, and is_working_note_active() reads metadata["expires_at"]. source_eligibility.py:47-57 has is_generation_eligible() end in return not source.is_working_note, so a working-note Source is excluded from every ordinary Source window and cannot reach a summary request at all. The write path is equally explicit: persistence/artifacts.py:167,188 defaults allow_working_notes: bool = False, and source_eligibility.py:60-77 only admits a working note when that flag is passed and is_working_note_active() holds, otherwise raising SourceNotEligibleError or WorkingNoteUnavailableError.

    The one place that opts in is Handoff's own citation resolution, which passes allow_working_notes=True at persistence/handoff.py:69,82,162. That is a citation path, not a generation window: it lets a Handoff point at a working note it was explicitly given, and it cannot make a working note enter a summary input as evidence. So the §7 gap closes in the safe direction — stance carried by a working note cannot reach a second derivation through the ordinary generation path — while the citation path is the one that needs an explicit decision if this contract ever has to preserve stance across it.

    Storing continuity information in a Handoff Artifact does not promote it to a durable Memory fact. RFC 0014 admission rules remain unchanged; the owner must still confirm this ownership boundary.

    Use working_hypothesis, not the execution status Status1.UNVERIFIED. Stance must not affect authority, verification, ranking, access control, EvidenceManifest.incomplete, MemoryEvidenceDeclaration, or Source capture coverage. Matching strings in a host body do not directly set structured fields, much less confer authority.

    3. Minimal deterministic guarantee across two derivations

    Fixed fixture:

    I suspect the offset is 12 degrees, not confirmed
    The calibration file is named calibration.json.
    

    First derivation: the settled fact belongs in ordinary state; the hypothesis belongs in a working_hypothesis omission with a separate basis. If no reason was supplied, record that absence explicitly.

    Second derivation: use the first structured Handoff as explicit input for pure compression / continuity preservation. For each existing input hypothesis, runtime checks that the original text/basis remains intact in an output entry of the same kind. Tests cover rejection of deletion, kind changes, missing basis, and pair rewriting. Identical pairs are checked with multiplicity; fuzzy semantic matching must not silently merge entries. Citations remain limited to evidence allowed in the current request; existing citation-mapping rules are not relaxed.

    Exact comparison provides a reproducible deterministic guard for this pure-compression path; it does not declare hypothesis strings permanently immutable. Refinement, merging, confirmation, or contradiction based on new evidence is outside this contract. The summarizer must not silently perform those updates, and no automatic closure mechanism is added. If semantic revision is required in this issue, its acceptance criteria must be specified first rather than substituting an unverified “semantic equivalence” claim for the comparison.

    No history scan or multi-version lifecycle is introduced. If the input cannot be unambiguously associated with the predecessor for this operation, or requires hypothesis revision, report the unsupported case or request a scope decision instead of inferring lifecycle rules.

    Use existing failure/budget mechanisms for invalid output. No unbounded retries or new correction system. Never silently truncate pairs, invent bases, or commit partial success.

    Guarantee boundary: structural checks preserve pairs already present in the input. They do not prove complete first-pass extraction or that free-form output never paraphrases a hypothesis as a fact elsewhere. The two-pass fixture should include such incorrect output, but stub tests cannot establish real-model semantic reliability.

    4. Prompts, provenance, and presentation

    • Handoff owns the new rules. Place them in each summary request's input, not fixed instructions, system prompts, fixed Prompt Artifact demonstrations, or application-maintained cached prefixes. Rules must not come from the host body.
    • The seam for that is smaller than §5's file set may suggest, and it already exists. The generic generator accepts input_renderer: Callable[[InputT], str] | None = None at pydantic_ai.py:302 and applies it instead of model_dump_json() at pydantic_ai.py:379-383. The memory generators already pass it (composition.py:1704, :1716); the Handoff generator at composition.py:1774-1783 does not. So the wiring is one added argument at the composition site.
    • That also removes one file from the necessary set. LLMHandoffGenerationPipeline.init takes only generator and evidence_projector and needs no change for the injection; handoff/generation.py changes stay confined to the DTO. composition.py is the only mandatory file for this half. Avoiding one wiring file is not a reason to insert rules into demonstration inputs that may be persisted.
    • Bump Handoff generation and the necessary Prompt definition versions. Test actual message placement and provenance for Auto/custom Prompts; do not change Receipt shape. Schema/version changes may affect the provider's effective cache; zero invalidation is not promised.
    • Service rendering remains JSON, and the structured fields are this slice's presentation contract. No new Dashboard Markdown groups are included. Existing Markdown export is not claimed to be a complete stance display. Human-visible sections would require a separate, explicit renderer and bilingual-catalog scope decision.

    5. Minimal conditional file set

    This is a proposed allowlist, not authorization to edit, nor a requirement that every file produce a diff. Domain rules stay in Handoff. Additional files synchronize existing boundaries rather than introduce a new framework.

    Core

    src/powercontext/builtin/artifacts/handoff/models.py
    src/powercontext/builtin/artifacts/handoff/generation.py
    src/powercontext/builtin/artifacts/handoff/prompts.py
    src/powercontext/builtin/artifacts/handoff/service.py
    

    Necessary adaptation at existing boundaries

    Exact file, linked at the analyzed commit Necessity and limit
    server/mapping.py Currently reconstructs omissions field by field, passing only text/citation. If the public extension is approved, kind/basis must survive mapping while legacy representation is preserved. Internal-model and generated-DTO changes alone cannot ensure an HTTP round trip.
    prompt/validation.py Existing demonstration validation reconstructs a domain Draft with only text/citation. Propagate the fields so validation does not substitute stripped content for the actual new output. Do not expand the validation framework.
    runtime/composition.py Pass the existing input_renderer to the Handoff generator: one added argument carrying Handoff-owned per-request rules. Actual message-placement tests must establish the behavior and cache boundary; no new pipeline, no change to the generic inference framework.
    prompt/builtin.py Synchronize the Handoff Prompt definition version without adding the new rules to the fixed instruction prefix.

    Eligible only after approval of the public-contract exception

    openapi/powercontext.yaml
    src/powercontext/http/_generated/models.py
    src/powercontext/http/_generated/schema.py
    src/powercontext/http/_generated/operations.py
    

    Update generated files only through make api-generate, never by hand. No standalone closure type or associated export chain. If the owner selects a different versioning approach or generation requires additional files, freeze the scope again before proceeding.

    Focused tests and owning documentation

    tests/builtin/artifacts/handoff/test_models.py
    tests/builtin/artifacts/handoff/test_generation.py
    tests/builtin/artifacts/handoff/test_generation_metadata.py
    tests/builtin/artifacts/handoff/test_service.py
    tests/builtin/artifacts/prompt/test_prompt_validation.py
    tests/e2e/test_handoff_prompt_provenance_api.py
    tests/e2e/test_handoff_runtime.py
    tests/test_api_contract.py
    docs/en/rfcs/0048_handoff_artifact.md
    docs/zh/rfcs/0048_handoff_artifact.md
    

    No production changes to Dream/Review/Topic, Dashboard, generic inference, persistence, Receipt, capture/retrieval, or authorization modules. Relevant existing tests must still run. If the shared-model change breaks those paths, HOLD: neither ignore the failures nor silently expand the allowlist.

    6. Acceptance and current status

    Acceptance item Current status and boundary
    New kind/basis; distinguish evidence gaps from hypotheses NOT_RUN: not implemented
    Structured preservation through the fixture's first and second derivations NOT_RUN: implementation acceptance target; baseline observations are below
    Explicit empty list and unknown legacy entries NOT_RUN; no counter or backfill
    Reject malformed new output; no silent budget truncation NOT_RUN
    Legacy reads/serialization, HTTP round trip, persistence and subsequent reuse NOT_RUN
    Rule text present in the rendered user message, for Auto and custom Prompts alike NOT_RUN; must be asserted on the request actually sent, downstream of the instruction override
    Prompt identity and version bumped for both fields the Receipt reports NOT_RUN
    Non-authority semantics and forged body markers NOT_RUN
    Topic/Dream cross-family structured preservation NOT_RUN; outside the first slice, not grounds for closing the issue
    RFC ownership, public contract, versioning, and frozen file set HOLD: owner decisions pending
    Real-model fidelity NOT_RUN; stubs do not substitute

    The prompt row splits because one row cannot fail correctly. A custom Prompt replaces the constructor instructions: pydantic_ai.py:391-397 applies Agent.override(instructions=selection.compiled_instructions), and for a Scope-owned Prompt prompt/definitions.py:106-112 compiles invariant instructions plus Scope guidance, dropping default_instructions. So the v2 wording at handoff/prompts.py:36 ("Record relevant uncertainty or unavailable support as an omission") never reaches a custom-Prompt Scope; those Scopes see the invariant text at prompt/builtin.py:212 ("Record uncertainty as omissions"). Asserting instruction text alone would therefore pass for Auto and silently prove nothing for custom Prompts. Asserting the rendered user message passes for both, because the input_renderer seam is applied regardless of which instructions win.

    The version row names both fields. The compiled digest binds compiler_version, definition_version, and builtin_version (prompt/definitions.py:113-120); the Receipt reports the latter two (receipt_builder.py:92-105). Bumping only the definition version leaves a stale builtin version reported next to changed behavior.

    After implementation is approved, run at least:

    uv run --locked pytest tests/builtin/artifacts/handoff/test_generation.py tests/builtin/artifacts/handoff/test_generation_metadata.py tests/builtin/artifacts/topic_memory/test_generation.py -q
    uv run --locked pytest tests/e2e/test_handoff_prompt_provenance_api.py -q
    uv run --locked pytest tests/builtin/artifacts/handoff tests/builtin/artifacts/prompt/test_prompt_validation.py tests/e2e/test_handoff_runtime.py -q
    uv run --locked pytest tests/builtin/dream/test_models.py tests/e2e/test_artifact_dreaming.py -q
    make api-generate
    make contract-test
    uv run --locked ruff check <changed-python-paths>
    uv run --locked ruff format --check <changed-python-paths>
    git diff --check

    Generation and contract commands are conditional on approval of the public-contract exception. Passing Dream regression tests would establish only the existing behavior they cover, not its stance-preservation acceptance.

    7. Executed Phase 1 baseline evidence

    Analysis is pinned to upstream 63f021d6103c782f325dc917ca5cb7c9a3f3fafd; the issue's original baseline is 2291237a7809410ea0dc8f19f2de149573af8378. The comparison for relevant Handoff/Topic/Dream, RFC 0014, Dashboard Markdown, and OpenAPI files was empty. The frozen issue-body SHA-256 is 7a98dc2e0eafa8312a2fc227009410390738057c7c6666f36516a4860db756ce. The older working branch was neither switched nor reset.

    Findings

    • 21 supplemental probe checks PASS; exit code 0. These assertions confirm current behavior, not passing acceptance of the proposed feature.
    • The ordinary Handoff pipeline from the frozen source accepted all three scripted second-pass outputs: preserving the hypothesis, dropping the omission, and restating the offset as a settled fact. Structured claim/basis capability and deterministic preservation at that tested boundary are therefore FAIL.
    • Handoff generation omissions ignore unknown kind/basis fields, while the persisted-content model rejects them. The Topic generation proposal rejects the added structure, while bare content ignores unknown structure; existing prose outputs admit the three variants. Dream's operation validator also admits the three Topic prose variants.
    • The Handoff probe executed the real pipeline and JSON render/parse, but not commit. Its first pass used the supported custom-projector interface to expose the fixture body; its second pass used default full-Artifact projection. This is not a claim about production Source projection, which has a separate registry projector.
    • Topic execution covered input/output schemas only; Dream execution covered the operation validator only. No complete Topic/Dream service or live model ran. The working_note probe itself covered RFC policy text only; the runtime admission and rejection behavior it did not exercise is now read from source in §2 (content.py:101, source_eligibility.py:47-57 and :60-77, persistence/artifacts.py:167,188, persistence/handoff.py:69,82,162). That closes the gap by reading the frozen code, not by executing it, and it is not a substitute for the write-path tests this slice would add.

    Commands, environment, and raw evidence

    Local evidence is stored under the repository root at these paths. It has not been uploaded; GitHub reviewers are not assumed to have access to it:

    .powercontext/task-2559/checkpoints/baseline-probe/report.md
    .powercontext/task-2559/checkpoints/baseline-probe/probe.py
    .powercontext/task-2559/checkpoints/baseline-probe/results.json
    .powercontext/task-2559/checkpoints/baseline-probe/probe-run2.log
    .powercontext/task-2559/checkpoints/baseline-probe/environment-sync.log
    .powercontext/task-2559/checkpoints/baseline-probe/final-verification.log
    

    The working directory was frozen under that evidence directory, containing a complete git archive of the SHA above. Locked-environment attempt:

    uv sync --locked --offline --no-default-groups --no-install-project \
      --cache-dir /Users/zzstar/Developer/Programs/powercontext/.powercontext/task-2559/checkpoints/baseline-probe/uv-cache

    Exit code 1; BLOCKED. Error excerpts:

    Failed to download jsonschema==4.26.0
    Network connectivity is disabled, but the requested data wasn't found in the cache
    

    Supplemental execution:

    PYTHONDONTWRITEBYTECODE=1 \
    PYTHONPATH="$PWD/src:/Users/zzstar/.cache/uv/archive-v0/hnDthDthit1JQPkY:/Users/zzstar/.cache/uv/archive-v0/5HGDCJeML1SlwwDo" \
    python3 ../probe.py

    Exit code 0. Condensed interpretation of the recorded results, not a verbatim raw-JSON excerpt:

    Observation Result
    Supplemental current-behavior checks 21 PASS
    Baseline structured claim/basis capability FAIL
    Baseline deterministic second-derivation preservation FAIL
    Locked execution BLOCKED
    Real-model fidelity NOT_RUN
    Storage commit and complete Dream service NOT_RUN

    The supplemental environment used CPython 3.13.13; it was not a locked-environment PASS. Principal dependency deviations, actual / lock: Pydantic 2.13.3 / 2.13.4; pydantic-core 2.46.3 / 2.46.4; typing-extensions 4.15.0 / 4.16.0; rpds-py 0.30.0 / 2026.6.3; opentelemetry-api 1.44.0 / 1.45.2. All PowerContext imports were checked against the frozen source. No live-model or network calls were made by the probe.

    Independent checkpoints and dependency refresh

    An independent kickoff review and a bounded independent review of this minimal design have completed. The design review found no material blocker to publication as an owner-decision request: direction CONTINUE, correctness CONTINUE for that proposal purpose, and implementation HOLD. It was a static review of the known boundaries, not exhaustive implementation-feasibility verification or whole-issue acceptance. The first implementation slice and final delivery still require the independent checkpoints specified by the issue.

    PRs #2539 and #2527 were both OPEN at kickoff; their actual file lists did not directly occupy the initial Handoff/Topic/Dream candidate modules at that time. Refresh master, PR file lists, and ownership before implementation. This snapshot is not a permanent no-conflict guarantee.

    Requested owner response: approve or reject the minimum public-contract exception and its version treatment, confirm the RFC ownership boundary and first-slice/remaining-acceptance scope, and approve the conditional file set before implementation begins.

  5. zzstar101 commented on Nov 10, 2026

    @zzstar101
    Contributor

    Design Note — #2559: Minimal Structured Uncertainty Contract

    Proposal and decisions required from the owner

    The objective is: context compression must not lose an existing hypothesis and its basis, or incorrectly promote a hypothesis into a fact. This task does not establish a hypothesis lifecycle, automatic closure, or verification system.

    Reuse HandoffOmission, adding only kind and basis. Handoff owns uncertainty needed for continuity; this proposal does not introduce new admission rules for speculative durable Atomic Memory or Topic Memory entries.

    Implementation status: HOLD. The following decisions require explicit owner approval:

    1. Allow the minimum public-field extension? The existing public HandoffOmission schema is a closed object. Changing only the internal model cannot leave the HTTP contract unchanged. The requested exception covers only kind/basis and the necessary generated-contract and HTTP-mapping synchronization; it does not pre-commit to Handoff v2 or a comprehensive client migration. Optional fields support new readers reading old data; they do not guarantee that old strict clients can read new fields. If this exception is rejected, the conflict between the structured goal and the public-contract freeze remains unresolved. Encoding a mini-format in text or changing prompts alone must not be presented as completion.
    2. Accept ordinary Handoff as the first implementation slice? First validate the minimal ordinary Handoff → Handoff path. Section 2 explains the relationship with Dream and Topic. Uncovered acceptance requirements do not become passing requirements, and this slice alone does not complete feat(memory): reconcile existing uncertainty surfaces into one compression-stable stance contract #2559. The owner may explicitly revise the issue scope or retain the other paths as required subsequent work.
    3. Approve the minimal conditional file set in Section 5? Public-contract files become eligible only after approval of item 1. Discovering another necessary file triggers HOLD and a new scope decision, not automatic expansion.

    No closure, supported/contradicted assessment states, persisted counter, global hypothesis IDs, historical resurrection detection, special Dream target-citation rules, or Dashboard grouping is introduced. This note reports no production changes, implementation authorization, or passing feature acceptance.

    1. Fields, empty results, and legacy data

    Proposed shape:

    class HandoffOmission:
    text: str
    citation: HandoffCitation | None
    kind: Literal["working_hypothesis", "evidence_gap"] | None
    basis: str | None

    • Preserve existing text/citation. For a hypothesis, text is the claim; do not introduce a duplicate hypothesis list.
    • Newly generated output must provide kind. A working_hypothesis requires a nonempty basis; an evidence_gap may omit it. Generation must validate the new fields rather than silently ignore and discard them.
    • If the source provides no supporting reason, the basis explicitly states “No supporting basis was supplied in the source.” Do not invent a reason. A citation locates the source; it is neither proof nor confidence.
    • Legacy reads allow missing kind/basis and retain an unclassified state. Do not infer evidence_gap or “no hypotheses.” No backfill, rematerialization, or changes to historical Artifact identity, body, or generation metadata. Reserializing legacy content must not inadvertently add new default fields and change its existing representation.
    • Newly generated output must explicitly include omissions, including [] when empty. When all entries are classified, no working_hypothesis entries means that this result records no hypotheses; no redundant counter is persisted. Historical results containing unclassified entries remain unknown, not zero hypotheses.
    • Reject new output with a missing kind, an empty/missing hypothesis basis, or an unknown category. Invalid new output must not fall back to legacy handling. Reading valid historical content and validating new generation are distinct boundaries.
    • This proposes only the minimum optional-field extension; public-contract version treatment remains an owner decision. No v2 upgrade is pre-approved. The new fields remain subject to existing text, item-count, and total-byte budgets; no unbounded input is introduced.

    2. Ownership, RFC 0014, and existing uncertainty surfaces

    Surface Existing behavior and treatment
    Handoff omission / generation Existing omission and uncertainty instructions lack a separate basis. Ordinary Handoff is the first structured end-to-end slice.
    Topic Memory Existing prompts preserve uncertainty, negation, and status; content remains title/summary/detail. The first slice does not change its production model or promise structured-pair preservation through Topic reduction.
    Dream revise_topic_memory distinguishes hypotheses; refresh_handoff uses Handoff content. Dream is not a separate storage family, and refresh is not the ordinary generation path. Compatibility must be tested; its structured-preservation guarantee requires a separately assessed slice, without introducing Review exceptions.
    working_note / RFC 0014 Durable entries prohibit unverified speculation. working_note is an ordinary kind for short-term progress, not an ephemeral-storage exemption or a way around that prohibition.
    Storing continuity information in a Handoff Artifact does not promote it to a durable Memory fact. RFC 0014 admission rules remain unchanged; the owner must still confirm this ownership boundary.

    Use working_hypothesis, not the execution status Status1.UNVERIFIED. Stance must not affect authority, verification, ranking, access control, EvidenceManifest.incomplete, MemoryEvidenceDeclaration, or Source capture coverage. Matching strings in a host body do not directly set structured fields, much less confer authority.

    3. Minimal deterministic guarantee across two derivations

    Fixed fixture:

    I suspect the offset is 12 degrees, not confirmed
    The calibration file is named calibration.json.
    

    First derivation: the settled fact belongs in ordinary state; the hypothesis belongs in a working_hypothesis omission with a separate basis. If no reason was supplied, record that absence explicitly.

    Second derivation: use the first structured Handoff as explicit input for pure compression / continuity preservation. For each existing input hypothesis, runtime checks that the original text/basis remains intact in an output entry of the same kind. Tests cover rejection of deletion, kind changes, missing basis, and pair rewriting. Identical pairs are checked with multiplicity; fuzzy semantic matching must not silently merge entries. Citations remain limited to evidence allowed in the current request; existing citation-mapping rules are not relaxed.

    Exact comparison provides a reproducible deterministic guard for this pure-compression path; it does not declare hypothesis strings permanently immutable. Refinement, merging, confirmation, or contradiction based on new evidence is outside this contract. The summarizer must not silently perform those updates, and no automatic closure mechanism is added. If semantic revision is required in this issue, its acceptance criteria must be specified first rather than substituting an unverified “semantic equivalence” claim for the comparison.

    No history scan or multi-version lifecycle is introduced. If the input cannot be unambiguously associated with the predecessor for this operation, or requires hypothesis revision, report the unsupported case or request a scope decision instead of inferring lifecycle rules.

    Use existing failure/budget mechanisms for invalid output. No unbounded retries or new correction system. Never silently truncate pairs, invent bases, or commit partial success.

    Guarantee boundary: structural checks preserve pairs already present in the input. They do not prove complete first-pass extraction or that free-form output never paraphrases a hypothesis as a fact elsewhere. The two-pass fixture should include such incorrect output, but stub tests cannot establish real-model semantic reliability.

    4. Prompts, provenance, and presentation

    • Handoff owns the new rules. Place them in each summary request's input, not fixed instructions, system prompts, fixed Prompt Artifact demonstrations, or application-maintained cached prefixes. Rules must not come from the host body.
    • The existing adapter supports input_renderer, and runtime constructs the Handoff generator here. If this existing interface is used, limit changes to minimal wiring; do not change the generic inference framework. Avoiding one wiring file is not a reason to insert rules into demonstration inputs that may be persisted.
    • Bump Handoff generation and the necessary Prompt definition versions. Test actual message placement and provenance for Auto/custom Prompts; do not change Receipt shape. Schema/version changes may affect the provider's effective cache; zero invalidation is not promised.
    • Service rendering remains JSON, and the structured fields are this slice's presentation contract. No new Dashboard Markdown groups are included. Existing Markdown export is not claimed to be a complete stance display. Human-visible sections would require a separate, explicit renderer and bilingual-catalog scope decision.

    5. Minimal conditional file set

    This is a proposed allowlist, not authorization to edit, nor a requirement that every file produce a diff. Domain rules stay in Handoff. Additional files synchronize existing boundaries rather than introduce a new framework.

    Core

    src/powercontext/builtin/artifacts/handoff/models.py
    src/powercontext/builtin/artifacts/handoff/generation.py
    src/powercontext/builtin/artifacts/handoff/prompts.py
    src/powercontext/builtin/artifacts/handoff/service.py
    

    Necessary adaptation at existing boundaries

    Exact file, linked at the analyzed commit Necessity and limit
    server/mapping.py Currently reconstructs omissions field by field, passing only text/citation. If the public extension is approved, kind/basis must survive mapping while legacy representation is preserved. Internal-model and generated-DTO changes alone cannot ensure an HTTP round trip.
    prompt/validation.py Existing demonstration validation reconstructs a domain Draft with only text/citation. Propagate the fields so validation does not substitute stripped content for the actual new output. Do not expand the validation framework.
    runtime/composition.py If the existing input_renderer seam is used, wire only Handoff-owned per-request rules. Actual message-placement tests must establish the behavior and cache boundary; no new pipeline.
    prompt/builtin.py Synchronize the Handoff Prompt definition version without adding the new rules to the fixed instruction prefix.

    Eligible only after approval of the public-contract exception

    openapi/powercontext.yaml
    src/powercontext/http/_generated/models.py
    src/powercontext/http/_generated/schema.py
    src/powercontext/http/_generated/operations.py
    

    Update generated files only through make api-generate, never by hand. No standalone closure type or associated export chain. If the owner selects a different versioning approach or generation requires additional files, freeze the scope again before proceeding.

    Focused tests and owning documentation

    tests/builtin/artifacts/handoff/test_models.py
    tests/builtin/artifacts/handoff/test_generation.py
    tests/builtin/artifacts/handoff/test_generation_metadata.py
    tests/builtin/artifacts/handoff/test_service.py
    tests/builtin/artifacts/prompt/test_prompt_validation.py
    tests/e2e/test_handoff_prompt_provenance_api.py
    tests/e2e/test_handoff_runtime.py
    tests/test_api_contract.py
    docs/en/rfcs/0048_handoff_artifact.md
    docs/zh/rfcs/0048_handoff_artifact.md
    

    No production changes to Dream/Review/Topic, Dashboard, generic inference, persistence, Receipt, capture/retrieval, or authorization modules. Relevant existing tests must still run. If the shared-model change breaks those paths, HOLD: neither ignore the failures nor silently expand the allowlist.

    6. Acceptance and current status

    Acceptance item Current status and boundary
    New kind/basis; distinguish evidence gaps from hypotheses NOT_RUN: not implemented
    Structured preservation through the fixture's first and second derivations NOT_RUN: implementation acceptance target; baseline observations are below
    Explicit empty list and unknown legacy entries NOT_RUN; no counter or backfill
    Reject malformed new output; no silent budget truncation NOT_RUN
    Legacy reads/serialization, HTTP round trip, persistence and subsequent reuse NOT_RUN
    Auto/custom Prompt placement, versions, and provenance NOT_RUN
    Non-authority semantics and forged body markers NOT_RUN
    Topic/Dream cross-family structured preservation NOT_RUN; outside the first slice, not grounds for closing the issue
    RFC ownership, public contract, versioning, and frozen file set HOLD: owner decisions pending
    Real-model fidelity NOT_RUN; stubs do not substitute
    After implementation is approved, run at least:

    uv run --locked pytest tests/builtin/artifacts/handoff/test_generation.py tests/builtin/artifacts/handoff/test_generation_metadata.py tests/builtin/artifacts/topic_memory/test_generation.py -q
    uv run --locked pytest tests/e2e/test_handoff_prompt_provenance_api.py -q
    uv run --locked pytest tests/builtin/artifacts/handoff tests/builtin/artifacts/prompt/test_prompt_validation.py tests/e2e/test_handoff_runtime.py -q
    uv run --locked pytest tests/builtin/dream/test_models.py tests/e2e/test_artifact_dreaming.py -q
    make api-generate
    make contract-test
    uv run --locked ruff check
    uv run --locked ruff format --check
    git diff --check
    Generation and contract commands are conditional on approval of the public-contract exception. Passing Dream regression tests would establish only the existing behavior they cover, not its stance-preservation acceptance.

    7. Executed Phase 1 baseline evidence

    Analysis is pinned to upstream 63f021d6103c782f325dc917ca5cb7c9a3f3fafd; the issue's original baseline is 2291237a7809410ea0dc8f19f2de149573af8378. The comparison for relevant Handoff/Topic/Dream, RFC 0014, Dashboard Markdown, and OpenAPI files was empty. The frozen issue-body SHA-256 is 7a98dc2e0eafa8312a2fc227009410390738057c7c6666f36516a4860db756ce. The older working branch was neither switched nor reset.

    Findings

    • 21 supplemental probe checks PASS; exit code 0. These assertions confirm current behavior, not passing acceptance of the proposed feature.
    • The ordinary Handoff pipeline from the frozen source accepted all three scripted second-pass outputs: preserving the hypothesis, dropping the omission, and restating the offset as a settled fact. Structured claim/basis capability and deterministic preservation at that tested boundary are therefore FAIL.
    • Handoff generation omissions ignore unknown kind/basis fields, while the persisted-content model rejects them. The Topic generation proposal rejects the added structure, while bare content ignores unknown structure; existing prose outputs admit the three variants. Dream's operation validator also admits the three Topic prose variants.
    • The Handoff probe executed the real pipeline and JSON render/parse, but not commit. Its first pass used the supported custom-projector interface to expose the fixture body; its second pass used default full-Artifact projection. This is not a claim about production Source projection, which has a separate registry projector.
    • Topic execution covered input/output schemas only; Dream execution covered the operation validator only. No complete Topic/Dream service or live model ran. The working_note check covered RFC policy text, not runtime admission/rejection behavior.

    Commands, environment, and raw evidence

    Local evidence is stored under the repository root at these paths. It has not been uploaded; GitHub reviewers are not assumed to have access to it:

    .powercontext/task-2559/checkpoints/baseline-probe/report.md
    .powercontext/task-2559/checkpoints/baseline-probe/probe.py
    .powercontext/task-2559/checkpoints/baseline-probe/results.json
    .powercontext/task-2559/checkpoints/baseline-probe/probe-run2.log
    .powercontext/task-2559/checkpoints/baseline-probe/environment-sync.log
    .powercontext/task-2559/checkpoints/baseline-probe/final-verification.log
    

    The working directory was frozen under that evidence directory, containing a complete git archive of the SHA above. Locked-environment attempt:

    uv sync --locked --offline --no-default-groups --no-install-project
    --cache-dir /Users/zzstar/Developer/Programs/powercontext/.powercontext/task-2559/checkpoints/baseline-probe/uv-cache
    Exit code 1; BLOCKED. Error excerpts:

    Failed to download jsonschema==4.26.0
    Network connectivity is disabled, but the requested data wasn't found in the cache
    

    Supplemental execution:

    PYTHONDONTWRITEBYTECODE=1
    PYTHONPATH="$PWD/src:/Users/zzstar/.cache/uv/archive-v0/hnDthDthit1JQPkY:/Users/zzstar/.cache/uv/archive-v0/5HGDCJeML1SlwwDo"
    python3 ../probe.py
    Exit code 0. Condensed interpretation of the recorded results, not a verbatim raw-JSON excerpt:

    Observation Result
    Supplemental current-behavior checks 21 PASS
    Baseline structured claim/basis capability FAIL
    Baseline deterministic second-derivation preservation FAIL
    Locked execution BLOCKED
    Real-model fidelity NOT_RUN
    Storage commit and complete Dream service NOT_RUN
    The supplemental environment used CPython 3.13.13; it was not a locked-environment PASS. Principal dependency deviations, actual / lock: Pydantic 2.13.3 / 2.13.4; pydantic-core 2.46.3 / 2.46.4; typing-extensions 4.15.0 / 4.16.0; rpds-py 0.30.0 / 2026.6.3; opentelemetry-api 1.44.0 / 1.45.2. All PowerContext imports were checked against the frozen source. No live-model or network calls were made by the probe.

    Independent checkpoints and dependency refresh

    An independent kickoff review and a bounded independent review of this minimal design have completed. The design review found no material blocker to publication as an owner-decision request: direction CONTINUE, correctness CONTINUE for that proposal purpose, and implementation HOLD. It was a static review of the known boundaries, not exhaustive implementation-feasibility verification or whole-issue acceptance. The first implementation slice and final delivery still require the independent checkpoints specified by the issue.

    PRs #2539 and #2527 were both OPEN at kickoff; their actual file lists did not directly occupy the initial Handoff/Topic/Dream candidate modules at that time. Refresh master, PR file lists, and ownership before implementation. This snapshot is not a permanent no-conflict guarantee.

    Requested owner response: approve or reject the minimum public-contract exception and its version treatment, confirm the RFC ownership boundary and first-slice/remaining-acceptance scope, and approve the conditional file set before implementation begins.

    @AlexStocks I've completed the design notes. Please review them

  6. AlexStocks commented on Nov 12, 2026

    @AlexStocks
    ContributorAuthor

    Checked the design note's load-bearing seams at 63f021d6. Everything it claims about server/mapping.py, prompt/validation.py and the Handoff construction site holds. Three additions — one closes the runtime evidence gap the note itself flags, two tighten scope and acceptance.

    1. Runtime evidence for working_note (the gap §7 says was not collected)

    §7 says the working_note check covered RFC policy text, "not runtime admission/rejection behavior". Here is that side, verified on 63f021d6:

    • sources/content.py:101 — working_note: bool = False; is_working_note_active() reads metadata["expires_at"].
    • source_eligibility.py:47-57 — is_generation_eligible() returns not source.is_working_note. A working-note Source is excluded from the generation path entirely, not just from promotion.
    • Write path — allow_working_notes must be enabled (default False) and the entry must still be unexpired (source_eligibility.py:60-77, persistence/artifacts.py:167,188).

    This matters because it turns the note's implicit choice into a proven one: the Source flag cannot be the stance carrier, since an entry carrying it never reaches the second derivation, which is exactly the guarantee §3 requires. Worth stating positively in §2 rather than leaving as "RFC policy text".

    One residual wording risk: the issue body offers working_note in a single list where it actually names two different mechanisms — the ContentSource.working_note flag above, and the Atomic Memory entry kind (atomic_memory/extraction.py:141, which is what RFC 0014:531 refers to). The design note resolves this by not using either, but the body is still the spec of record. One sentence naming atomic_memory/extraction.py:141 as the intended reading would stop the next reader from taking the other branch.

    2. input_renderer — the seam is smaller than §5 implies

    The note routes rules through runtime/composition.py:1774-1797 with "minimal wiring", which is right, but the pipeline is not the place to wire it:

    • inference/pydantic_ai.py:302,379-383 — the generic generator does accept input_renderer, and applies it instead of model_dump_json().
    • runtime/composition.py:1774-1783 — the Handoff generator is constructed without it, unlike memory_generator a few lines above (:1704, :1716).
    • handoff/generation.py:126-135 — LLMHandoffGenerationPipeline.__init__ takes only generator and evidence_projector; there is no renderer parameter on the pipeline.

    So this needs exactly one argument at the construction site in composition.py; handoff/generation.py's constructor needs no change for the injection itself. That keeps composition.py as the only mandatory file for this half and leaves generation.py changes confined to the DTO.

    3. The prompt-instruction override makes the "custom Prompt" acceptance row untestable as currently worded

    Placement in per-request input is the right call, but the acceptance row "Auto/custom Prompt placement, versions, and provenance" needs to assert the user message, not the instruction prefix:

    • inference/pydantic_ai.py:391-397 — when a Prompt Artifact selection exists, Agent.override(instructions=selection.compiled_instructions) replaces the constructor's instructions (= HANDOFF_GENERATION_INSTRUCTIONS at composition.py:1776).
    • prompt/definitions.py:106-112 — for a Scope-owned Prompt, compiled is invariant_instructions + Scope guidance, so default_instructions is dropped. The v2 text that says "Record relevant uncertainty or unavailable support as an omission" (handoff/prompts.py:36) is therefore not what a custom-Prompt Scope sees; it sees the invariant text at prompt/builtin.py:199-215, which says only "Record uncertainty as omissions".

    Consequence for the acceptance table: a check that inspects the compiled instruction prefix passes while custom-Prompt Scopes still receive the weaker wording. The row should be split into (a) rule text present in the rendered user message for Auto and custom Prompts, and (b) prompt identity/version bumped — and (a) must be asserted on the request actually sent, downstream of the override.

    Minor, on versions: the compiled digest binds three fields — compiler_version, definition_version, builtin_version (prompt/definitions.py:113-120) — and the Receipt reports the latter two (runtime/receipt_builder.py:99-100). "Bump the necessary Prompt definition versions" is two fields; naming both avoids a Receipt that reports unchanged prompt identity while the wording changed.

    None of this changes the HOLD or the direction — it narrows the file set and makes one acceptance row actually able to fail.

  7. zzstar101 commented on Nov 12, 2026

    @zzstar101
    Contributor

    Updated the design note in place for all three additions. None of them changed the direction, and two of them reduced the file set.

    1. working_note runtime evidence. §2 now separates the two mechanisms the issue body names. RFC 0014:531 is read as the Atomic Memory entry kind at builtin/artifacts/atomic_memory/extraction.py:141, not as a ContentSource flag, and it does not relax RFC 0014 admission. The ContentSource flag is stated positively rather than left as policy text: builtin/sources/content.py:101 declares working_note: bool = False; builtin/source_eligibility.py:47-57 ends is_generation_eligible() in return not source.is_working_note, so a working note never reaches a summary request through an ordinary Source window; the write path defaults allow_working_notes: bool = False at builtin/persistence/artifacts.py:167,188 and only admits an unexpired working note through source_eligibility.py:60-77. The one opt-in is Handoff's own citation resolution at builtin/persistence/handoff.py:69,82,162 — a citation path, not a generation window. §7 now says the working_note gap closed by reading frozen code, not by executing it, and that this does not substitute for the write-path tests.

    One correction worth flagging: the cited paths in the review omit a builtin/ segment (src/powercontext/sources/content.py, src/powercontext/sources/source_eligibility.py, src/powercontext/persistence/artifacts.py, src/powercontext/inference/pydantic_ai.py, src/powercontext/runtime/receipt_builder.py do not exist at 63f021d6). The note links the real paths.

    2. input_renderer seam. Agreed, and it is now stated as the smaller thing it is. §4 records that builtin/inference/pydantic_ai.py:302 already accepts input_renderer and applies it at :379-383 in place of model_dump_json(), that the memory generators pass it (composition.py:1704, :1716), and that the Handoff generator at composition.py:1774-1783 does not — so the wiring is one added argument at the composition site. §4 also now says LLMHandoffGenerationPipeline.__init__ (handoff/generation.py:123-135) takes only generator and evidence_projector and needs no change, so composition.py is the only mandatory file for this half and generation.py changes stay confined to the DTO.

    3. Prompt-instruction override. This is the one that made a row actually able to fail, so the acceptance table now splits it:

    • Rule text present in the rendered user message, for Auto and custom Prompts alike — asserted on the request actually sent, downstream of the override.
    • Prompt identity and version bumped for both fields the Receipt reports — definition_version and builtin_version.

    The rationale is recorded under the table: pydantic_ai.py:391-397 applies Agent.override(instructions=selection.compiled_instructions), and for a Scope-owned Prompt prompt/definitions.py:106-112 compiles invariant instructions plus Scope guidance while dropping default_instructions. So the v2 wording at handoff/prompts.py:36 never reaches a custom-Prompt Scope; those Scopes see prompt/builtin.py:212. Asserting instruction text alone would pass for Auto and prove nothing for custom Prompts; asserting the rendered user message holds for both because the input_renderer seam applies regardless of which instructions win.

    Still HOLD on the three owner decisions — the minimum public-field extension, ordinary Handoff as the first slice, and the conditional file set. No production edits.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions