Codex Evidence-Grounded Long-Horizon Feature Build Planner

Develop an evidence-grounded plan for the following long-horizon feature change.

## Change inputs
Feature goal: [Feature goal]
Repository context and architecture: [Repository context and architecture]
Current and expected behavior: [Current and expected behavior]
Scope and non-goals: [Scope and non-goals]
Relevant paths: [Relevant paths]
Technical constraints: [Technical constraints]
Data and migration requirements: [Data and migration requirements]
Interface and integration requirements: [Interface and integration requirements]
Access and security requirements: [Access and security requirements]
Operational requirements: [Operational requirements]
Verification commands and environments: [Verification commands and environments]
Release and rollback policy: [Release and rollback policy]
Definition of done: [Definition of done]
Codex authorization mode: [Codex authorization mode]

## Operating boundaries
Use the authorization mode to determine what Codex may do:
- Plan-only: analyze supplied material without changing files or running commands.
- Inspect-and-plan: inspect accessible repository files and read-only project state, then produce the plan.
- Execute approved phases: inspect first and modify or run commands only within the explicitly approved phase and accessible environment.

Do not assume repository, shell, network, database, CI, deployment, monitoring, or production access. State which capabilities are available and which are unavailable. Never invent file contents, command results, test outcomes, approvals, deployments, or production observations.

Require human authorization before destructive migrations, data mutation, credential or permission changes, external side effects, dependency upgrades with broad impact, deployment, rollback, or production operations. Do not expose secrets, tokens, personal data, or sensitive configuration. Stop and request direction if a proposed action could cause irreversible data loss, security exposure, an uncontrolled outage, or work outside the approved scope.

## Input and uncertainty rules
Treat the feature goal, observable current behavior, expected behavior, repository or source snapshot, applicable constraints, definition of done, and authorization mode as blocking inputs for an implementation-ready plan. If one is missing or materially conflicting, ask the smallest set of clarifying questions needed for safe progress. You may still provide a bounded preliminary plan, but mark affected decisions as blocked.

Treat architecture diagrams, issue history, traffic profiles, incident records, API specifications, schema documentation, deployment runbooks, and monitoring details as useful optional context. Do not infer them as facts when absent.

Classify important statements as one of:
- Supplied fact: stated in the inputs but not independently confirmed.
- Observed: confirmed from an accessible file, symbol, configuration, schema artifact, or command result; cite the path and symbol, line range, command, or artifact.
- Assumption: a bounded premise needed to continue; explain its effect and how to validate it.
- Hypothesis: a possible explanation or design implication requiring inspection or testing.
- Unknown: information not available.
- Conflict: incompatible evidence or requirements requiring reconciliation.

Prefer repository evidence over convention. If the repository differs from the supplied description, record the discrepancy rather than silently choosing one account.

## Planning workflow

### 1. Establish the evidence baseline
- Record the repository revision, branch, working-tree state, environment, accessible tools, and authorization mode when observable.
- List supplied artifacts and inspected artifacts separately.
- Identify blocking gaps, conflicting requirements, and any uncommitted changes that must not be overwritten.

### 2. Trace current behavior
Inspect relevant entry points and follow the behavior through routes or commands, middleware, validation, authorization, controllers or handlers, services, domain logic, persistence, events, queues, caches, templates or clients, integrations, and observability hooks. Cite concrete files and symbols for observed behavior.

For Laravel repositories, inspect applicable routes, middleware, Form Requests, policies and gates, controllers, service or action classes, Eloquent models and relationships, casts and scopes, migrations, jobs and listeners, scheduler entries, cache usage, Blade, Livewire or Inertia surfaces, API resources, service providers, configuration, and PHPUnit or Pest tests. Include only components that exist or are supported by evidence.

Map callers, callees, state transitions, data ownership, transaction boundaries, synchronous and asynchronous side effects, public contracts, compatibility assumptions, and existing tests. Flag dead paths, duplicated behavior, hidden coupling, and uncertain runtime behavior without presenting them as confirmed defects.

### 3. Analyze change impact and design choices
- Compare current and expected behavior using explicit scenarios, actors, permissions, inputs, state transitions, outputs, side effects, and failure responses.
- Identify affected API, event, queue, database, UI, cache, configuration, and observability contracts.
- Present viable design options where material trade-offs exist. Compare complexity, compatibility, operability, performance, security, reversibility, and testability, then recommend one with evidence and assumptions.
- Prefer localized changes. Justify every broad refactor, dependency addition, public contract change, or abstraction.

For schema or data changes, assess nullability, defaults, indexes, uniqueness, foreign keys, lock duration, table size, transaction behavior, replication effects, backfill cost, resumability, idempotency, mixed-version compatibility, and downgrade limitations. Use expand-migrate-contract or another justified compatibility strategy when zero-downtime delivery is required. Do not label a migration reversible merely because a down method exists; explain whether rollback would preserve data.

For asynchronous or integrated behavior, assess duplicate delivery, ordering, retries, timeouts, idempotency keys, poison messages, partial failure, rate limits, webhook verification, contract versioning, and reconciliation.

For access and security, assess authentication, authorization at every entry point, tenant isolation, input validation, mass assignment, injection, CSRF where applicable, sensitive logging, secret handling, file access, and abuse or privilege-escalation paths.

### 4. Build gated implementation phases
Create the smallest coherent phases that preserve deployability and existing behavior. Each phase must specify:
- Objective and user-visible effect.
- Preconditions and required approval.
- Exact files and symbols to inspect, add, or modify, with a justification.
- Schema, code, configuration, dependency, interface, and observability changes.
- Compatibility strategy for old and new application versions.
- Tests and commands to run.
- Expected observations and evidence to retain.
- Failure signals, stop conditions, and recovery action.
- Exit gate before the next phase.

Separate preparation, compatibility scaffolding, data migration or backfill, behavior activation, cleanup, and contract removal when those operations carry different risks. Use feature flags or staged rollout only when their lifecycle, default state, ownership, monitoring, and removal plan are defined.

### 5. Design verification and acceptance
Build a verification matrix covering applicable unit, feature, integration, contract, authorization, migration, regression, concurrency, queue, cache, UI, performance, and security checks. Include negative and boundary cases, not only the happy path.

For every check, provide the requirement or risk covered, setup, command or manual procedure, expected observation, actual observation if executed, evidence location, and status. Valid statuses are proposed, unavailable, blocked, failed, passed, and not applicable. Use passed only when the check actually ran successfully and supporting evidence exists. If execution did not occur, actual observation must say not observed.

Reconcile verification results against the definition of done. A failing, blocked, unavailable, or contradictory check remains unresolved and must have an owner or decision before acceptance.

### 6. Plan release, monitoring, and recovery
Define deployment order, migration timing, worker or scheduler coordination, cache and configuration handling, health checks, canary or staged rollout where justified, relevant metrics and logs, alert thresholds, observation period, and rollback decision authority.

Distinguish code rollback, feature disablement, forward fix, schema rollback, and data restoration. Document recovery point limitations, irreversible transformations, backup or restore prerequisites, backfill cancellation behavior, and how partially processed records will be reconciled.

### 7. Execute only when authorized
If execution is authorized, work one approved phase at a time. Before each phase, show its scope, commands, side effects, and stop conditions. Preserve unrelated changes. After the phase, report changed files, command results, evidence, deviations, and unresolved issues, then wait for approval when the next phase is consequential.

Do not say fixed, tested, verified, approved, deployed, rolled back, or complete unless that action occurred in the accessible environment and evidence is recorded. Keep planned work, inspected findings, executed changes, unavailable checks, and human approvals visibly separate.

## Required deliverable

### A. Capability and Evidence Ledger
Provide repository state, authorization mode, available and unavailable capabilities, supplied artifacts, inspected artifacts with citations, assumptions, unknowns, conflicts, and blocking questions.

### B. Current-to-Target Behavior Matrix
Use columns for scenario, actor or permission, current behavior and evidence, target behavior, affected contracts, side effects, edge cases, and unresolved questions.

### C. Architecture and Dependency Trace
Describe entry points, call paths, state transitions, transaction boundaries, data stores, queues, caches, integrations, user interfaces, and observability. Cite files and symbols for observations.

### D. Design Decision Record
For each material decision, provide options considered, evidence, assumptions, trade-offs, recommendation, rejected alternatives, compatibility impact, and approval required.

### E. File and Contract Change Manifest
Use columns for phase, path and symbol, change type, intended modification, justification, dependent contracts, compatibility concern, and test coverage. Do not list speculative paths as confirmed files.

### F. Phased Implementation Plan
Provide phase objectives, prerequisites, approvals, ordered implementation steps, migration or rollout strategy, verification gate, failure signals, stop conditions, recovery procedure, and handoff state.

### G. Risk and Control Register
Use columns for failure mode, trigger or cause, affected users or systems, likelihood, impact, detectability, preventive control, detection signal, mitigation or recovery, owner, phase, and residual risk. Include applicable data-loss, authorization, compatibility, race-condition, migration-lock, queue-duplication, cache-staleness, integration, performance, and deployment risks.

### H. Verification and Acceptance Matrix
Use columns for requirement or risk, test level, setup, command or procedure, expected observation, actual observation, evidence, status, and follow-up owner. Clearly separate proposed checks from executed checks.

### I. Release, Monitoring, and Rollback Runbook
Specify release sequence, approval points, feature-flag state, migration and backfill coordination, worker handling, health checks, metrics, logs, thresholds, observation window, rollback triggers, recovery path, and irreversible limitations.

### J. Definition-of-Done Reconciliation
For each supplied completion criterion, report its evidence, status, unresolved gap, and acceptance authority. End with one handoff state: ready for human review, blocked pending information, ready for an approved implementation phase, or executed with unresolved verification. Do not imply approval or completion from the handoff state alone.