ADR 032 Repository Plan Reconstruction and Preparation - joeroberts/release-radar GitHub Wiki

ID: ADR-032
Status: Accepted
Date: 2026-10-18
Date meaning: Recorded proposal date; not an ADR acceptance date.
Implementation: This document proposes the contract; implementation progress belongs to issue 101.
Approval qualification: Owner approved the reviewed proposal with policy B for ADR preparation only; final acceptance of this exact ADR, publication and dependent implementation remain separately unauthorized.

Context, decision and approval boundary

Existing-project onboarding can establish repository access, catalog acceptance and managed guidance while leaving Project Plan empty. The owner needs an in-app path from selected repository delivery documents to a reviewed plan, including historical state, without composing connector commands, manually authoring JSON or orchestrating another chat. This proposal also covers partially populated plans while preserving existing records and history.

The proposed decision is one bounded reconstruction payload within the existing plan-proposal infrastructure, an app-owned non-operative source-to-draft preparation purpose in the existing coordinator, and explicit policy B for honest present-day owner attestations when original terminal-state records are unavailable. It introduces neither a competing importer nor a second planning database, delivery phase, recurring synchronization or live-owner-data operation. Legacy import, ordinary planning, task execution, acceptance and recovery keep their existing meaning. No automatic Backlog conversion or silent exclusion is permitted.

The owner said, “Approve proposal with policy B; prepare ADR”. That direction approves the design for this preparation, not this ADR's final acceptance. Every rule below remains Proposed. Existing Accepted bodies, immutable metadata, baselines and scope applicability are unchanged. Dependent implementation remains blocked pending the exact decision's acceptance and separate implementation authority.

This is a self-contained translation of the complete reviewed contract, with the resolved policy B choice and the approval boundary made explicit. Schemas, guards, exceptional cases and acceptance obligations are retained below. The owning product specification remains Repository Plan Reconstruction; this proposal does not update that specification or make its proposed source-boundary amendment operative.

Provenance and scope

Owning outcome and acceptance criteria: issue 101.
Exact design source: reviewed revision 2 contract, updated 2026-10-18T06:42:30Z, including the final goal_acceptance and proofRef corrections.
Independent design review passed that candidate; this is a design result, not runtime verification or decision acceptance.
Recorded owner direction selects policy B and ADR preparation only.
Design source code identity: 2c8ea048784d1190083f464c155c48004c25fb2f. Governing ADR read: canonical Wiki revision 5a7017b97b19822a52662c907ee098bc74cfedb5. Read-only design observations below are attributed to that reviewed design, not a new runtime inspection.
New scope: product.repository-plan-reconstruction. Affected existing scopes: product.authority, product.readiness, product.ticket-tasks, product.managed-documentation, product.planning-placement, product.document-references, product.planning-proposals, product.history, product.task-adoption and product.phase-lifecycle. All catalog applicability for this ADR is proposed.

Issue 1 retains generic task adoption for existing tickets; this proposal reuses its reconciliation and receipt boundaries and owns repository-plan preparation. It coordinates with the existing P6-remediation reconstruction work; it does not create another reconstruction project. Connector upgrade recovery in issue 99 and the Copy update prompt defect are outside scope. Repository registration, catalog acceptance and guidance installation remain distinct from plan population. The reviewed design records repository-documentation reconciliation delivered through issues 118/153; that fact does not authorize implementation here.

Atomic Apply retains the owning specification's qualification: all-or-nothing application is acceptable only if blockers are easy to resolve or explicitly exclude while preserving a coherent graph. Usability verification must establish this before shipping. If it fails, a bounded owner product decision is required; partial application must not be substituted silently.

Proposed contract

1. Source format and complete in-app preparation

Introduce the proposed structured projection format release-radar.repository-plan, schemaVersion 1. A pre-authored repository projection may be read from docs/delivery/reconstruction-plan.json. It is an OPTIONAL entry path, not a prerequisite the owner must manufacture. Legacy dashboard-status.json / Rekon V1 remains unchanged.

When no compliant projection exists, Prepare repository plan opens an in-app source chooser over the authorized repository's delivery documents. The app shows path, catalog identity/lifecycle/authority, current byte digest and destination. The owner selects the documents and authorizes sending those exact captured bytes to the already selected supported Codex account/model for draft preparation. No repository write permission follows. The app captures bounded immutable source copies, records their identities and creates a resumable preparation attempt. An agent may interpret these documents into proposed planning rows, citations, contradictory claims and unresolved fields. It cannot decide which claim is authoritative, assert acceptance/completion, or mutate delivery records. The owner reviews the generated rows inside Release Radar; ordinary planning values and authority classifications may be confirmed in a batch with explicit exclusions, while terminal-state claims require section 2's policy B evidence rule. The owner does not write JSON, compose connector commands, or open another chat.

Concrete component: add an app-owned project-scoped plan_preparation purpose to ReleaseRadarCoordinator and a typed preparePlanDraft request keyed by registration/root/proposal/preparation-attempt identity. Reuse its existing AppServerTransport, selected Codex context/identity checks, restrictive permission validation, model/effort readback, MCP/plugin disablement and correlated turn handling. WorkerAdapter.start and ProjectExecutionWork currently require an existing ticket/task/In-delivery phase; they CANNOT be called with fabricated work. The new purpose is explicitly separate admission for a non-operative draft, with no delivery-task identity or delivery/review mutation authority. This app-to-helper preparation entry is NEW proposed #101 implementation, not a capability claimed to exist today. It extends the existing coordinator rather than introducing another runner.

The helper receives read-only access to the app-captured selected-source snapshot, no repository/store writes, no RR mutation tools or other MCP services, no worker network capability, no additional agents and no approval escalation. Account/model transport retains the existing supported identity and selected-context boundary. The app must verify effective grants and fail before a turn if the installed runtime cannot enforce them. Model/provider fallback is not automatic. Model output returns as a bounded typed draft to the app, not a repository file or an operational command. The existing 32,000-character generic worker message truncation cannot carry this payload: the preparation response must be collected completely up to the stated 1 MiB bound and rejected explicitly on overflow/truncation. Tool-generated content and citations remain untrusted data.

The app alone validates and stores the normalized projection as part of the existing reconstruction proposal version, alongside the original source bytes and owner review decisions. It does not need to write reconstruction-plan.json, edit catalogs/instructions, publish to Git/Wiki, or accept a repository catalog. A repository-provided projection requires its accepted managed artifact binding; an app-prepared projection instead has app-owned proposal identity and a manifest binding every original selected source. These two origins are displayed distinctly. Neither origin makes model text approval.

Preparation state is scoped to the proposal: queued/running, awaiting_resolution, ready_for_review, failed, cancelled or outcome_unknown. Persist the attempt ID and known helper/thread/turn identity with its source manifest. Missing agent/account/model or unsupported grants shows the exact in-app setup/retry action and retains source selection/draft. It is not an instruction to transcribe JSON or use a separate chat. Reuse existing account/context setup UI; do not silently enable project execution or install hooks. Reconnection queries the known preparation attempt. A replacement may start only after the prior turn is known ended/revoked; late results for a superseded attempt cannot replace the current draft. Cancellation revokes the exact preparation request and preserves any explicitly saved draft. No preparation result can Apply itself. If no supported agent is available and no structured source already exists, the feature is temporarily blocked with resumable in-app recovery; it cannot claim successful onboarding.

NARROW PROPOSED SOURCE-BOUNDARY AMENDMENT: “Only a validated, versioned structured projection, bound to its captured sources and explicitly reviewed in Release Radar, may supply reconstruction operations. Release Radar may prepare that non-operative projection from owner-selected repository documents through its bounded preparation agent. Prose and agent output never directly create delivery state, establish source authority, or prove historical acceptance/completion. Unresolved authority or state evidence blocks Apply. The approved projection and its sources may be retained in the app-owned proposal; a pre-existing repository JSON file is not required.” This replaces only the pre-authored-source restriction in the owning reconstruction specification. It requires owner acceptance before dependent implementation; no broader prose inference, autonomous approval, or repository-write authority is proposed.

Projection schema: strict UTF-8 JSON without BOM, duplicate/unknown keys, invalid numbers or truncation. format and schemaVersion above; required top-level repositoryID, projectionID, projectionRevision, documents, phases, tickets, phaseDependencies, ticketDependencies. The app supplies projectionID (stable UUID) and revision (positive integer) for prepared drafts. Source-supplied values are validated for repository projections. Destination registration/capabilities/approval never come from the file.

Limits: 1 MiB projection, 256 phases, 5,000 tickets, 5,000 total task rows, 20,000 total dependency edges; existing 64-definition bound for a revision to an existing task plan. Source reads use existing document-reader limits. Over-limit sources or outputs identify the exact bound and selection; no omitted/truncated data is presented as complete. The owner can narrow sources explicitly, with excluded context retained. A reconstruction operation is subject to these row bounds, not an unbounded bypass of ordinary proposal limits.

documents: {id, artifactID, contentSHA256}. id is local to the projection; artifactID resolves the selected authorized source; contentSHA256 hashes its COMPLETE captured bytes. The projection itself is forbidden from this table. Historical/proposed/superseded source metadata stays visible and never becomes an operational controller merely through selection.

sourceRef is a tagged union:

{kind:"projection", pointer}: an RFC 6901 JSON pointer into the already captured projection envelope. Its identity is the app-held complete projection SHA-256 plus pointer. The digest is outside the projection, never a self-hash field.
{kind:"document", documentID, locator}: external captured-document identity plus an anchor or JSON pointer. Terminal-record parsing requires a JSON pointer resolving exactly one object. A displayed prose anchor is only a citation. No reference is an executable instruction or an alternate file path.

The schema has no subjectDefinitionSHA256 field. The complete envelope/document digest and pointer identify the bytes. Terminal subject binding uses the exact typed field comparison in section 2; there is no second subject hash, unspecified JSON canonicalization or recursive digest.

All phase/ticket/task rows: sourceID, authorityClass, sourceRefs. sourceID is nonempty, <=256 UTF-8 bytes, no NUL/control characters; compare exact UTF-8 identity without case folding/normalization. authorityClass is current_approved | historical | proposed | superseded | unscheduled. Generated classifications are suggestions requiring explicit owner resolution; model confidence cannot establish approval. A currently recorded Accepted ticket can be current_approved; “historical” denotes a non-current source definition, not all completed work.

Phase adds name, lifecycle, stateEvidence. lifecycle is unassessed | upcoming | in_delivery | completed. Ticket adds outcome, phaseSourceID, lane, taskPlan, stateEvidence, evidenceRefs. phaseSourceID/lane are both null when unplaced; otherwise lane is backlog | in_progress | needs_review | blocked | accepted. taskPlan is null or {sourceRevision,tasks}; sourceRevision is positive source provenance, never copied into the live RR optimistic revision. Task adds label, title, sortOrder, completion, lifecycle, stateEvidence. completion is pending | completed; lifecycle active | superseded; sortOrder is nonnegative. IDs/labels remain stable. No-plan atomic tickets are valid. An Accepted ticket's active tasks must all be completed; a nonempty plan retains at least one active task; unplaced work cannot have completed tasks. stateEvidence is an array of proof references, not a single nullable record. Pending/active, Backlog and Unassessed states may use an empty array. A task that is both completed and superseded requires both proofs; neither fact overwrites the other. Dependencies: {sourceID,subjectSourceID,dependsOnSourceID,sourceRefs}, separate phase/ticket arrays. Validate all endpoints and cycles against the included source plus explicitly mapped existing records. Exclusions never silently sever edges.

All listed fields are required; null and empty arrays are explicit. Text limits otherwise reuse Core policy. Intermediate agent drafts may contain unresolved-field diagnostics outside this strict projection. They can be saved as blocked drafts but cannot be treated as a valid reconstruction projection until required fields, authority and state evidence are resolved. Omission never means deletion, supersession or approval.

2. Typed terminal-state evidence and selected policy B

The initial supported historical-record adapter is state-record-v1. It resolves a document sourceRef to a JSON object with exactly: {format:"release-radar.state-record",schemaVersion:1,recordID,repositoryID,kind,subject,state,occurredAt,actorID,phaseCompletion}. recordID is a stable nonempty source identity; repositoryID must match the projection. kind is ticket_acceptance | task_completion | task_supersession | phase_lifecycle | goal_acceptance. state is respectively accepted | completed | superseded | the explicit phase lifecycle | accepted. A goal_acceptance record has subject {phaseSourceID,sourceGoalID} and phaseCompletion:null. It asserts only that exact goal's acceptance; its owning phase may remain In delivery. It neither asserts phase completion nor creates an operational Delivery Goal. occurredAt is a source RFC 3339 timestamp or null; actorID is a source assertion or null. Null remains unknown. phaseCompletion is null except for a Completed-phase record, where the certificate below is required. No field can grant owner-app authority.

subject comparison is deterministic and nonrecursive:

task: {ticketSourceID,sourceID,label,title,sortOrder}, compared field-for-field to the current source task definition. Completion and supersession are independent assertions; exclude sourceRefs, stateEvidence and authority metadata from this subject.
ticket: {sourceID,outcome,phaseSourceID,taskPlan}; taskPlan is null or {sourceRevision,tasks}. Each task snapshot contains sourceID,label,title,sortOrder,completion,lifecycle, with no evidence/citation fields. Match the complete task set by exact IDs, rejecting duplicates/missing/extra rows; compare strings as UTF-8 bytes and integers exactly. The acceptance proof's state is accepted.
phase: {sourceID,name}, plus the complete certificate for Completed. Object key order is irrelevant; task/membership arrays are compared as sets keyed by exact identity after duplicate rejection. Thus no canonical JSON serializer or additional hashing scheme is required. Changing a terminal subject definition invalidates its proof; a correction cannot silently reuse old evidence.

For the original-evidence path retained under policy B, this object must be an original structured source record captured from the referenced document, not a model-created normalization of prose. No adapter for arbitrary old logs/receipts is claimed. Other structured formats are unsupported until a specific adapter and matching rules are approved; they remain cited evidence, not proof of a terminal state. The app verifies shape, source bytes, scope and subject/state agreement, not cryptographic authenticity of a historical human decision. The owner reviews provenance explicitly. Generated output cannot label itself an original receipt.

An ordinary nonterminal lane or nonterminal phase lifecycle is an explicit projection assertion located by a projection reference and confirmed in review; it is not historical acceptance evidence. For terminal states, a projection-local reference alone does not satisfy the original-evidence path. Source state assertions from prose may be shown as unresolved claims; they cannot populate a valid terminal state without a valid original proof or policy B's explicit attestation.

Completed-phase certificate (phaseCompletion) is: {membershipComplete:true,tickets,goals,obligations,deliveredBy}. tickets lists the exact complete current nonretired membership as {sourceTicketID,lane,acceptanceProof}; every lane must be accepted, its proof must validate above, and the set must equal all source tickets assigned to the phase plus all destination tickets retained there after mappings/corrections. Listed unresolved or omitted destination members block. A full-source membership declaration is a scoped assertion in the original phase-completion record, not an inference from how many rows the agent listed. goals is the source completion-assessment inventory: {sourceGoalID,required,lifecycle,remainingDebt}; required non-superseded goals must be accepted. Superseded goals must be explicitly debt-free. These are retained historical completion facts, not newly imported operational Delivery Goals. obligations is the complete source-assessment inventory: {sourceObligationID,disposition,descendants}; descendants contains exact {kind,phaseSourceID,sourceID} references, where kind is ticket or goal. disposition is fulfilled | explicitly_dropped | superseded_debt_free | unresolved | unassessed. unresolved/unassessed block. A carried obligation is fulfilled only when its nonempty explicit descendants all resolve to validated Accepted ticket or accepted-goal facts in the captured assessment; cycles/missing descendants block. An explicitly dropped obligation is not accepted/delivered credit. Compare any live destination obligations through existing store policy too; a certificate cannot override them. deliveredBy is a nonempty array of the same {kind,phaseSourceID,sourceID} references to accepted ticket or accepted-goal facts in that certificate. Every goal/obligation row is scoped to the certificate's phase. A goal reference outside that certificate has the same kind/phaseSourceID/sourceID plus proofRef, which is null only when an exact Accepted destination goal is included in the current baseline; otherwise proofRef is a document sourceRef to a captured state-record-v1 goal_acceptance record. Its repositoryID, subject.phaseSourceID and subject.sourceGoalID must match the reference exactly, and its state must be accepted. This also permits an Accepted goal in a still-In-delivery source phase. Under selected policy B, the app may instead bind the same reference to its separately audited exact-goal owner attestation; source/agent JSON cannot assert that trusted origin. Cross-phase ticket descendants must resolve to a validated ticket_acceptance proof or an exact Accepted destination ticket. Unknown/missing scope, mismatched identity or non-Accepted state blocks. These are completion-assessment facts retained with the reconstruction, not an operational goal importer. At least one actual accepted outcome must validate. Empty/all-dropped phases cannot be reconstructed Completed. This preserves ADR-020's actual-delivered-outcome, resolved-coverage and accepted-required-work rules without adding an operational goal importer or evidence engine. Missing membership/coverage records, unresolved references or a contradictory assessment blocks the Completed assertion. Presence of a digest or an owner clicking ordinary proposal approval does not substitute for these typed checks.

Policy B is selected for this proposal. The alternative considered was: Alternative A (not selected) — Original structured evidence required. Missing supported original terminal records is a specific blocker. The owner can select an existing supported source through the app, correct an erroneous claim or explicitly exclude genuinely unwanted work; no automatic exclusions/Backlog conversion. Selected policy B — When original historical records are unavailable, explicit present-day owner attestation is allowed. In a separate in-app confirmation, the owner attests each exact terminal subject/state, including both facts for completed-and-superseded tasks and the full membership/coverage/delivered-outcome certificate for a Completed phase. The app produces and audits that attestation in the proposal's trusted review state; source/agent JSON cannot assert this origin. Persist it as current owner attestation of historical state, not a recovered receipt. Original actor/time remain unknown unless separately evidenced. All structural consistency and actual-delivered-outcome checks still apply. The final immutable proposal approval binds these attestations. This is an explicit proposed evidence-authority exception.

Read-only feasibility evidence is limited: assigned HEAD's tracked docs contain neither reconstruction-plan.json nor dashboard-status.json, and the inspected retained documentation/Wiki inventory did not establish any supported original terminal record in the newly specified format. This is not proof that no historical evidence exists elsewhere. No owner store/runtime was inspected. This limitation accompanied the reviewed proposal; it is not proof that original records cannot be found. The owner subsequently selected policy B for ADR preparation. A generated fixture still does not establish source feasibility, and final acceptance of this exact ADR remains pending.

3. Source/destination identity and freshness

Preparation accepts only the exact owner-selected registered project and persisted authorized root row. Reuse AuthorizedProject, registration ID/request generation, bookmark access, DocumentationRootContext, accepted repository/catalog identity and RepositoryDocumentReader's bounded no-follow descriptor reads. Reject root substitution, symlinks, nonregular files, path escape, an unaccepted/mismatched catalog, unavailable bookmark and archived/rotated registration.

For a repository projection, revalidate its file; for an app-prepared projection, revalidate the captured-source manifest and the immutable app-owned projection version. There is no required repository output write.

Capture in the proposal: projectID; rootID; registrationID/requestGeneration; repositoryID; projectionID/revision; source path; complete projection SHA-256 and bytes; accepted catalog version/digest; each referenced document's artifact identity/digest/captured lifecycle/authority and required content; Git HEAD when available as observation, not authority; destination PlanningBaseline bytes/digest; exact edits, mappings, exclusions and derived operations. Do not embed the file's containing Git commit in the projection itself. Content digest plus declared projectionRevision identifies its bytes; observed Git HEAD is additional provenance. A dirty working copy is identified as such, not falsely called the committed blob.

Revalidate exact root/binding/registration, projection and included-reference bytes, source classification and destination baseline before saving an applicable version, owner approval and Apply. A changed or unavailable source invalidates application; it does not silently update the proposal. Preserve the old version for comparison and require a refreshed version and new approval. Revalidate descriptor stability immediately before transaction completion. There is no cross-filesystem/SQLite atomicity claim; freshness is established at the final validation boundary, and later filesystem edits are a new source revision.

4. Partial plans, identities and corrections

Persist source-to-destination associations in the same app store, tied to the reconstruction proposal/application. The identity key is repositoryID + projectionID + record kind + parent ticket sourceID for tasks + sourceID. A changed file revision does not change record identity.

For an unmapped new record, derive a deterministic RR ID as rpr- followed by SHA-256 of those five UTF-8 components separated by NUL; validated source components cannot contain NUL. Keep the original source ID visible and retained. This avoids global ID collisions between repositories. Existing records may be explicitly mapped by the owner using the exact existing project-scoped identity; do not merge by title. A matching raw source ID may be shown as a candidate, not auto-approved.

Preview shows each row as new, identical/unchanged, conflicting, blocked or explicitly excluded, with before/after fields and provenance. For an existing mapped record, compare owned fields, placement/lane, task definition/state/revision, relationships, lifecycle and protected history. An identical record becomes a no-op. Repeated preparation reuses its persisted mapping and produces no duplicate. A different existing record is never overwritten merely because the source is newer.

Resolve differences through explicit keep-destination or source-draft correction, or through an existing permitted planning/task revision shown in the proposal. Keep-destination is a recorded difference and exact chosen result, not silent source substitution. Existing Accepted tickets/tasks, completed task definitions, superseded history and Completed phases remain immutable; no reopening, retargeting or retrospective task addition is implicit. A conflicting addition into an existing Completed phase blocks rather than reopening it. Explicit exclusions remain visible in the saved proposal and final report and must leave a coherent graph.

The review editor may correct editable planning fields and mappings. It cannot synthesize historical state/evidence, manufacture source authority, or edit accepted destination history. Every correction/exclusion creates a new immutable proposal version and clears prior approval. The original source bytes are retained separately from owner corrections.

5. Exact typed operation and atomic state adoption

Add a reconstruction payload kind to existing PlanChangeProposalVersionRecord and its existing save/query/decision/apply infrastructure; existing ordinary proposal versions retain their meaning. A reconstruction version contains one bounded reconstructRepositoryPlan operation with the source envelope, explicit mappings/corrections/exclusions and validated resulting record set. It cannot be mixed with arbitrary ordinary operations to evade guards.

Proposed entry points:

previewRepositoryPlanReconstruction(target): read-only bounded source/destination observation; no proposal, audit, receipt or live-plan writes.
saveRepositoryPlanReconstruction(proposalID, expectedPreviousVersion, exactPreview, edits): saves a version through the existing dispatcher/receipt infrastructure. It may save a clearly blocked draft for resumable resolution, but a blocked version cannot be approved/applied. Add this explicit draft qualification to the existing proposal-version contract; do not create another proposal engine.
Existing trusted owner-app decidePlanChangeProposal and applyPlanChangeProposal bind the immutable reconstruction version, complete baseline, registration and state-evidence disposition. External agents may prepare/save proposals but cannot decide/apply. No field from source or agent may impersonate ownerApp.
Existing proposal query/readback returns draft blockers, source metadata, exact decisions and application receipt.

Apply uses one existing DeliveryStore audited transaction for the entire selected graph, mappings, reconstruction provenance, application record and command receipt. Revalidate all guards inside the transaction; a late failure commits none of them. Preparation/review never changes the live plan.

For new records only, the proposed reconstruction policy may initialize the explicitly approved source lane/task/lifecycle state without replaying normal historical transitions. This is the narrow new rule requiring acceptance. It is not a new public arbitrary upsert, acceptance bypass for existing work, or permission for ordinary imports/commands.

New task plans receive RR revision 1; original source revisions remain provenance. Existing task plans keep exact revisions unless a separately shown permitted revision is applied. Accepted task-plan consistency and complete phase membership/remaining-work consistency must hold; contradictions block rather than inventing goals or outcomes.

New phase readiness begins Legacy-unassessed; do not import Ready, invent Delivery Goals/assignments, or set the v11 migration-continuation flag. Existing phase changes use existing readiness invalidation. Reconstructed In-progress/Needs-review/Blocked lanes are visible current-state facts, but subsequent governed actions still require ordinary applicable readiness/assignment/evidence checks. The app lists that remaining setup and offers existing planning actions. No automatic reset to Backlog, active-phase change, execution start, acceptance, or notification occurs.

For Completed phases, section 2's typed membership, goals/obligations and actual-delivered-outcome certificate must validate against the complete selected source and resulting destination graph. No unresolved/unassessed carried debt, hidden unfinished member, or empty/all-dropped phase may pass. New Completed phase initialization is a distinct reconstruction-state record, not a fabricated lifecycle transition.

6. Persistence, history and recovery

Add reconstruction provenance/mapping data within the existing app store and proposal ownership; no external writer or second database. It retains source key, mapped runtime identity, proposal/version/application, source field assertions, source evidence references and optional original event facts. Include these additive records in existing full-backup, archive/removal-history and registration-rotation behavior. Restoration must not revive an old approval as current authority.

Current task/phase storage requires completion dates. Do not write today's time into those fields to satisfy constraints. Add a bounded storage representation for reconstructed states: creation/recording time is the actual Apply time, while original completed/superseded/lifecycle occurrence times remain source-supplied or null/unknown. Preserve ordinary task/lifecycle constraints for ordinary records. A later additive migration may adjust these constraints for explicitly reconstruction-origin records; never edit the frozen historical migration/fixture. Original source revision/baseline facts remain separate from the new RR revision and reconstruction comparison baseline.

History records one real current reconstruction application with source snapshot, exact counts/identities, unchanged/conflicting/excluded rows and receipt. It does not create prior transition, acceptance, task-completion or phase-completion events, actors, timestamps or notifications. UI labels imported state as reconstructed from the named snapshot and distinguishes unknown historical facts.

Before dispatching Apply, durably retain the exact command envelope/requestID/applicationID against that proposal version through a narrow owner-app pending-attempt record. Reuse that envelope after interruption. Do not regenerate request IDs on Retry. This is proposal recovery state in the same store, not a workflow database.

Applied: read back the matching application/receipt and resulting records; show success and remaining setup.
Pending/uncertain: disable a new Apply; query that exact attempt and replay only its identical complete envelope under current registration/origin checks. The atomic receipt returns the original result without duplicate audit/effects.
Known refusal/no receipt after authoritative reconciliation: show the cause; stale source/baseline requires a new version/approval. An unavailable query remains unknown, not proof of no effects.
Registration rotation: prior approval/attempt becomes historical; never apply it to the new registration. Cancel before Apply leaves the live graph unchanged. A saved draft remains resumable and visibly unapplied; “Not now” from the initial offer performs no writes. Once dispatch has occurred, Cancel cannot claim rollback; it returns to outcome reconciliation.

7. App journey, agent boundary and acceptance

On onboarding completion and empty Project Plan, show Prepare repository plan with exact destination/source and “Nothing is added until you review and Apply.” A partially populated Project Plan has the same action. Recognition alone never saves/applies anything. Preparation reads the supported source and opens the review with source classes, current counts versus excluded context, comparisons and blockers. Save draft is explicit and resumable; Approve and Apply remain distinct. After Apply, refresh Project Plan, Phase Board and History and show unresolved setup/conflicts/exclusions.

Historical/proposed/superseded/unscheduled source rows are visible context, not automatically operational rows. They are never silently dropped from preview or counted as current approved work. An explicit current_approved source record with Accepted lane is eligible historical completed work, not misclassified as unscheduled. No automatic source promotion is allowed.

A pre-authored supported projection uses deterministic preparation without an agent. Otherwise section 1's bounded in-app source-to-draft preparation is part of #101's required journey. It must be implemented and verified against repository delivery documents, not bypassed by supplying a specially prepared JSON fixture. Agent/account/runtime unavailability preserves the in-app source selection and draft and offers exact supported setup/retry; it never falls back to manual transcription or a separate chat. The narrow source-boundary amendment is proposed explicitly; until accepted it blocks dependent implementation, not design completion.

Use the existing approved reconstruction entry hierarchy and Project Plan compact behavior. Source/destination, conflicts, terminal-state evidence and Apply summary remain keyboard/VoiceOver accessible at normal and compact width. Blocking errors focus the relevant row and explain the available correction. Evidence/authority distinctions must not rely on color.

QA acceptance must exercise: a substantial historical-document repository and RR self-onboarding fixture with the exact supported projection; empty and partial plans; new higher-lane/Accepted/completed records; identical reruns; protected existing history; unknown historical dates; conflicting source authority; incorrect/missing historical evidence and explicit owner attestation under policy B; unsafe roots; unsupported version/size; missing source/unavailable agent; coherent corrections/exclusions; stale source/destination; cancellation; late atomic failure; lost response/relaunch/exact replay; and normal/compact independent native UI. Observe resulting records in Project Plan/Phase Board and the single real History event; verify no synthetic completion notifications. Test-first QA owns fixtures/tests/execution.

8. Narrow accepted constraints needing a new decision

Do not amend existing Accepted bodies. A new accepted decision would specify these reconstruction-only exceptions and leave all other scopes unchanged:

ADR-004: new/moved tickets and imports enter Backlog; migration alone grants continuation. Reconstruction needs source-lane initialization for new records; it does NOT grant continuation or implicit readiness.
ADR-005: every task addition starts Active/Pending and completion uses separate exact-revision commands; current legacy import is task-plan-free. Reconstruction needs initialization of explicit historical task states and honest nullable source event facts. Ordinary additions/completion and legacy import remain unchanged.
ADR-016: first placement enters Backlog. Source-state initialization is a distinct operation for absent records, not altered ordinary placement.
ADR-018: original additive proposal restrictions, existing-reference-only source impacts and valid-version-only application. Extend it with source-bound reconstruction payloads, explicitly blocked resumable drafts and a narrow atomic initializer.
ADR-020: new phases default Unassessed and lifecycle completion has an explicit guarded transition/history. Reconstruction needs initialization of explicit source lifecycle without a fabricated prior transition; existing Completed-phase immutability and consistency guards remain.
ADR-023: adoption uses ordinary task commands and separate evidence-backed completion. Reuse its inventory, exact reconciliation, guards and receipts; the new-record reconstruction initializer is a named exception, not a redefinition of generic adoption. Selected policy B additionally proposes the explicit historical-evidence threshold exception defined in section 2.

ADR-001 sole-store/typed authority, ADR-006 root/catalog safety, ADR-017 versioned source references and ADR-021 truthful event-time History remain constraints to preserve, not decisions to weaken. Any necessary schema changes belong to this bounded design and require implementation review; no portable format/export work follows.

The source-boundary amendment in section 1 additionally authorizes only non-operative document-to-projection preparation and a project-scoped plan_preparation admission in the existing coordinator; it does not grant ordinary execution or source-write permissions. This is a named new component-boundary decision, not an existing delivered capability.

Final owner acceptance of this exact Proposed ADR remains required before these new rules become governing. Proposal approval selected policy B and authorized ADR preparation only; it did not accept or publish this ADR or authorize dependent implementation.