# AWP Planning Decision Register **Date:** 2026-08-19 **Status:** Durable traceability checkpoint for the active Planning design/specification work. **Purpose:** Preserve every material Planning decision from the design conversation so conversation compaction or agent/session replacement cannot erase product intent. > This register is a traceability map, not a competing source of truth. Canonical behavior belongs in the linked specs/design documents. If this register and a canonical spec disagree, the discrepancy must be reconciled explicitly rather than silently choosing one. ## 1. Core Planning product contract Planning is not chat -> `PLAN.md` and not a fixed wizard. AWP Planning owns durable structured state and must continuously answer: ```text What did I ask for? What are we doing now? What has already been decided? Why did AWP choose this? What remains unresolved? What is blocked/deferred? What happens next? Can I change a technical decision? ``` The user must never need to reconstruct these answers from chat history. Canonical: [`../specs/domains/planning.md`](../specs/domains/planning.md), [`AWP-PLANNER-LEADERSHIP-UX.md`](AWP-PLANNER-LEADERSHIP-UX.md), [`AWP-PLANNING-UX-DESIGN.md`](AWP-PLANNING-UX-DESIGN.md). ## 2. Planner leads the conversation The Planner is proactive. It does not wait for the user to remember the next Planning topic. Every substantive turn should: ```text answer current input -> update structured Planning state -> detect gaps/contradictions/risks -> decide whether the current area is sufficiently resolved -> choose the highest-value next unresolved item -> present what is next ``` The Planning UX mental model is: ```text LEFT / Plan Index What did I ask for? CENTER / Current What are we doing now? RIGHT / Context Why / impact / confidence / evidence / what next? PLANNER owns the agenda and advances it automatically ``` The user may interrupt, reorder or park non-blocking work, but should not have to lead the Planning process. Canonical: [`AWP-PLANNER-LEADERSHIP-UX.md`](AWP-PLANNER-LEADERSHIP-UX.md), [`../specs/workflows/interactive-planning.md`](../specs/workflows/interactive-planning.md). ## 3. Stable Planning landmarks, dynamic content The stable Plan Index landmarks are: ```text DEFINE DESIGN SPECIFY DELIVER LAUNCH ``` Children are generated from PlanningProfile and discovered project traits. This is not a hard-coded universal wizard. Examples: - CLI projects may have no Pages section. - UI-heavy products may have many page specs. - security-heavy systems may expand threat/security planning. - existing projects may add Current Architecture, Migration, Compatibility or observed-state sections. Canonical: [`AWP-PLANNING-UX-DESIGN.md`](AWP-PLANNING-UX-DESIGN.md), [`../specs/domains/planning.md`](../specs/domains/planning.md), [`../specs/ui/planning.md`](../specs/ui/planning.md). ## 4. Simple and Expert Planning modes Planning has two participation modes. They change **user participation**, not Planning completeness, correctness or authority. ### Simple User conversation concentrates on decisions that genuinely belong to the owner: ```text product direction scope/non-goals who the product serves experience/taste pricing/business model customer/business policy budget ceilings risk acceptance market/customer commitments ``` AWP resolves technical expert decisions visibly without repeatedly asking the user to approve routine engineering choices. The technical plan builds in front of the user in the Plan Index/technical summaries. The user can inspect, challenge or change it whenever desired. ### Expert The same complete Plan exists, but technical recommendations become normal conversational review/refutation decisions: ```text architecture security design storage/data framework/library choices Quality/testing CI CD/release/deployment execution topology technical integrations observability ``` Expert still remains recommendation-first, not a blank questionnaire. ### Mode hierarchy ```text explicit Plan override > Project preference > user-global preference > product default: Simple ``` Mode switching preserves all structured state. Canonical: [`../specs/domains/planning.md`](../specs/domains/planning.md), [`../specs/workflows/interactive-planning.md`](../specs/workflows/interactive-planning.md), [`../specs/ui/planning.md`](../specs/ui/planning.md). ## 5. Decision participation classes Every material Planning decision is classified before AWP decides how to handle it: ```text OwnerRequired DelegableExpert PolicyRequired ``` ### OwnerRequired AWP may recommend but may not silently decide because the choice expresses owner intent, preference, business policy, pricing, customer commitment, budget/risk acceptance or equivalent. ### DelegableExpert AWP may decide using evidence, project defaults, accepted constraints and industry-grounded engineering judgment. The decision must remain visible, attributable, inspectable and changeable. ### PolicyRequired Explicit authorization/approval/consent is required regardless of Simple/Expert mode, for example OAuth/provider authorization, configured production approval, destructive actions, capability broadening, security exceptions and configured spend/security/HITL gates. When a technical uncertainty affects an owner consequence, Simple mode asks about the **consequence**, not engineering jargon. Example: ```text Do you require customer data to remain in the EU? ``` not: ```text Which cloud-region topology do you want? ``` Canonical: [`../specs/domains/planning.md`](../specs/domains/planning.md). ## 6. Planning Profile inference The user should not begin by classifying the project through a template picker. AWP infers a PlanningProfile from the conversation and existing project evidence, displays the inference, and provides `Change`. Low-confidence inference becomes a recommendation with a small number of credible alternatives. Changing profile previews the Planning sections affected and does not silently delete accepted decisions. PlanningProfile describes **what planning work is required**, not delivery methodology. Canonical: [`../specs/domains/planning.md`](../specs/domains/planning.md), [`../specs/workflows/project-onboarding.md`](../specs/workflows/project-onboarding.md). ## 7. New/existing Project entry Project onboarding begins with user intent, not a large template/configuration wizard. Working entry model: ```text + New Project What are we working on? [ Start something new ] [ Bring in an existing project ] ``` New projects ask for minimal initial intent and enter Planning immediately. Existing projects connect/identify the repository and AWP inspects repository evidence before asking questions that source/config/docs can already answer. Canonical: [`../specs/workflows/project-onboarding.md`](../specs/workflows/project-onboarding.md), [`AWP-PLANNING-MODULE-DESIGN.md`](AWP-PLANNING-MODULE-DESIGN.md). ## 8. Existing-project truth conflicts remain distinct AWP never collapses contradictory evidence into one invented truth. Keep distinct: ```text ObservedCurrentState DocumentedIntendedState UserDesiredState AWPRecommendation ``` A material conflict becomes a Finding/Decision rather than silent overwrite. Canonical: [`../specs/domains/planning.md`](../specs/domains/planning.md), [`../specs/workflows/project-onboarding.md`](../specs/workflows/project-onboarding.md), [`../specs/ui/planning.md`](../specs/ui/planning.md). ## 9. Recommendation-first decision UX For material recommendations AWP shows: ```text recommendation confidence: high | medium | low basis material consequences what would change the recommendation credible alternatives when useful ``` Do not invent numeric confidence without a calibrated model. Normal comparisons show roughly 2-4 credible alternatives, not a wall of options. One primary action remains visually dominant. Canonical: [`../specs/domains/planning.md`](../specs/domains/planning.md), [`../specs/ui/planning.md`](../specs/ui/planning.md). ## 10. Context-following right rail The Context rail follows the current Planning item rather than becoming a second permanent navigation tree. Typical contents: ```text Current decision Recommendation Why / basis Confidence Evidence Consequences Impact Affected artifacts Open risks/questions What is next ``` Items may be pinned. Full Decisions/Risks/Artifacts/OpenQuestions collections remain accessible elsewhere but are not all permanent competing tabs. Canonical: [`AWP-PLANNING-UX-DESIGN.md`](AWP-PLANNING-UX-DESIGN.md), [`../specs/ui/planning.md`](../specs/ui/planning.md). ## 11. Plan Index progressive disclosure For large Plans: ```text current group expanded next unresolved group partially visible completed groups collapsed to summary blockers/deferred remain visible even when parents collapse ``` Search/filter and direct Review/Change paths are required. Selected/focus state should be URL-restorable where practical. Canonical: [`../specs/ui/planning.md`](../specs/ui/planning.md). ## 12. Now / Next / Later agenda The Planner maintains an explicit agenda: ```text Now Next Later ``` Priority considers blockers, high-impact owner/policy decisions, risks that invalidate downstream work, the next gate, and decisions that unlock several artifacts. The user may reorder/park non-blocking items without turning Planning into a manual wizard. Canonical: [`../specs/domains/planning.md`](../specs/domains/planning.md), [`../specs/workflows/interactive-planning.md`](../specs/workflows/interactive-planning.md), [`../specs/ui/planning.md`](../specs/ui/planning.md). ## 13. Readiness is gate-based Do not use arbitrary completion percentages. Readiness must explain both: ```text What can proceed now? What remains required later? ``` Working states: ```text Not ready Ready Ready with accepted/deferred gaps Blocked ``` Deferral is durable structured state and names the future gate where it becomes blocking. Canonical: [`../specs/domains/planning.md`](../specs/domains/planning.md), [`../specs/ui/planning.md`](../specs/ui/planning.md). ## 14. Research & Validation is conditional Research/validation is a Planning capability, not a compulsory universal ceremony. Recommend it when uncertainty and consequence justify it, such as unvalidated user assumptions or a high-risk new workflow. Synthetic/model personas are not evidence. Material skipped validation may become an accepted risk when policy permits. UX-researcher/UX-designer methods are tools for AWP/the designer to reason better; they are not mandatory operating instructions imposed on the project owner. Canonical: [`../specs/domains/planning.md`](../specs/domains/planning.md), [`AWP-PLANNING-UX-RESEARCH-AUDIT.md`](AWP-PLANNING-UX-RESEARCH-AUDIT.md). ## 15. ProjectPlanningDefaults and first Expert Plan Preferred flow: ```text first substantial Plan in Expert mode -> deeply establish technical recommendations -> AWP identifies reusable/default-eligible decisions -> user explicitly accepts promotion set -> ProjectPlanningDefaults later Plans in Simple mode -> inherit Project defaults -> AWP resolves technical deltas -> user conversation concentrates on new owner decisions ``` A Plan-specific exception never silently changes Project defaults. Canonical: [`../specs/domains/planning.md`](../specs/domains/planning.md). ## 16. Quality and CI are first-class Planning outputs AWP owns CI planning because AWP owns Planning and CI lifecycle control. Each relevant Plan resolves a visible recommendation that includes testing/verification methodology and CI design. The user can accept the recommendation or enter a deeper Expert discussion. `QualityStrategy` and `CIPlan` are first-class Planning outputs. Canonical: [`AWP-QUALITY-CI-PLANNING-DESIGN.md`](AWP-QUALITY-CI-PLANNING-DESIGN.md), [`../specs/INDEX.md`](../specs/INDEX.md). ## 17. Smallest-meaningful-verification discipline Binding quality principle: > Use the smallest check that can meaningfully falsify the implementation. Broaden only for a concrete reason. Stop when sufficient evidence exists. AWP must not equate more testing with better verification. Rules include: - test the behavior changed, not the whole application by default; - prefer focused regression tests and affected-package/static checks; - bug fixes should get regression tests when practical; - new behavior gets focused tests that would fail before the change where practical; - do not repeatedly run broad suites/builds/smoke tests as a substitute for reasoning; - smoke testing establishes basic operability, not feature correctness; - broaden for shared infrastructure/contracts, broad dependency impact, targeted failure discovery, required completion gates or final pre-merge/release qualification; - stop retesting a property once sufficient still-valid evidence exists; - never weaken meaningful tests merely to get green. The decision tree is: ```text CHANGE -> What can actually detect a mistake in this change? local logic -> focused unit/regression types/contracts -> targeted typecheck static/format -> targeted lint integration -> focused integration user flow -> focused E2E/browser -> Did that establish correctness? yes -> STOP no -> broaden carefully ``` Canonical: [`AWP-QUALITY-CI-PLANNING-DESIGN.md`](AWP-QUALITY-CI-PLANNING-DESIGN.md). ## 18. Verification enforcement is outside agents This methodology is enforced, not merely recommended in prompts. Agents may request/run checks, but agents do not authoritatively declare verification complete. AWP owns a verification authority layer conceptually containing: ```text ChangeClassifier VerificationPlanner VerificationAdmission EvidenceLedger EvidenceInvalidator GateEvaluator ``` Lifecycle gates reuse valid evidence rather than blindly repeating the same checks: ```text TaskVerificationGate -> ReviewVerificationGate -> ChangeSetCompletionGate -> MergeGate -> ReleaseGate -> DeploymentGate ``` A review agent receives existing evidence and adds verification only for newly discovered risks. If it changes code, affected evidence is invalidated and the smallest necessary checks run again. Broad verification requests require a reason. Arbitrary shell commands do not become authoritative verification merely because an agent ran them. Canonical: [`AWP-VERIFICATION-ENFORCEMENT-DESIGN.md`](AWP-VERIFICATION-ENFORCEMENT-DESIGN.md). ## 19. CI/CD/deployment/execution recommendation is integrated Every relevant Plan automatically presents the inferred/recommended technical delivery setup. The user is not asked another generic question merely to expose it. The recommendation covers, as applicable: ```text Quality/testing CI release strategy CD behavior EnvironmentStrategy PromotionPolicy DeploymentStrategy DeploymentProvider rollback/recovery ExecutionPolicy/topology/concurrency required external connections/accounts ``` The UI uses compact summary rows with only the active area expanded. `Use recommended setup` is the primary action in Expert review; `Review/customize` opens detail. In Simple mode the recommendation resolves visibly without unnecessary chat questions. Existing projects show current vs recommended when AWP proposes a change. Canonical: [`AWP-DELIVERY-CONNECTIONS-PLANNING-DESIGN.md`](AWP-DELIVERY-CONNECTIONS-PLANNING-DESIGN.md), [`AWP-QUALITY-CI-PLANNING-DESIGN.md`](AWP-QUALITY-CI-PLANNING-DESIGN.md). ## 20. Delivery concepts stay distinct Do not collapse all delivery concerns into one `CD method` setting. Distinct concepts include: ```text delivery strategy work-management method QualityStrategy / CIPlan release strategy continuous delivery vs continuous deployment EnvironmentStrategy PromotionPolicy DeploymentStrategy DeploymentProvider rollback/recovery ExecutionPolicy ``` Continuous delivery may retain an explicit production approval. Continuous deployment promotes qualifying changes automatically. Deployment mechanics such as rolling/canary/blue-green are chosen from real risk/operational needs, not because sophisticated automatically means better. When artifacts exist, prefer promotion of the same immutable artifact through environments rather than rebuilding different binaries for each environment. Canonical: [`AWP-DELIVERY-CONNECTIONS-PLANNING-DESIGN.md`](AWP-DELIVERY-CONNECTIONS-PLANNING-DESIGN.md). ## 21. Connection/account primitives External providers are reusable connection primitives, not hard-coded one-token settings. Core model: ```text Connection user-global reusable authenticated identity ProjectConnectionBinding project-local capability/resource authorization to use a Connection ConnectionRequirement missing/deferred provider access required by some future gate CredentialReference secret reference behind SecretStore ``` Multiple GitHub, Cloudflare or future provider accounts are normal. A Project can bind one or several user-global Connections and narrow capabilities/resources. A Plan may select/narrow among project-authorized Connections but cannot silently broaden itself to a different user-global account. Connection lifecycle includes connected, missing resource selection, missing permission, needs re-authentication, revoked and provider error. Canonical: [`AWP-INTEGRATION-CONNECTIONS-ARCHITECTURE.md`](AWP-INTEGRATION-CONNECTIONS-ARCHITECTURE.md), [`AWP-DELIVERY-CONNECTIONS-PLANNING-DESIGN.md`](AWP-DELIVERY-CONNECTIONS-PLANNING-DESIGN.md). ## 22. Connection interruption preserves Planning context When an external account is needed, Planning creates a `ConnectionRequirement`. If it is not required yet, Planning may continue and record the future lifecycle gate where it becomes blocking. If the user connects now: ```text preserve current Planning location/state -> provider authorization/account/resource selection -> return to same decision -> announce result -> automatically resume Planner agenda ``` Unsupported provider adapters are integration requirements, not mislabeled as missing credentials. Canonical: [`../specs/workflows/project-onboarding.md`](../specs/workflows/project-onboarding.md), [`../specs/ui/planning.md`](../specs/ui/planning.md), [`AWP-INTEGRATION-CONNECTIONS-ARCHITECTURE.md`](AWP-INTEGRATION-CONNECTIONS-ARCHITECTURE.md). ## 23. Every Plan ends with explicit launch disposition Every completed Plan, not only new Projects, deliberately answers: ```text Start now Schedule Park until later ``` Planning produces a Ready-to-launch brief covering scope, user decisions, technical plan, Quality/CI/CD/deployment, execution, connections, approvals, accepted risks/gaps and preflight. Planning completion never silently starts execution. Failed preflight preserves launch intent and moves to Waiting/Needs attention rather than discarding it. Canonical: [`../specs/domains/planning.md`](../specs/domains/planning.md), [`../specs/workflows/interactive-planning.md`](../specs/workflows/interactive-planning.md), [`../specs/ui/planning.md`](../specs/ui/planning.md). ## 24. Structured truth is separate from conversational presentation Conversation wording is presentation. Decisions/Risks/Assumptions/OpenQuestions/Artifacts are structured authoritative state. Changing communication style or an alias cannot silently mutate Plan truth. Instruction aliases are configurable primitives with user-global or Project scope. Project override wins over inherited user-global value. Aliases cannot bypass authorization/autonomy/approval/security/execution policy. Canonical: [`AWP-ENGINEERING-COMMUNICATION-POLICY.md`](AWP-ENGINEERING-COMMUNICATION-POLICY.md). ## 25. Human-readable specification system Specs must be readable/auditable by humans without losing agent-grade technical detail. Required model: ```text .md canonical technical source .html committed generated human presentation ``` `docs/specs/INDEX.html` is the human navigation root. HTML specs include diagrams/flowcharts, stable section anchors, clickable cross-spec references, status/authority and approved mockups where applicable. The human presentation contains the whole material contract, not an executive-summary substitute. CI will eventually detect stale HTML, broken links/index coverage and missing required mockup linkage. Canonical: [`../specs/SPEC-PRESENTATION-STANDARD.md`](../specs/SPEC-PRESENTATION-STANDARD.md), [`../specs/INDEX.md`](../specs/INDEX.md). ## 26. Product-quality UI gate AWP must not repeat Overdeck's accidental UI development. For every user-facing surface: ```text behavior sufficiently specified -> high-fidelity mockup(s) for required states -> human review of spec + mockups together -> correct either until consistent -> explicit Design Complete approval -> implementation ``` Approved high-fi mockups replace the corresponding low-fi/ASCII visual authority. Text specs remain authoritative for non-static behavior/edge cases. Canonical: [`AWP-SPECIFICATION-MOCKUP-SEQUENCE.md`](AWP-SPECIFICATION-MOCKUP-SEQUENCE.md), [`../specs/ui/planning.md`](../specs/ui/planning.md). ## 27. Incremental delivery correction AWP implementation must **not** proceed module/page by module as: ```text Planning -> Project -> Factory/Agent -> CI -> CD ``` That would delay delivery of a complete lifecycle and conflicts with the established incremental architecture plan. The implementation spine is end-to-end usable increments. The architecture review requires containment and durable observability from the first usable increment and identifies the first complete product slice as: ```text Project -> Plan -> Task -> FactoryRun -> AgentRun on K3s -> ChangeSet -> Review -> Merge ``` Later increments deepen the same product lifecycle: real Planning, autonomy, full factory observability, CI control plane, Release/CD, Cluster product surface, self-healing, then broader productization. Specs and high-fi designs are therefore produced **for the capabilities/journeys required by the next end-to-end increment**, not for an isolated module merely because it is next in a domain list. A page/spec may intentionally be minimal in an early increment and then be amended/replaced by later approved specs/high-fi designs. It may not be accidental or unreviewed. Historical evidence: [`AWP-PLANNING-ARCHITECTURE-REVIEW.md`](AWP-PLANNING-ARCHITECTURE-REVIEW.md). The current sequencing docs must be reconciled to this rule before implementation planning is treated as final. ## 28. Immediate specification work `docs/specs/domains/planning.md` remains the first deep Planning domain spec because the Planning mechanism itself is currently being specified. However, implementation planning must not interpret that as `implement Planning first as a standalone product area`. The next specification pass must: ```text 1. preserve/reconcile every decision in this register into canonical specs; 2. complete cross-cutting architecture contracts required by Increment 0/1; 3. define the complete Increment-1 end-to-end slice and acceptance boundary; 4. identify only the domain/workflow/UI specs required for that increment; 5. produce/approve the high-fi states needed by that increment before its UI implementation; 6. keep the richer Planning spec ready for Increment 2, where real Planning becomes the incremental product addition. ``` ## 29. Compaction safety rule No material Planning decision is considered safely captured merely because it exists in chat history. A decision is durable only when at least one applies: ```text it is represented in a canonical spec; it is represented in an approved binding design document; it is recorded here with a direct pointer to the canonical document that must absorb it. ``` Before this Planning design session is considered complete, every item in this register must either be absorbed into canonical specs or explicitly marked as superseded/deferred.