project-tiny-context-harness 0.7.7 → 0.7.9

package/assets/skills/long-task-workflow/SKILL.md

@@ -25,6 +25,7 @@ Prefer the lowest practical Authoring, Runtime, State, Recovery and verification
 
 Read only the reference needed for the current phase; these files are guidance, not new artifacts or authority:
 
+- When inputs are raw, mixed, attachment-heavy, incomplete or need synthesis/refinement before Contract mapping, read [`references/source-authoring.md`](references/source-authoring.md) and author the needed self-contained meaning directly inside this workflow.
 - Before creating or structurally revising Source markers, Outcomes, requirements, controls, obligations, architecture boundaries, paths, Bindings, Assertions or risk, read [`references/contract-authoring.md`](references/contract-authoring.md).
 - Before creating or repairing Checks, runners, Observations, proof surfaces, Playwright/structured evidence, Counterfactuals, Population or environment probes, read [`references/evidence-design.md`](references/evidence-design.md).
 - Before Preflight, Compile, protected revision, resume, targeted verify, Final Gate, Stop, close or abandon, read [`references/authority-lifecycle.md`](references/authority-lifecycle.md).
@@ -43,20 +44,22 @@ A Draft Outcome is an Outcome in that pre-Authority-Lock Draft, not a new schema
 
 ## Entry And Authoring Loop
 
-1. Read the user request or external proposal plus minimum controlling Context and decide `Context Delta: none|required`.
+1. Read the user request or external initial proposal, selected design resources and minimum controlling Context. Collect the architecture owners, extension points and boundaries needed for the shared deliberation before deciding `Context Delta`.
    - For material production UI, read the Contract-authoring visual guidance before Compile. Inspect any external design resources as ordinary Source, including selection basis, stable identity and declared surface/viewport/mode/state coverage. An unconfigured starter, candidate, style-only rule or inspiration-only reference is incomplete design authority unless Source explicitly scopes the result as prototype/non-fidelity or supplies a selected target before implementation.
    - If the user is asking to generate or iterate standalone design resources before Contract authoring rather than execute this delivery, use `design-resource-authoring` instead. Its result may later return as ordinary Source; it creates no Contract Draft or Authority.
 2. If a valid active binding exists, run `ty-context long-task resume <workdir>` and read the lifecycle reference.
-3. Otherwise author one complete Delivery Contract for the whole selected delivery. Declare the target profile, its non-empty required product target refs, each target's runtime family/root entrypoint, ordered Stages and vertical Outcomes. Do not create a second Contract plan, matrix or top-level Contract split.
-4. Preserve at least one real `source_path`. Wrap every material Source item in its original Markdown with non-rendering `ty-source-item:start/end` markers without rewriting the text; marked Source Item keys and `source_claim` keys are exactly equal.
-5. An ordinary prose plan, optional Source Plan or externally authored design resource remains valid Source after marker-only enumeration and does not need to match a recommended authoring structure. Preserve stable semantic keys and Markdown anchors where practical. External design authoring neither updates Context nor creates Contract authority by itself; candidate resources authorize no fidelity Claim.
-6. Continue reading repository, Source and Context and revise the same Draft. A request to synthesize, refine, complete, implement or use judgment delegates plan-level authoring, but it does not invent the user's tradeoff priorities. Before comparative research or a material product, technical, architecture or provider selection, identify the criteria that could change the research scope, candidate set or recommendation. Infer them only from the user's words, Source, Context or controlling constraints. If quality versus cost, speed, reliability, privacy, lock-in, operational burden or another material priority is unknown or ambiguous, stop before that research or selection and ask one concise targeted clarification. Do not impose a questionnaire, re-ask known preferences or interrupt minor reversible choices whose recommendation would not change.
-7. Once the material preference envelope is clear, decide what research is needed. Use current authoritative or primary evidence for external capability, pricing, quota, license, compatibility, region, security posture or support claims. When one recommendation is then defensible, record it in real Source with the authoring instruction, preference/evidence basis and exact added meaning instead of pausing for approval. Append the delegated item without rewriting the user's original text when ordinary prose is the Source. Return only when authoritative requirements conflict, the user explicitly reserves the choice, a material preference remains unknown, critical semantics have no defensible recommendation or no falsifiable acceptance standard can be formed.
-8. Contract expansion remains limited to meaning-preserving structural decomposition, evidence-backed repository binding and choices first recorded as delegated real Source. Never place a new product rule, default, threshold, recovery behavior, permission or platform/data scope only in Contract YAML. Default plan delegation authorizes meaning, not action: payment, contracting, production deployment or publication, destructive production mutation, real permission grants, sensitive-data transmission and required legal/security/human approval remain named external confirmations. Any conflicting, user-reserved, missing-preference or unsupported semantic remains `decision_required`.
-9. Give every Check an atomic Given/When scenario and journey role; give every Assertion the minimum all-of Evidence Capabilities that can actually prove its Claim. Separate required success and degradation Checks. Type every external confirmation with impacted Claim refs and target-blocking effect. Run read-only `ty-context long-task preflight <workdir>`, repair every error and `decision_required` finding in the same Draft, then formally Compile only when ready.
-10. When the first Compile returns `execution_model_checkpoint.required: true`, stop before implementation and ask the user to choose `continue_current_model` or switch models and then resume the active Long-Task. A task-specific choice already stated explicitly satisfies the checkpoint. Later revisions return `required: false` and do not repeat it.
-
-Architecture quality uses the existing authority model, not a new gate: when Source or controlling Context declares an architecture invariant, encode it as a Source-backed technical obligation/global constraint/forbidden shortcut plus owner/path/Binding boundaries and a project-owned executable Check. Functional acceptance cannot substitute when the architecture claim can fail independently. An unverifiable design preference remains task-local, durable Context or `decision_required`; it must not be promoted into false proof.
+3. If the inputs are not yet self-contained, use the Source-authoring reference now. Inventory every proposal, selected design resource and attachment; preserve direct meaning; add only traceable derived/delegated meaning; enumerate material surfaces/controls/states and acceptance; and resolve or retain genuine decisions. Revise a supplied writable initial proposal when it is the delivery Source. If the request exists only in conversation, materialize exactly one project-native Markdown Source for this delivery. This is an internal authoring step in the same Goal, not a standalone Source Plan service, second plan, schema, gate or lifecycle.
+4. Otherwise author one complete Delivery Contract for the whole selected delivery. Declare the target profile, its non-empty required product target refs, each target's runtime family/root entrypoint, ordered Stages and vertical Outcomes. Do not create a second Contract plan, matrix or top-level Contract split.
+5. Preserve at least one real `source_path`. Wrap every material Source item in its original Markdown with non-rendering `ty-source-item:start/end` markers without rewriting direct text; marked Source Item keys and `source_claim` keys are exactly equal. Newly delegated meaning must first be written into that real Source with provenance before marking.
+6. An ordinary prose proposal, legacy Source Plan or externally authored design resource remains valid Source and does not need to match a recommended structure. Preserve stable semantic keys and Markdown anchors where practical. Selected resources retain their stable resource/surface/control/state/target keys, declared coverage, provider/project/run/entry provenance and immutable digest/snapshot; candidates authorize no fidelity Claim.
+7. Continue reading repository, Source and Context and revise the same Draft. A request to synthesize, refine, complete, implement or use judgment delegates plan-level authoring, but it does not invent the user's tradeoff priorities. Before comparative research or a material product, technical, architecture or provider selection, identify the criteria that could change the research scope, candidate set or recommendation. Infer them only from the user's words, Source, Context or controlling constraints. If quality versus cost, speed, reliability, privacy, lock-in, operational burden or another material priority is unknown or ambiguous, stop before that research or selection and ask one concise targeted clarification. Do not impose a questionnaire, re-ask known preferences or interrupt minor reversible choices whose recommendation would not change.
+8. Once the material preference envelope is clear, decide what research is needed. Use current authoritative or primary evidence for external capability, pricing, quota, license, compatibility, region, security posture or support claims. When one recommendation is then defensible, record it in real Source with the authoring instruction, preference/evidence basis and exact added meaning instead of pausing for approval. Append the delegated item without rewriting the user's original text when ordinary prose is the Source. Return only when authoritative requirements conflict, the user explicitly reserves the choice, a material preference remains unknown, critical semantics have no defensible recommendation or no falsifiable acceptance standard can be formed.
+9. Contract expansion remains limited to meaning-preserving structural decomposition, evidence-backed repository binding and choices first recorded as delegated real Source. Never place a new product rule, default, threshold, recovery behavior, permission or platform/data scope only in Contract YAML. Default plan delegation authorizes meaning, not action: payment, contracting, production deployment or publication, destructive production mutation, real permission grants, sensitive-data transmission and required legal/security/human approval remain named external confirmations. Any conflicting, user-reserved, missing-preference or unsupported semantic remains `decision_required`.
+10. Before formal Compile and the first implementation edit, complete the shared `Architecture Deliberation` once and surface concise repository-bound conclusions rather than private reasoning. Cover the current owner/extension point/source of truth, dependencies and lifecycle, selected and rejected alternatives, a plausible future-change challenge, touched debt and its disposition, forbidden shortcuts and project-owned Checks. Even a preservation result names concrete owners and why no new or worsened debt is introduced. Put durable conclusions in owning Context and material falsifiable delivery conclusions in real marked Source plus existing Contract fields, then decide `Context Delta: none|required`. A material scope, owner, Context or design change before implementation stales and refreshes the deliberation.
+11. Give every Check an atomic Given/When scenario and journey role; give every Assertion the minimum all-of Evidence Capabilities that can actually prove its Claim. Separate required success and degradation Checks. Type every external confirmation with impacted Claim refs and target-blocking effect. Run read-only `ty-context long-task preflight <workdir>`, repair every error and `decision_required` finding in the same Draft, then formally Compile only when ready.
+12. When the first Compile returns `execution_model_checkpoint.required: true`, stop before implementation and ask the user to choose `continue_current_model` or switch models and then resume the active Long-Task. A task-specific choice already stated explicitly satisfies the checkpoint. Later revisions return `required: false` and do not repeat it.
+
+Architecture quality uses the existing authority model, not a new gate or field. The visible deliberation proves that architecture work occurred, not that subjective quality is machine-proven. Encode every material falsifiable invariant as a Source-backed technical obligation/global constraint/forbidden shortcut plus owner/path/Binding boundaries and a project-owned executable Check. Functional acceptance cannot substitute when the architecture claim can fail independently. An unverifiable design preference remains task-local, durable Context or `decision_required`; it must not be promoted into false proof.
 
 ## Rolling Execution
 
@@ -64,6 +67,8 @@ After Authority Lock and the one-time execution-model checkpoint are satisfied,
 
 Re-evaluate `Context Delta` whenever implementation or repair discovers a durable fact. Controlling Context changes use protected revision; graph-derived, non-explicit `implementation-index` and `archive` are Supporting Context in referenced mode and may auto-revise when only navigation/background changed. Full snapshot mode treats every selected Context file as controlling.
 
+If rolling implementation materially changes scope, ownership, dependency direction, the selected design or a debt disposition, refresh the Architecture Deliberation and express any authority change through marked Source/Context plus protected revision before continuing. This is refinement of the same checkpoint, not a second workflow stage.
+
 Use targeted `verify --outcome/--check` only to drive repair. Progress is repair evidence only and never acceptance authority. Keep precise findings attached to the owning Source item, Claim, Assertion, Check, Binding and owner path. Do not add another model-switch pause or coordinate parallel subagents.
 
 When the Contract declares a target-runtime Check because a proxy can pass while the target fails independently, run it at the earliest owning Outcome's first runnable boundary. Every required target is proved separately from its root; Browser evidence requires Playwright and Native/Desktop evidence requires the project binary. After accumulated changes to declared `input_paths` or Binding carriers make the result stale, rerun before dependent work grows. Coalesce related edits and use the cheapest reliable target Check; do not mandate a full environment rebuild per Outcome or per edit. This is rolling feedback through existing targeted verify, not acceptance, a trigger queue or per-target progress state.
@@ -76,10 +81,12 @@ Complete Context, implementation and project tests, create a clean candidate com
 
 Final Gate recompiles Source authority, validates active task/revision/compiled/worktree identity, creates one Git-tree snapshot, reruns every required Global and Outcome Check and rechecks active identity before acceptance. It derives Stage results and target qualification from that run; it does not trust targeted Progress as a Stage pass. A target-runtime Check must exercise its exact target in that current Gate execution; rerunning a reader for a historical or tracked status report is not live target proof. Final Gate, Stop and close never trust historical Progress, Receipt or compiled cache.
 
+Final Gate is the Long-Task path's sole `Architecture Conformance` carrier. It reruns the declared architecture obligations/constraints/forbidden shortcuts, owner/path/Binding boundaries and project-owned Checks on that same snapshot and blocks scope escape, bypass, duplicate authority, a second source of truth, wrong dependency direction, undeclared boundary change or new/worsened debt represented by those invariants. Do not also run the default Workflow's standalone Contract Conformance closure. Any later candidate or authority change invalidates the Gate and uses the existing freshness path again.
+
 Machine acceptance covers only declared machine authority. Preserve every pending external confirmation through `final-gate`, `status`, `resume`, `stop-check`, the package-owned Stop Hook and `close`; accepted output identifies `acceptance_scope: declared_machine_authority` and `native_goal_effect: none`, while `closed_scope: machine_authority` means only Authority cleanup. Do not invent external-confirmation or native-Goal tracking state.
 
 Before invoking platform-native Goal completion, perform one veto-only conformance review: compare the current Goal and user instructions with accepted marked Source, and check for pending revisions, unresolved blockers or omitted requirements. Any mismatch keeps the Goal active and returns to Source/Contract repair. A clean review does not add acceptance proof and never lets Agent judgment replace Final Gate.
 
 ## Handoff
 
-Report implementation, effective risk, Claim Coverage, Stage frontier/results, declared target profile, exact `target_state`, Live Gate result, acceptance scope, every pending external confirmation, Context status and blockers. Use verifier terms exactly: `progress_passing` means targeted repair evidence, `progress_stale` is not a current pass, `final_workflow_status: null` means unfinished, `authority_revision_adopted` means return to rolling execution, and `machine_accepted_external_pending` must retain its named confirmations. Contract target states are only `implementation_complete`, `target_profile_usable` and `production_release_ready`; terminal failure uses `not_accepted` or `blocked_external`. Never shorten targeted progress to “Outcome complete” or invent per-platform progress/status. State the threat-model limits: undeclared requirements cannot be discovered, installed verifier/Git metadata are trusted, native-Goal/model selection belongs to the host/user, and internal platform delegation is not observed.
+Report implementation, effective risk, Architecture Deliberation/Conformance status, Claim Coverage, Stage frontier/results, declared target profile, exact `target_state`, Live Gate result, acceptance scope, every pending external confirmation, Context status and blockers. Use verifier terms exactly: `progress_passing` means targeted repair evidence, `progress_stale` is not a current pass, `final_workflow_status: null` means unfinished, `authority_revision_adopted` means return to rolling execution, and `machine_accepted_external_pending` must retain its named confirmations. Contract target states are only `implementation_complete`, `target_profile_usable` and `production_release_ready`; terminal failure uses `not_accepted` or `blocked_external`. Never shorten targeted progress to “Outcome complete” or invent per-platform progress/status. State the threat-model limits: the visible checkpoint cannot prove private reasoning or universal future-proofing, undeclared requirements cannot be discovered, installed verifier/Git metadata are trusted, native-Goal/model selection belongs to the host/user, and internal platform delegation is not observed.

package/assets/skills/long-task-workflow/references/authority-lifecycle.md

@@ -48,7 +48,7 @@ Report their exact meaning: `progress_passing` is current targeted repair eviden
 
 ## Final Gate And Terminal Paths
 
-Before Final Gate, complete Context/code/tests and create a clean candidate commit. Final Gate captures active identity, recompiles Source authority, reads complete current Context, validates common-dir record/marker, creates a Git-tree snapshot, reruns all Checks and sensitivity controls and rechecks identity before acceptance. A target-runtime Check must exercise its exact target again in that Final Gate execution; rereading historical status does not become live proof merely because the reader reran. The Receipt reports the target profile/state and every Stage as `passed`, `failed`, `blocked_external` or `blocked_dependency`. A concurrent revision returns `active_authority_changed_during_final_gate`.
+Before Final Gate, complete Context/code/tests and create a clean candidate commit. Final Gate captures active identity, recompiles Source authority, reads complete current Context, validates common-dir record/marker, creates a Git-tree snapshot, reruns all Checks and sensitivity controls and rechecks identity before acceptance. This is the sole Long-Task `Architecture Conformance` carrier: material deliberation conclusions must already be declared through existing obligations/constraints/forbidden shortcuts, owners/paths/Bindings and project-owned Checks, and no separate default Contract Conformance closure runs. A target-runtime Check must exercise its exact target again in that Final Gate execution; rereading historical status does not become live proof merely because the reader reran. The Receipt reports the target profile/state and every Stage as `passed`, `failed`, `blocked_external` or `blocked_dependency`. A concurrent revision returns `active_authority_changed_during_final_gate`.
 
 Commit, verifier migration, clear and abandon share one active-state lock. Stop/close clear only the identity actually accepted through CAS and preserve `machine_accepted_external_pending` plus every named external confirmation in output. Final Gate/Stop/close identify `acceptance_scope: declared_machine_authority` and `native_goal_effect: none`; close additionally identifies `closed_scope: machine_authority`. The Stop Hook emits the same scope as one non-blocking message for either accepted machine status. A stale Receipt exposes no accepted workflow status.
 

package/assets/skills/long-task-workflow/references/contract-authoring.md

@@ -9,7 +9,8 @@ Read this only while authoring or structurally revising the one `delivery-contra
 - Typed dispositions keep Result, Requirement, Control, Technical Obligation, Non-completing Claim, Acceptance, Global Constraint/Non-goal, Forbidden Shortcut, Risk, External Confirmation and Decision distinct.
 - Every non-decision Source item owns exactly one same-kind, text-identical canonical target; no target may collapse multiple Source items. `out_of_scope` is not a resolution.
 - A Source AC maps criterion-identically to one named Assertion and proves at least one independently Source-backed non-Result Claim.
-- Missing recommended Source Plan headings or keys never blocks authoring. Missing mandatory Material Source Item markers does.
+- Missing recommended legacy Source Plan headings or keys never blocks authoring. When raw/mixed inputs are not self-contained, use `source-authoring.md` inside this workflow before Contract mapping. Missing mandatory Material Source Item markers does block activation.
+- A revised initial proposal and selected design resources are parallel Source inputs. Preserve their stable resource/surface/control/state/target keys, declared conditions, provider/project/run/entry provenance and immutable digest/snapshot; do not flatten visual meaning into an untraceable prose summary.
 - `delegated` in a Source Plan is provenance, not a Contract disposition or new Claim kind. An instruction to synthesize, refine, complete, implement or use judgment delegates plan-level authoring, but it does not invent material tradeoff preferences. Before comparative research or a material product, technical, architecture or provider selection, identify the criteria that could change the research scope, candidate set or recommendation. If such a preference is unknown or ambiguous, ask a concise targeted question before research or selection and keep the item `decision_required` until answered; do not impose a fixed questionnaire or re-ask preferences already supplied by the user, Source, Context or controlling constraints.
 - Once the material preference envelope is clear, use current authoritative or primary evidence for external capability, price, quota, license, compatibility, region, security posture or support claims. When one defensible recommendation exists, record the authoring instruction, preference/evidence or conservative-default basis and exact added meaning in real Source, then preserve that keyed item as ordinary Source of its semantic kind. If ordinary prose is the Source, append the delegated item without rewriting the user's original text; never place the choice only in Contract YAML.
 - A delegated plan choice is not action authorization. Payment, contracting, production deployment/publication, destructive production mutation, real permission grants, sensitive-data transmission and required legal/security/human approval remain named External Confirmations. Conflicting authority, an explicitly user-reserved choice, a missing material preference or the absence of a defensible recommendation remains `decision_required`; high impact or multiple options with known criteria alone does not.
@@ -39,11 +40,11 @@ Global non-goals, constraints and forbidden shortcuts remain Global authority an
 - `task.target_profile` declares `required_state` plus a non-empty, duplicate-free `required_target_refs`. Each ref resolves to a `product` execution target with one bounded runtime family and root entrypoint. Every Stage Gate and every `critical_user_path` Outcome provides root `target_runtime` proof for every required ref; optional support/observer targets never substitute.
 - Use `implementation_complete` only when code-level implementation is the selected target, `target_profile_usable` when the declared required targets must be usable, and `production_release_ready` only when release gates are part of the selected target. These are terminal target qualifications, not Outcome progress states.
 
-## Architecture Closure
+## Architecture Deliberation And Closure
 
-Architecture protection is risk-triggered and project-specific. Use it when the delivery declares module ownership, unique source of truth, dependency direction, API/schema/data boundary, state lifecycle, persistence/recovery, security boundary, compatibility/migration or a forbidden bypass.
+Architecture Deliberation occurs once for every implementation delivery before formal Compile and the first implementation edit; risk changes depth, not occurrence. Surface concise conclusions and repository evidence rather than private chain-of-thought. A preservation result still names the concrete owner/extension point and explains why durable boundaries and debt do not worsen. Material work covers module ownership, unique source of truth, dependency direction, API/schema/data boundary, state lifecycle, persistence/recovery, security boundary, compatibility/migration, selected and rejected alternatives, one plausible future-change challenge, touched technical debt and forbidden bypasses.
 
-Represent the invariant with existing Contract fields:
+Represent every material falsifiable invariant with existing Contract fields:
 
 1. a Source-backed technical obligation, global constraint or forbidden shortcut;
 2. owner Context and expected/support/forbidden paths;
@@ -51,7 +52,9 @@ Represent the invariant with existing Contract fields:
 4. a project-owned executable architecture check, such as the repository's lint, AST, dependency or contract test;
 5. a separate Assertion when functional behavior could pass while the architecture invariant fails.
 
-Do not encode subjective “clean architecture” or generic quality prose as machine authority. If no reliable observation can falsify it, keep it as durable Context/review judgment or return `decision_required`. Harness routes the repository's architecture check; it does not become a language-generic dependency analyzer.
+New or worsened debt is unacceptable unless a project-owned bounded exception identifies owner, rationale, tracking and removal/expiry condition. Unrelated legacy debt does not automatically expand delivery scope, but debt touched, relied on or worsened by the implementation cannot remain hidden. Material changes to scope, owner, Context, dependency direction, selected design or debt disposition refresh the deliberation and, after Authority Lock, use protected revision.
+
+Do not encode subjective “clean architecture” or generic quality prose as machine authority. If no reliable observation can falsify it, keep it as durable Context/review judgment or return `decision_required`. Harness routes the repository's architecture check; it does not become a language-generic dependency analyzer. Final Gate is the only Long-Task Architecture Conformance carrier and reruns these declared Checks on its current snapshot; do not add a default-workflow closure, architecture field, second Gate or state.
 
 ## Proxy And Target Runtime Independence
 
@@ -91,7 +94,7 @@ When the selected delivery includes a new/redesigned screen, primary layout/navi
 - keep subjective visual direction, taste or approval outside false machine proof. Resolve an undecided direction as `decision_required`; represent required human design or new-baseline approval as an explicit external confirmation.
 - for combined design-and-implementation delivery, ordinary design Outcomes/Stages may author candidates before selection, but candidate/planned artifacts cannot authorize fidelity Claims. Append the selected result to real marked Source and the owning registry/target input; after Authority Lock adopt it through the existing protected revision before downstream fidelity implementation. This creates no target-selection state, second Contract or second Gate.
 
-External authored design resources remain ordinary upstream Source rather than a Contract Draft, verification result or alternate authority. This guidance adds no UI-specific Contract block, Claim kind, risk level, lifecycle state, required design package, design directory or Gate. The additive generic Control fields only preserve Source meaning through existing Source, Requirement/Control/Assertion, Stage, Binding, proof-surface, verification-input, revision and external-confirmation mechanisms.
+External authored design resources remain ordinary upstream Source rather than a Contract Draft, verification result or alternate authority. The revised initial proposal plus selected immutable resources is the recommended upstream input; no standalone Source Plan handoff is required. A legacy Source Plan remains valid ordinary Source if supplied. This guidance adds no UI-specific Contract block, Claim kind, risk level, lifecycle state, required design package, design directory or Gate. The additive generic Control fields only preserve Source meaning through existing Source, Requirement/Control/Assertion, Stage, Binding, proof-surface, verification-input, revision and external-confirmation mechanisms.
 
 ## Compact Authoring
 

package/assets/skills/long-task-workflow/references/source-authoring.md

@@ -0,0 +1,98 @@
+# Integrated Source Authoring Reference
+
+Read this when raw, mixed, attachment-heavy or incomplete inputs need to become self-contained delivery Source before Contract mapping. This work occurs inside the same `long-task-workflow` Goal and feeds the same Contract Draft; it is not a standalone Source Plan stage or second lifecycle.
+
+## Objective and boundary
+
+Preserve every material user, product, technical, visual and acceptance constraint from the initial/revised proposal and supplied resources. Add only traceable necessary derivations, defensible delegated choices and evidence-backed repository facts. Make the real Source understandable without the original conversation.
+
+Do not create a Source Plan schema, CLI, Preflight, Compile, Receipt, cache, authority or state. Do not bind a choice only in Contract YAML. Do not let current implementation silently redefine intent. A pre-existing Source Plan is simply one possible input.
+
+## Input inventory
+
+1. Assign every proposal, selected design resource, screenshot, document, diagram, table and other attachment a stable input ID.
+2. Inspect all material pages/frames/screens/tables/visible states; never silently sample a multi-part artifact.
+3. Classify each input as user instruction, product requirement, technical constraint, existing proposal, selected target, repository/Context evidence, constraint, inspiration or background.
+4. For visual resources, preserve selection basis, classification (`exact-target`, `constraint` or `inspiration`), stable resource/surface/control/state/target keys, declared platform/viewport/mode/state/content coverage, provider/project/run/entry provenance and immutable digest/snapshot. Unselected candidates authorize no fidelity.
+5. Record incorporated meaning and every unreadable, conflicting or intentionally unused part. Higher authority and user-stated precedence win; unresolved conflicts remain decisions.
+
+## Preference and research gate
+
+Before comparative research or a material product, technical, architecture or provider selection, identify decision-changing criteria such as fidelity versus cost, delivery speed, reliability/support, privacy/compliance, lock-in/control, operational burden, platform scope and extensibility.
+
+Infer preferences only from user words, Source, Context or controlling constraints. If an unknown preference would materially change research or recommendation, ask one concise targeted clarification before proceeding. Do not impose a questionnaire, re-ask known preferences or pause for minor reversible choices with the same defensible recommendation.
+
+Use current primary/authoritative evidence for changing external facts. Record source, scope and retrieval date. Preference clarification authorizes plan meaning, not payment, contracting, deployment/publication, destructive production mutation, permission grants, sensitive-data transmission or required legal/security/human approval; those remain typed external confirmations.
+
+## Authoring modes
+
+Infer rather than ask the user to choose:
+
+- **refinement:** preserve and complete a substantially developed proposal;
+- **synthesis:** build coherent Source from a goal plus mixed inputs;
+- **hybrid:** use one proposal as backbone and fill gaps from other inputs.
+
+A short request is sufficient when roles, goal and reference authority are recoverable. Reuse an authorized writable proposal as the real Source. If the delivery exists only in conversation, materialize exactly one project-native Markdown Source according to repository convention. Do not create a parallel planning artifact.
+
+## Semantic authoring
+
+For every material item, preserve one origin:
+
+- `direct`: stated by user or controlling input, with all qualifiers;
+- `derived`: unavoidable for completeness/falsifiability, identifies `Derived From`, states why necessary and changes no user capability, business rule or scope;
+- `delegated`: a defensible choice requested by instructions to synthesize/refine/use judgment, records `Delegated By`, preference/evidence basis and exact added meaning;
+- `evidence-backed`: repository/Context fact with exact source and no promotion of incidental code shape to product intent;
+- `decision_required`: conflicting authority, explicitly user-reserved choice, missing material preference or no defensible recommendation.
+
+High impact or several options is not itself a reason to pause when criteria support one recommendation. Keep real high-risk actions as external confirmations. Never introduce a requirement for the first time only inside acceptance criteria.
+
+## Structure and stable keys
+
+Use stable semantic lowercase-kebab keys and Markdown anchors where practical. Preserve keys when wording changes but meaning does not; never renumber for ordering or reuse a retired key for new meaning.
+
+Define vertical Outcomes only when observable results are independently decidable and later verifiable. Do not split by response length, frontend/backend layer, module count, agent capacity or desired parallelism; do not merge distinct results merely for brevity.
+
+Use only applicable semantic types:
+
+- result/Outcome;
+- Requirement (`REQ`);
+- user-visible Control (`CTRL`);
+- technical obligation (`OBL`);
+- explicitly non-completing meaning (`NCOMP`);
+- acceptance scenario (`AC`);
+- global non-goal/constraint and forbidden shortcut;
+- risk with exact Fact, Affected Outcome, Basis and Consequence;
+- external confirmation (`EXT`);
+- genuine decision (`DEC`);
+- advisory implementation hint (`HINT`), which is not a material requirement.
+
+## UI and control completeness
+
+For each in-scope surface, record purpose, entry/exit/navigation, regions/overlays and included Control keys. For every material interactive control, independently preserve applicable:
+
+`surface`, `region`, `control type`, `label/content`, `location`, `user task`, `visibility`, `availability`, `trigger`, `input`, `validation`, `default`, `interaction`, `navigation/result`, `loading`, `empty`, `success`, `failure`, `recovery`, `permission`, `feedback` and `accessibility`.
+
+Do not invent controls for a non-interface delivery. A coarse frame or configured design system does not supply unshown states. Selected design resources and product/technical Source remain parallel: visuals cannot invent business/data/permission/algorithmic rules.
+
+## Acceptance and risk
+
+Each AC has exactly one Given/When/Then scenario, names the REQ/CTRL/OBL/NCOMP meaning it accepts and introduces no undeclared product semantics. Keep representative/sample/framework checks distinct from full-population claims and partial delivery distinct from completion.
+
+Use the Runtime's exact risk Fact names when marking risk. Data migration is `data_migration`; a weakly observable critical path is separate `critical_user_path` and `weak_observability` facts; preserve `multi_repository_change` in Source so Contract compilation can reject unsupported delivery honestly.
+
+## Completeness audit
+
+Before Contract mapping confirm:
+
+1. Every material original statement and qualifier is preserved.
+2. Every supplied input is incorporated or has an explicit unreadable/unused/conflict disposition.
+3. Distinct requirements and independently decidable Outcomes were not collapsed.
+4. Every material UI surface/control/state is explicit or marked not applicable/unresolved.
+5. Every REQ and material CTRL state has acceptance, external confirmation, decision or explicit exception.
+6. Derived/delegated/evidence-backed items have traceable basis and no hidden product expansion.
+7. Non-goals, forbidden shortcuts, risks and recovery are concrete.
+8. No unsupported number, threshold, metric or external claim appears.
+9. Selected design resources retain stable identity and exact declared coverage; candidates remain non-authoritative.
+10. The Source is self-contained enough for Contract authoring and names every still-required external artifact.
+
+Then add non-rendering `ty-source-item:start/end` markers to the real Markdown Source without rewriting direct text, and proceed to `contract-authoring.md`. The markers and Contract mapping are part of this same Long-Task authoring loop.