Repository navigation
Description
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:
HandoffOmissionconflates "material was unavailable" with "this claim is not verified"; a singletextfield 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()returnscontent.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
UNVERIFIEDis 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/ Topicdetail. - 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), andStatus1.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.", fieldstext(max_length) and optionalcitation, plus arequire_textvalidator.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:4907as "no execution outcome or control failure has been observed in this window".builtin/runtime/models.py:185andschema.py:8507use the same pair. A case-insensitivegit grep "unverified" origin/masterreturns ~200 hits, so "no corresponding mechanism" was never a defensible premise.src/powercontext/builtin/artifacts/handoff/service.py:356-367—HandoffService.render()returnscontent.model_dump_json(by_alias=True, indent=2). Markdown##sections appear only insrc/powercontext/server/dashboard/markdown.py:101-103(handoff_markdown, labels fromCATALOGS[language], called atserver/dashboard/routes.py:447).- RFC 0014:
:257routes handoff-only information toworking_note;:531-533listsworking_noteamong 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.pyat466591fe65d0...(an explicit labelled field inserted only into the summarizer prompt); Codexb8725c18(#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
- Repository
oceanbase/powercontext; baseline remote master2291237a7809410ea0dc8f19f2de149573af8378. Refresh master and the named issues/PRs at kickoff; recheck the conclusions if the baseline moves. Preserve other contributors' changes; do not reset the working tree. - File conflict, not a hard dependency: PR feat(processing): classify Dream, Handoff, and Evidence processing failures with safe diagnostics (#2126) #2539 (
feat(processing): classify Dream, Handoff, and Evidence processing failures with safe diagnostics, OPEN) touches Dream/Handoff generation paths; PR fix(integrations): drop the Python adapters' trust notices from prompt context #2527 (fix(integrations): drop the Python adapters' trust notices from prompt context, OPEN) touches prompt context. Neither is a prerequisite, but both may share files. Establish one owner or a serial handoff before editing; do not run two agents on the same module in parallel. - No hard dependency on evaluation(context): consume PreparedContext Receipts in opt-in LongMemEval diagnostics #2436, evaluation(memory): attribute prepared-context budget outcomes and compare allocation offline #2520, feat(context): investigate whether a current-state claim can be detected as no longer true #2545 or [Tracking] repeated-trial work-continuity gaps — research registry (case: three-session stereotaxic task) #2542. This task may run in parallel with them.
- Environment: Python 3.11+,
uv, the locked environment. Default tests need no live model and no network. A live-model probe, if used, must be reported separately as such.
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:
- 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. - 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. - The exact field shape and the label string, which must not be
UNVERIFIEDbecause ofStatus1.UNVERIFIED. - Whether the dashboard renderer needs a new
##section with bilingualCATALOGS[language]labels, or whether the JSON field alone is sufficient. Do not assume a Markdown section exists in the artifact. - The cache-prefix boundary, behavior on missing/empty/malformed stance, the second-derivation guarantee, and the treatment of pre-existing artifacts.
- The frozen file set for Phase 2, chosen from the candidate list below. A design that only changes
prompts.pycannot 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.
- Whether to reuse/extend
-
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 itsCATALOGScatalogs); focused behavior tests undertests/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
UNVERIFIEDas the stance label, or mapping stance ontoStatus1.UNVERIFIED/ExtractionObservation.status. - Adding a global
completeness/confidenceflag to Memory, folding stance intoMemoryEvidenceDeclarationauthority/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 thatHandoffService.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
BLOCKEDwith 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:
- The design cannot satisfy both RFC 0014 and the "uncertainty survives two derivations" goal — report the smallest contract change that would unblock it.
- A Phase 2 change would require a public DTO/API or Receipt change, or a module outside the frozen set.
- A shared file is already owned by feat(processing): classify Dream, Handoff, and Evidence processing failures with safe diagnostics (#2126) #2539 or fix(integrations): drop the Python adapters' trust notices from prompt context #2527 and no serial handoff can be arranged.
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:
- Receipt diagnostics in LongMemEval-V2 — already fully specified by open evaluation(context): consume PreparedContext Receipts in opt-in LongMemEval diagnostics #2436.
- Capture coverage
complete/partial/unknown— already merged by feat(capture): declare bounded projection coverage #2451 / fix(gateway): honor all inference protection modes #2457. - Host egress disclosure and withheld-data / checkpoint conformance — already merged by test(hermes): guard withheld-data boundaries and qualify real-host conformance #2438 / test(hermes): guard withheld data and qualify real-host conformance #2452; only the fork-channel gap is picked up by feat(integrations): gate fork/subagent write channels at the host boundary and close the capability-matrix gap #2560.
- Source evidence declarations — already merged by feat(memory): persist versioned Source evidence and neutral Atomic Memory projection #2004 (= feat(memory): add versioned Source evidence declarations and neutral lifecycle projection #1975).
- Compression-stable capture identity, and least-privilege binding for consolidation tasks — idea-level observations in the review; both still need a reproduction before a task is justified.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsTodo
Activity
[-]feat(memory): design how derived summaries keep unverified hypotheses labelled[/-][+]feat(memory): reconcile existing uncertainty surfaces into one compression-stable stance contract[/+]zzstar101 commentedon Nov 9, 2026
assign me plz
AlexStocks commentedon Nov 9, 2026
done. thx for your enthusiam for pc.
zzstar101 commentedon Nov 9, 2026
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 onlykindandbasis. 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:
kind/basisand 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.No
closure,supported/contradictedassessment 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:
text/citation. For a hypothesis,textis the claim; do not introduce a duplicate hypothesis list.kind. Aworking_hypothesisrequires a nonemptybasis; anevidence_gapmay omit it. Generation must validate the new fields rather than silently ignore and discard them.kind/basisand retain an unclassified state. Do not inferevidence_gapor “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.omissions, including[]when empty. When all entries are classified, noworking_hypothesisentries means that this result records no hypotheses; no redundant counter is persisted. Historical results containing unclassified entries remain unknown, not zero hypotheses.2. Ownership, RFC 0014, and existing uncertainty surfaces
The issue body's
working_notenames 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 aContentSourceflag and it does not relax RFC 0014 admission.The
ContentSourceflag is separate and already constrains the generation path in the direction this contract needs. content.py:101 declaresworking_note: bool = False, andis_working_note_active()readsmetadata["expires_at"]. source_eligibility.py:47-57 hasis_generation_eligible()end inreturn 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 defaultsallow_working_notes: bool = False, and source_eligibility.py:60-77 only admits a working note when that flag is passed andis_working_note_active()holds, otherwise raisingSourceNotEligibleErrororWorkingNoteUnavailableError.The one place that opts in is Handoff's own citation resolution, which passes
allow_working_notes=Trueat 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 statusStatus1.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:
First derivation: the settled fact belongs in ordinary state; the hypothesis belongs in a
working_hypothesisomission 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
input_renderer: Callable[[InputT], str] | None = Noneat pydantic_ai.py:302 and applies it instead ofmodel_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.generatorandevidence_projectorand needs no change for the injection;handoff/generation.pychanges stay confined to the DTO.composition.pyis 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.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
Necessary adaptation at existing boundaries
input_rendererto 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.Eligible only after approval of the public-contract exception
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
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
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, droppingdefault_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 theinput_rendererseam is applied regardless of which instructions win.The version row names both fields. The compiled digest binds
compiler_version,definition_version, andbuiltin_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:
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 is2291237a7809410ea0dc8f19f2de149573af8378. The comparison for relevant Handoff/Topic/Dream, RFC 0014, Dashboard Markdown, and OpenAPI files was empty. The frozen issue-body SHA-256 is7a98dc2e0eafa8312a2fc227009410390738057c7c6666f36516a4860db756ce. The older working branch was neither switched nor reset.Findings
content.py:101,source_eligibility.py:47-57and: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:
The working directory was
frozenunder that evidence directory, containing a completegit archiveof the SHA above. Locked-environment attempt:Exit code 1; BLOCKED. Error excerpts:
Supplemental execution:
PYTHONDONTWRITEBYTECODE=1 \ PYTHONPATH="$PWD/src:/Users/zzstar/.cache/uv/archive-v0/hnDthDthit1JQPkY:/Users/zzstar/.cache/uv/archive-v0/5HGDCJeML1SlwwDo" \ python3 ../probe.pyExit code 0. Condensed interpretation of the recorded results, not a verbatim raw-JSON excerpt:
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.
zzstar101 commentedon Nov 10, 2026
@AlexStocks I've completed the design notes. Please review them
AlexStocks commentedon Nov 12, 2026
Checked the design note's load-bearing seams at
63f021d6. Everything it claims aboutserver/mapping.py,prompt/validation.pyand 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_notecheck covered RFC policy text, "not runtime admission/rejection behavior". Here is that side, verified on63f021d6:sources/content.py:101—working_note: bool = False;is_working_note_active()readsmetadata["expires_at"].source_eligibility.py:47-57—is_generation_eligible()returnsnot source.is_working_note. A working-note Source is excluded from the generation path entirely, not just from promotion.allow_working_notesmust be enabled (defaultFalse) 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_notein a single list where it actually names two different mechanisms — theContentSource.working_noteflag above, and theAtomic Memoryentry 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 namingatomic_memory/extraction.py:141as the intended reading would stop the next reader from taking the other branch.2.
input_renderer— the seam is smaller than §5 impliesThe note routes rules through
runtime/composition.py:1774-1797with "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 acceptinput_renderer, and applies it instead ofmodel_dump_json().runtime/composition.py:1774-1783— the Handoff generator is constructed without it, unlikememory_generatora few lines above (:1704,:1716).handoff/generation.py:126-135—LLMHandoffGenerationPipeline.__init__takes onlygeneratorandevidence_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 keepscomposition.pyas the only mandatory file for this half and leavesgeneration.pychanges 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'sinstructions(= HANDOFF_GENERATION_INSTRUCTIONSatcomposition.py:1776).prompt/definitions.py:106-112— for a Scope-owned Prompt,compiledisinvariant_instructions+ Scope guidance, sodefault_instructionsis 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 atprompt/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.
zzstar101 commentedon Nov 12, 2026
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_noteruntime evidence. §2 now separates the two mechanisms the issue body names. RFC 0014:531 is read as the Atomic Memory entry kind atbuiltin/artifacts/atomic_memory/extraction.py:141, not as aContentSourceflag, and it does not relax RFC 0014 admission. TheContentSourceflag is stated positively rather than left as policy text:builtin/sources/content.py:101declaresworking_note: bool = False;builtin/source_eligibility.py:47-57endsis_generation_eligible()inreturn not source.is_working_note, so a working note never reaches a summary request through an ordinary Source window; the write path defaultsallow_working_notes: bool = Falseatbuiltin/persistence/artifacts.py:167,188and only admits an unexpired working note throughsource_eligibility.py:60-77. The one opt-in is Handoff's own citation resolution atbuiltin/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.pydo not exist at63f021d6). The note links the real paths.2.
input_rendererseam. Agreed, and it is now stated as the smaller thing it is. §4 records thatbuiltin/inference/pydantic_ai.py:302already acceptsinput_rendererand applies it at:379-383in place ofmodel_dump_json(), that the memory generators pass it (composition.py:1704,:1716), and that the Handoff generator atcomposition.py:1774-1783does not — so the wiring is one added argument at the composition site. §4 also now saysLLMHandoffGenerationPipeline.__init__(handoff/generation.py:123-135) takes onlygeneratorandevidence_projectorand needs no change, socomposition.pyis the only mandatory file for this half andgeneration.pychanges 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:
definition_versionandbuiltin_version.The rationale is recorded under the table:
pydantic_ai.py:391-397appliesAgent.override(instructions=selection.compiled_instructions), and for a Scope-owned Promptprompt/definitions.py:106-112compiles invariant instructions plus Scope guidance while droppingdefault_instructions. So the v2 wording athandoff/prompts.py:36never reaches a custom-Prompt Scope; those Scopes seeprompt/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 theinput_rendererseam 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.