Imported from Bobjet61/fca-openpilot-project (AGENTS.md). Install upstream with npx skills add Bobjet61/fca-openpilot-project. Copyright stays with the author.

Codex Porting Guide

These instructions apply to the entire repository. This repository is a research reference, not an installer. Preserve that distinction in every plan, change, and final report.

Mission

Use the documented findings, source patches, tests, and negative results to help port one explicitly selected component to a named openpilot-compatible codebase. Do not treat badge-level FCA compatibility, a clean patch apply, or a successful build as evidence that a vehicle is supported.

Required inputs

Before changing vehicle-control code, identify all of the following:

• target repository, branch, and exact base commit;
• vehicle model, model year, openpilot fingerprint, powertrain, radar, EPS, and factory ACC configuration;
• comma hardware model and internal Panda target;
• harness and CAN topology: standard factory wiring or physically isolated ACC-side CAN2;
• requested component and intended actuation level;
• available validation: unit tests, Panda safety tests, replay, bench/HIL, and closed course.

If any item that changes the architecture or safety boundary is unknown, stop after inspection and ask for it. Do not infer topology from a vehicle badge, branch name, toggle, or CAN address alone.

Read order

Read these files before proposing implementation:

1. SAFETY.md
2. COMPATIBILITY.md
3. PROJECT_STATUS.md
4. docs/COMPONENT_MAP.md
5. The selected component's README, blockers, patch, and tests
6. ARCHITECTURE.md when CAN routing, radar, longitudinal control, or Panda ownership is involved
7. CONTRIBUTING.md for evidence and reporting requirements

Use source and tests as the authority for behavior. Use prose to understand intent and known limits. When they conflict, report the conflict rather than silently choosing the more convenient interpretation.

Select exactly one track

Standard harness

Factory ACC remains connected and owns ordinary acceleration and braking.

• B6 Shadow is historical A0 stop/hold/resume review material.
• Read patches/standard-harness/KNOWN_BLOCKERS.md before touching it.
• Redesign the state resets, feature/vehicle gate, pedal constraints, and bundled MADS behavior before considering actuation.
• The B6 host and Panda patches are a matched historical pair; do not use one without reviewing the other.
• The bump-transient filter is separate from B6 and does not correct a model or desired-path error.
• Steering-response changes require matching host and Panda safety changes. They change torque slew, not maximum steering torque.

Isolated CAN2

The host, internal Panda, external bridge, harness, and ownership protocol form one matched system.

• The advanced source set is not yet published. Do not reconstruct or invent missing control code from the architectural summary.
• Raw FCA radar has insufficient lateral identity for radar-only braking.
• Radar may only extend a previously strong vision/radar association through a bounded degradation; it must not cold-acquire authority.
• The camera distance-trend detector is telemetry-only.
• Do not claim OEM AEB remains available after isolation unless independently demonstrated on the exact topology.

Never mix assumptions, safety parameters, firmware, or bus mappings from these two tracks.

Porting workflow

1. Inspect the target tree, its upstream lineage, current Chrysler/FCA interfaces, safety model, tests, and dirty-worktree state.
2. Map the selected historical concept onto current APIs and message schemas. Do not blindly cherry-pick or mechanically apply an old patch.
3. Separate unrelated behavior into independent changes. Keep host, internal Panda, and external bridge work independently identifiable.
4. Scope behavior to the reviewed vehicle, hardware, topology, and explicit feature gate. Disabled and non-target configurations must remain unchanged.
5. Define every state transition and reset: activation, disengagement, pedals, cancel, gear, faults, stale input, lead/source switch, mode change, timeout, and process restart.
6. Add positive, negative, boundary, stale-input, reset, and non-target tests before increasing authority.
7. Run focused tests and the relevant upstream host and Panda safety suites.
8. Validate in order: static review, unit/safety tests, replay, disconnected bench/HIL, and controlled closed course. A road drive is not an initial test.
9. Record evidence level and limitations using docs/EVIDENCE_LEVELS.md.

Non-negotiable safety boundaries

• Never weaken checksum, counter, forwarding, TX allowlist, torque, rate, or timeout checks merely to make commands pass.
• Never hide or debounce a real EPS, ACC, ABS, AEB, or CAN fault as the fix.
• Never let stale or ambiguous state preserve experimental authority.
• Never use raw radar severity to command acceleration or braking without the documented association prerequisites.
• Never raise longitudinal torque or brake limits solely because performance feels weak; trace planner request, mapping, transport, ECU limits, and measured response first.
• Never publish or flash a firmware binary without exact source provenance, hardware target verification, reproducible build evidence, and matching host configuration.
• Never describe replay, simulation, one vehicle, or driver intervention as proof of safety.

Authorization boundaries

• For explanation, review, diagnosis, or planning, inspect and report only.
• For an explicit request to build or port, make the smallest in-scope source changes and run non-destructive validation.
• Do not flash a Panda, install on a comma, SSH to a vehicle device, modify CAN wiring, publish a release, or begin a road test unless the user separately requests that exact action after reviewing the candidate and evidence.

Privacy

Follow PRIVACY.md and docs/LOG_SHARING.md. Do not commit or quote raw routes, logs, video, GPS, VINs, dongle IDs, Panda serials, IP addresses, SSH material, local filesystem paths, or private conversations. Summarize evidence using relative timelines and anonymized aggregate measurements.

Required delivery report

For every custom candidate, report:

• target repository, branch, and base commit;
• vehicle, hardware, and CAN topology assumptions;
• selected component and files changed;
• host/Panda/bridge compatibility and matching requirements;
• tests run, exact results, and tests that could not run;
• evidence and actuation levels;
• remaining blockers, possible failure modes, and rollback point;
• one explicit status: analysis only, shadow only, bench candidate, closed-course candidate, or not ready.

Do not label a candidate road-ready or safe. If essential evidence is missing, state what is missing and stop at the lowest justified status.

Suggested user request

Use the FCA openpilot Project as a research reference to port <component> to <repository URL> at <branch/commit> for <vehicle fingerprint>, <comma hardware>, and <standard harness or isolated CAN2>. Read AGENTS.md first, preserve current non-target behavior, add the required safety tests, run all locally available validation, and report blockers. Do not install or flash anything.