@anik-2/autosar 0.0.0-stage → 0.1.0

package/python/ecuc_engine/values.py

@@ -0,0 +1,146 @@
+"""Typed value checks and ECUC-JSON value rendering, driven by the param def."""
+from __future__ import annotations
+
+import math
+import re
+from typing import Optional
+
+from .defs import DefNode
+
+C_IDENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+BOOL_TRUE = {"true", "1"}
+BOOL_FALSE = {"false", "0"}
+JS_SAFE = 2 ** 53 - 1
+
+
+def parse_int(s: str) -> Optional[int]:
+    s = s.strip()
+    try:
+        return int(s, 0)
+    except ValueError:
+        try:
+            return int(s)  # leading zeros, e.g. "007"
+        except ValueError:
+            return None
+
+
+def parse_float(s: str) -> Optional[float]:
+    t = s.strip()
+    if t.upper() in ("INF", "+INF"):
+        return math.inf
+    if t.upper() == "-INF":
+        return -math.inf
+    try:
+        return float(t)
+    except ValueError:
+        iv = parse_int(t)
+        return float(iv) if iv is not None else None
+
+
+def _bound(s: Optional[str], f):
+    if s is None or s == "":
+        return None
+    return f(s)
+
+
+def check_value(d: DefNode, raw: Optional[str]) -> list:
+    """Return [(rule, message)] problems with ``raw`` against ``d``. Empty list = OK."""
+    if raw is None or raw == "":
+        return [("ECUC-EMPTY-VALUE", f"{d.name}: empty value")]
+    k = d.kind
+    out = []
+    if k == "INTEGER":
+        v = parse_int(raw)
+        if v is None:
+            return [("ECUC-TYPE", f"{d.name}: '{raw}' is not an integer")]
+        lo, hi = _bound(d.min, parse_int), _bound(d.max, parse_int)
+        if (lo is not None and v < lo) or (hi is not None and v > hi):
+            out.append(("ECUC-RANGE", f"{d.name}={raw} outside [{d.min}..{d.max}]"))
+    elif k == "FLOAT":
+        v = parse_float(raw)
+        if v is None or math.isnan(v):
+            return [("ECUC-TYPE", f"{d.name}: '{raw}' is not a float")]
+        lo, hi = _bound(d.min, parse_float), _bound(d.max, parse_float)
+        bad = (lo is not None and (v < lo or (d.min_open and v == lo))) or \
+              (hi is not None and (v > hi or (d.max_open and v == hi)))
+        if bad:
+            out.append(("ECUC-RANGE", f"{d.name}={raw} outside {'(' if d.min_open else '['}{d.min}..{d.max}{')' if d.max_open else ']'}"))
+    elif k == "BOOLEAN":
+        if raw.strip().lower() not in BOOL_TRUE | BOOL_FALSE:
+            out.append(("ECUC-TYPE", f"{d.name}: '{raw}' is not a boolean (true/false/1/0)"))
+    elif k == "ENUMERATION":
+        if d.literals and raw.strip() not in d.literals:
+            lits = ", ".join(d.literals[:20]) + (" …" if len(d.literals) > 20 else "")
+            out.append(("ECUC-ENUM", f"{d.name}: '{raw}' is not a literal of the def ({lits})"))
+    elif k in ("STRING", "FUNCTION-NAME", "LINKER-SYMBOL", "MULTILINE-STRING"):
+        if d.min_len is not None and len(raw) < d.min_len:
+            out.append(("ECUC-STRING", f"{d.name}: length {len(raw)} < min {d.min_len}"))
+        if d.max_len is not None and len(raw) > d.max_len:
+            out.append(("ECUC-STRING", f"{d.name}: length {len(raw)} > max {d.max_len}"))
+        if k in ("FUNCTION-NAME", "LINKER-SYMBOL") and not C_IDENT.match(raw.strip()):
+            out.append(("ECUC-STRING", f"{d.name}: '{raw}' is not a valid C identifier"))
+        if d.regex:
+            try:
+                if not re.fullmatch(d.regex, raw):
+                    out.append(("ECUC-STRING", f"{d.name}: '{raw}' does not match /{d.regex}/"))
+            except re.error:
+                pass
+    return out
+
+
+def expected_value_tag(d: DefNode) -> Optional[str]:
+    k = d.kind or ""
+    if k in ("INTEGER", "FLOAT", "BOOLEAN"):
+        return "ECUC-NUMERICAL-PARAM-VALUE"
+    if k in ("ENUMERATION", "STRING", "FUNCTION-NAME", "LINKER-SYMBOL", "MULTILINE-STRING"):
+        return "ECUC-TEXTUAL-PARAM-VALUE"
+    if k == "ADD-INFO":
+        return "ECUC-ADD-INFO-PARAM-VALUE"
+    if k == "INSTANCE-REFERENCE":
+        return "ECUC-INSTANCE-REFERENCE-VALUE"
+    if k.endswith("REFERENCE"):
+        return "ECUC-REFERENCE-VALUE"
+    return None
+
+
+def to_json(d: Optional[DefNode], raw: Optional[str], is_ref: bool, numerical: bool):
+    """Raw ARXML text -> compact JSON value (int/float/bool/str, refs as '->/path')."""
+    if raw is None:
+        return None
+    if is_ref:
+        return "->" + raw if raw.startswith("/") else raw
+    k = d.kind if d is not None else ("NUMBER" if numerical else None)
+    t = raw.strip()
+    if k == "BOOLEAN" or (k == "NUMBER" and t.lower() in ("true", "false")):
+        lo = t.lower()
+        return True if lo in BOOL_TRUE else False if lo in BOOL_FALSE else raw
+    if k in ("INTEGER", "NUMBER"):
+        v = parse_int(t)
+        if v is not None:
+            return v if abs(v) <= JS_SAFE and t == str(v) else t  # keep hex / huge as text
+        if k == "INTEGER":
+            return raw
+    if k in ("FLOAT", "NUMBER"):
+        v = parse_float(t)
+        if v is not None and math.isfinite(v):
+            return v
+        return raw
+    return raw
+
+
+def from_json(d: Optional[DefNode], v) -> str:
+    """JSON value from an edit op -> ARXML text."""
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, (int, float)):
+        if isinstance(v, float) and v.is_integer() and d is not None and d.kind == "FLOAT":
+            return repr(v)
+        return str(v)
+    if v is None:
+        raise ValueError("null is not a value; use op 'remove' to delete a parameter")
+    s = str(v)
+    if s.startswith("->"):
+        s = s[2:]
+    if d is not None and d.kind == "BOOLEAN" and s.lower() in ("true", "false"):
+        s = s.lower()
+    return s

package/python/ecuc_engine/xmltree.py

@@ -0,0 +1,141 @@
+"""Byte-offset-preserving XML tree for ARXML.
+
+The engine never re-serialises a whole file. It parses with expat, records the byte span of every
+element (start tag, content, end tag) and the line it starts on, and later patches only the spans
+an edit touches. Comments, whitespace, attribute order, UUIDs and everything else outside the
+patched spans stay byte-identical.
+
+Namespace-agnostic: a prefixed tag (``ar:ECUC-CONTAINER-VALUE``) is stored without its prefix, so
+any AUTOSAR schema namespace (r4.0 or a later one) parses the same way.
+"""
+from __future__ import annotations
+
+import xml.parsers.expat as expat
+from typing import Iterator, Optional
+
+
+class Node:
+    __slots__ = ("tag", "attrs", "start", "stag_end", "end", "cstart", "cend", "line", "children", "parent", "_text")
+
+    def __init__(self, tag: str, attrs: dict, start: int, stag_end: int, line: int, parent: "Optional[Node]"):
+        self.tag = tag
+        self.attrs = attrs
+        self.start = start  # byte offset of '<'
+        self.stag_end = stag_end  # byte offset just after the start tag's '>'
+        self.end = stag_end  # byte offset just after the element (set on close)
+        self.cstart: Optional[int] = None  # content span (None for <X/>)
+        self.cend: Optional[int] = None
+        self.line = line
+        self.children: list[Node] = []
+        self.parent = parent
+        self._text: list[str] = []
+
+    @property
+    def text(self) -> str:
+        return "".join(self._text)
+
+    def child(self, tag: str) -> "Optional[Node]":
+        for c in self.children:
+            if c.tag == tag:
+                return c
+        return None
+
+    def child_text(self, tag: str) -> Optional[str]:
+        c = self.child(tag)
+        return c.text.strip() if c is not None else None
+
+    def iter(self) -> Iterator["Node"]:
+        stack = [self]
+        while stack:
+            n = stack.pop()
+            yield n
+            stack.extend(reversed(n.children))
+
+    @property
+    def short_name(self) -> Optional[str]:
+        return self.child_text("SHORT-NAME")
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<Node {self.tag} {self.short_name or ''} @{self.line}>"
+
+
+def _local(name: str) -> str:
+    return name.rsplit(":", 1)[-1]
+
+
+def _stag_end(data: bytes, start: int) -> int:
+    """Index just past the '>' closing the start tag at ``start`` (quote-aware)."""
+    i = start + 1
+    n = len(data)
+    quote = 0
+    while i < n:
+        b = data[i]
+        if quote:
+            if b == quote:
+                quote = 0
+        elif b in (0x22, 0x27):  # " '
+            quote = b
+        elif b == 0x3E:  # >
+            return i + 1
+        i += 1
+    raise ValueError(f"unterminated start tag at byte {start}")
+
+
+def parse(data: bytes) -> Node:
+    """Parse ``data`` and return the document element with byte spans filled in."""
+    p = expat.ParserCreate()
+    p.buffer_text = True
+    stack: list[Node] = []
+    root: list[Node] = []
+
+    def start(name, attrs):
+        s = p.CurrentByteIndex
+        se = _stag_end(data, s)
+        node = Node(_local(name), {_local(k): v for k, v in attrs.items()}, s, se, p.CurrentLineNumber,
+                    stack[-1] if stack else None)
+        if stack:
+            stack[-1].children.append(node)
+        else:
+            root.append(node)
+        stack.append(node)
+
+    def end(name):
+        node = stack.pop()
+        if data[node.stag_end - 2] == 0x2F:  # '/' of '/>'
+            node.end = node.stag_end
+        else:
+            idx = p.CurrentByteIndex
+            node.cstart = node.stag_end
+            node.cend = idx
+            node.end = data.index(b">", idx) + 1
+
+    def chars(t):
+        if stack:
+            stack[-1]._text.append(t)
+
+    p.StartElementHandler = start
+    p.EndElementHandler = end
+    p.CharacterDataHandler = chars
+    p.Parse(data, True)
+    if not root:
+        raise ValueError("no root element")
+    return root[0]
+
+
+def escape(s: str) -> str:
+    return s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+
+
+def escape_attr(s: str) -> str:
+    return escape(s).replace('"', "&quot;")
+
+
+def line_indent(data: bytes, pos: int) -> Optional[bytes]:
+    """Whitespace between the previous newline and ``pos`` if it is all whitespace, else None."""
+    nl = data.rfind(b"\n", 0, pos)
+    seg = data[nl + 1:pos]
+    return seg if seg.strip() == b"" else None
+
+
+def line_of(data: bytes, pos: int) -> int:
+    return data.count(b"\n", 0, pos) + 1

package/python/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "ecuc-engine"
+version = "0.1.0"
+description = "Load, read, edit in place, validate and diff AUTOSAR ECUC ARXML (Hydron AUTOSAR pack)"
+requires-python = ">=3.10"
+# The core is stdlib-only; autosar-data adds a strict schema check of every edited file.
+dependencies = ["autosar-data==0.17.0"]
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

package/skills/autosar/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: autosar
+description: >-
+  AUTOSAR Classic integration expertise — ECUC configuration (ARXML), param defs, BSW module
+  config, code generation and build, and config-to-code tracing. Load it at the START of any task
+  that touches .arxml files, ECUC values/param defs, DEFINITION-REFs, a BSW module's configuration
+  (Com, PduR, CanIf, EcuC, Os, Rte, NvM, Dem, Dcm, …), generated Output/ code, or the vendor
+  configurator / SIP. It carries the tool map (ecuc_read/ecuc_edit/ecuc_validate/arxml_diff,
+  autosar_trace/autosar_config_lookup, autosar_generate/autosar_build), the edit → validate →
+  generate → build → trace loop, and the ECUC model rules needed to edit correctly.
+---
+# AUTOSAR skill — Classic Platform integration layer
+
+You are working on an AUTOSAR Classic ECU project. The configuration is ECUC ARXML; generated C
+in `Output/` is derived from it; in-house code in `Source/` calls the generated symbols.
+
+## Hard rules
+1. **Never hand-write or hand-edit ARXML** (no `write`/`edit`/`sed` on `.arxml`). Every change goes
+   through `ecuc_edit`, which picks the value element, DEFINITION-REF/DEST and VALUE-REF DEST from
+   the param defs and patches only the changed bytes. Reading raw ARXML for context is fine; prefer `ecuc_read`.
+2. **Validate after every edit**: `ecuc_validate` (scoped with `files`/`module` if large). Fix
+   every error you introduced before moving on; report pre-existing ones separately.
+3. **Cite** the AUTOSAR path, the DEFINITION-REF and file:line for every element you discuss or change.
+4. **Generated code is an output.** Never edit `Output/` (or other generated files) to fix a
+   problem — change the configuration and regenerate.
+5. Values come from the param defs (ranges, literals, multiplicity) and the SWS; when the defs do
+   not settle a question (cross-module consistency, handle IDs, timing), say so and cite the SWS
+   requirement rather than guessing.
+
+## Tool map
+| Need | Tool |
+|---|---|
+| What modules/files/defs exist | `ecuc_read` (no path) |
+| Values of a module/container | `ecuc_read path=… depth=…` |
+| What may be set/added here (types, ranges, literals, multiplicity) | `ecuc_read path=… schema=true`, or a def path `/AUTOSAR/EcucDefs/<Mod>/…` |
+| Change config | `ecuc_edit ops=[…]` (`dry_run` first for large edits) |
+| Check config | `ecuc_validate` |
+| Review a change / PR / two versions | `arxml_diff a b` |
+| Which C symbols does this config produce, who calls them / where does this symbol come from | `autosar_trace query=…` |
+| Refs in/out, children of an element in the ingested repo | `autosar_config_lookup path=…` |
+| Regenerate code | `autosar_generate` (configured command, asks permission) |
+| Compile/link | `autosar_build` |
+| Spec questions (SWS/TPS requirement text) | the project's ingested docs search tools |
+
+## The loop
+`ecuc_read (schema) → ecuc_edit → ecuc_validate → autosar_generate → arxml_diff / inspect Output → autosar_build → autosar_trace (impact on Source/)`.
+Details and failure handling: `references/workflow.md`.
+
+## References (load when relevant)
+- `references/ecuc-model.md` — module/container/param/ref values vs defs, DEFINITION-REF, ECUC JSON, multiplicity, choice containers, refs vs foreign refs.
+- `references/symbolic-names.md` — the symbolic-name rule (TPS_ECUC_02108) that links config to generated `#define`s, handle IDs.
+- `references/config-classes.md` — pre-compile / link-time / post-build config classes, variants, post-build loadable/selectable.
+- `references/project-layout.md` — Config / Input / Output / Source / Build / SIP and `.hydron/autosar.json`.
+- `references/workflow.md` — the edit → validate → generate → build → trace loop, diagnostics rules, and what to do when a step fails.
+
+## Reading diagnostics
+`file:line SEVERITY RULE path — message [def DEFINITION-REF]`. Rules: ECUC-MISSING-PARAM,
+ECUC-MULT-CONTAINER/-PARAM, ECUC-CHOICE, ECUC-RANGE, ECUC-ENUM, ECUC-TYPE, ECUC-STRING,
+ECUC-REF-DANGLING, ECUC-REF-DEST, ECUC-REF-UNRESOLVED (foreign target not loaded: add System/SWC
+ARXML to `input`), ECUC-UNKNOWN-DEF (often a release mismatch between config and param defs),
+ECUC-DUP-NAME, ECUC-NO-DEF (module defs not loaded → module not validated), ECUC-VALUE-TYPE,
+ECUC-DEST-MISMATCH, ECUC-OBSOLETE. These are mechanical checks from the defs; they do not cover
+SWS cross-module rules — reason about those explicitly.

package/skills/autosar/references/config-classes.md

@@ -0,0 +1,23 @@
+# Configuration classes and post-build
+
+Every param/ref def lists, per implementation variant, when its value is fixed
+(`VALUE-CONFIG-CLASSES` in recent releases):
+
+| Class | Fixed at | Generated as | Changing it needs |
+|---|---|---|---|
+| PRE-COMPILE | compile time | `#define`s in `<Mod>_Cfg.h` | regenerate + full rebuild |
+| LINK | link time | `const` data in `<Mod>_Lcfg.c` | regenerate + relink of that object |
+| POST-BUILD | after build (flash/load) | `const` tables in `<Mod>_PBcfg.c`, passed to `<Mod>_Init(ConfigPtr)` | regenerate post-build data only (if the project uses post-build loadable) |
+
+The module's `IMPLEMENTATION-CONFIG-VARIANT` (VARIANT-PRE-COMPILE / VARIANT-LINK-TIME /
+VARIANT-POST-BUILD) selects which class applies; it must be one of the module def's
+`SUPPORTED-CONFIG-VARIANTS`.
+
+**Post-build selectable** (several configuration sets in one image, chosen at init via
+`EcuM`/`<Mod>_Init` config pointer) and **post-build loadable** (configuration flashed separately)
+only allow changing values whose class is POST-BUILD for the selected variant, and multiplicity
+only where `MULTIPLICITY-CONFIG-CLASSES` allows it. `POST-BUILD-VARIANT-VALUE=true` means the value
+may differ between post-build variants (predefined variants / variation points).
+
+When proposing a change, state its class: a pre-compile change forces a full rebuild and a new
+software version; a post-build change may ship as a data update.

package/skills/autosar/references/ecuc-model.md

@@ -0,0 +1,42 @@
+# ECUC model basics
+
+**Definitions vs values.** Param defs (`ECUC-MODULE-DEF` trees: the AUTOSAR StMD
+`/AUTOSAR/EcucDefs/<Mod>` and vendor VSMD/BSWMD refinements) describe what may be configured.
+Values (`ECUC-MODULE-CONFIGURATION-VALUES`) are the configuration. Every value element points to
+its def through `DEFINITION-REF` (an AUTOSAR path); the `DEST` attribute names the def's metaclass.
+
+**Hierarchy.**
+- Module configuration → `CONTAINERS` → `ECUC-CONTAINER-VALUE` → `SUB-CONTAINERS` …
+- A container holds `PARAMETER-VALUES` (`ECUC-NUMERICAL-PARAM-VALUE` for integer/float/boolean,
+  `ECUC-TEXTUAL-PARAM-VALUE` for enum/string/function-name/linker-symbol) and `REFERENCE-VALUES`
+  (`ECUC-REFERENCE-VALUE` with `VALUE-REF DEST=…`, `ECUC-INSTANCE-REFERENCE-VALUE`).
+- A value's AUTOSAR path is the chain of SHORT-NAMEs: `/<Pkg>/<Module>/<Container>/…`. The def
+  path follows the *def* names: `/AUTOSAR/EcucDefs/Com/ComConfig/ComSignal`.
+
+**ECUC JSON** (what `ecuc_read` returns and `ecuc_edit add` accepts): containers keyed
+`"<DefName>:<ShortName>"` (just `"<Name>"` when equal), params by def short-name, multi-valued
+params as arrays, refs as `"->/path"`, `@path`/`@def`/`@at` metadata.
+
+**Multiplicity.** `LOWER/UPPER-MULTIPLICITY` (or `UPPER-MULTIPLICITY-INFINITE`) on every container,
+param and ref def. Lower ≥ 1 = mandatory. A **choice container** (`ECUC-CHOICE-CONTAINER-DEF`)
+must hold exactly one of its `CHOICES`.
+
+**Parameter kinds.** INTEGER (uint64-safe, MIN/MAX), FLOAT (MIN/MAX with OPEN/CLOSED interval,
+INF), BOOLEAN (`true`/`false`/`1`/`0`), ENUMERATION (literals), STRING / FUNCTION-NAME /
+LINKER-SYMBOL (length, regex, C identifiers), ADD-INFO, MULTILINE-STRING.
+
+**References.**
+- ECUC reference (`ECUC-REFERENCE-DEF`, choice/symbolic-name refs): target is another container
+  value whose DEFINITION-REF matches a `DESTINATION-REF` (e.g. `ComPduIdRef → EcuC/…/Pdu`).
+- Foreign reference (`ECUC-FOREIGN-REFERENCE-DEF`): target is a System/SWC element of the metaclass
+  in `DESTINATION-TYPE` (e.g. `I-SIGNAL-TO-I-PDU-MAPPING`); `VALUE-REF DEST` names the target's
+  concrete metaclass. Resolving it needs the System extract in `input`.
+- Instance references point into a component instance context; the engine reads but does not edit them.
+
+**Split files.** One module's configuration may be split across several files with the same
+module path; tools merge them for reading and edit each element in the file it lives in.
+
+**Releases.** The def metamodel drifts across releases (e.g. `VALUE-CONFIG-CLASSES` vs older
+`ECUC-IMPLEMENTATION-CONFIGURATION-CLASS`; params added/removed). Always validate against the
+param defs of the release the project's SIP targets; an ECUC-UNKNOWN-DEF burst usually means
+mismatched defs, not broken config.

package/skills/autosar/references/project-layout.md

@@ -0,0 +1,29 @@
+# Project layout (typical OEM / Tier-1 integration repo)
+
+| Folder | Holds | Who edits |
+|---|---|---|
+| `Config/` | ECUC values ARXML (one or more files per module), configurator project file | integrator, via the configurator or `ecuc_edit` |
+| `Input/` | System description / ECU extract, DBC/LDF/FIBEX, SWC descriptions, diagnostic data | comes from the OEM network/system team |
+| `Output/` | generated BSW/RTE/OS/MCAL configuration code and reports | generator only — never by hand |
+| `Source/` | in-house application and integration code (callouts, CDDs, SWC runnables) | developers |
+| `Build/` | makefiles/CMake, linker scripts, compiler options | build owner |
+| `SIP/` (or `BSW/`, `ThirdParty/`) | the vendor's Software Integration Package: static BSW code, BSWMD with vendor param defs (VSMD), generators | vendor; read-only |
+
+Names vary; the tools classify `.arxml` files by content, not by folder.
+
+## `.hydron/autosar.json`
+Optional; pins what the tools load and how to generate/build:
+
+```json
+{
+  "paramDefs": ["SIP/**/bswmd/*.arxml", "~/autosar/R22-11/AUTOSAR_MOD_ECUConfigurationParameters.arxml"],
+  "config":    ["Config/**/*.arxml"],
+  "input":     ["Input/**/*.arxml"],
+  "generate":  {"command": "<vendor-cli> -p Config/Ecu.dpa --generate {module}", "cwd": ".", "timeoutSec": 3600},
+  "build":     {"command": "make -C Build -j8 all", "timeoutSec": 3600}
+}
+```
+Without it: param defs = every `.arxml` holding `ECUC-MODULE-DEF` (else `$AUTOSAR_PARAMDEFS`, a
+path list), config = every file holding `ECUC-MODULE-CONFIGURATION-VALUES`, input = all other
+`.arxml`. Use the param defs of the release and vendor the project actually targets; the vendor
+BSWMD defs take precedence for vendor-specific parameters.

package/skills/autosar/references/symbolic-names.md

@@ -0,0 +1,25 @@
+# Symbolic names: how config becomes C symbols
+
+**TPS_ECUC_02108 (symbolic name rule).** For a container whose def has a parameter with
+`SYMBOLIC-NAME-VALUE=true` (typically the handle ID, e.g. `ComHandleId`, `PduRDestPduHandleId`,
+`CanIfTxPduId`), the generator emits a `#define` named
+
+    <Module>Conf_<ContainerDefName>_<ContainerShortName>   value = that parameter
+
+e.g. `ComConf_ComSignal_DoorLatch`, `PduRConf_PduRDestPdu_Tx_Msg1`. In-house code and other BSW
+modules must use these symbols, never literal IDs. A `*-REF` with `SYMBOLIC-NAME-REFERENCE` uses
+the target's symbolic name.
+
+**Consequences for edits.**
+- Renaming a container (SHORT-NAME) renames its symbol: every caller in `Source/` breaks. Run
+  `autosar_trace` on the element first to list callers.
+- Handle IDs: often zero-based and dense per module; shared IDs must agree across modules
+  (TPS_ECUC_02106). When adding a container with a handle ID, read the siblings and pick the next
+  free value per the module's convention; say which convention you assumed.
+- Vendor generators may add prefixes or use different names for vendor-specific containers;
+  `autosar_trace` reports links by `method` (`symbolic_name` = rule match, score 1.0;
+  `token_match`/`value_match` = heuristic, check the score).
+
+**Other generated artefacts.** Const configuration tables (`<Mod>_PBcfg.c`, `<Mod>_Lcfg.c`),
+`<Mod>_Cfg.h` macros (feature switches from booleans such as `…DevErrorDetect`), and callout
+prototypes from FUNCTION-NAME params (the in-house code must define those functions).

package/skills/autosar/references/workflow.md

@@ -0,0 +1,29 @@
+# The integration loop
+
+1. **Orient.** `ecuc_read` (no path) → modules, files, whether param defs loaded. If it warns that
+   no defs were found, stop and ask for the param-def location (or set `paramDefs`); without defs
+   nothing is validated and new elements cannot be added.
+2. **Understand the target.** `ecuc_read path=<container> schema=true` for the allowed params,
+   ranges, literals, multiplicity. For cross-module work also read the referenced containers
+   (e.g. ComIPdu → EcuC Pdu → PduR routing path → CanIf Tx PDU). `autosar_trace` shows which C
+   symbols and callers depend on the element.
+3. **Edit.** One `ecuc_edit` call with all related ops (it is all-or-nothing). Use `dry_run` to
+   show a non-trivial change first. Never write ARXML yourself.
+4. **Validate.** `ecuc_validate` (scope with `module`/`files` on big projects). Separate findings you
+   introduced from pre-existing ones (`arxml_diff` against the committed version helps). Fix yours.
+5. **Generate.** `autosar_generate` (only with no new errors). If it fails, read its error output,
+   map each message to the AUTOSAR path / parameter, fix via `ecuc_edit`, re-validate.
+6. **Review output.** `arxml_diff` for ARXML outputs; for C, check the expected symbols changed
+   (e.g. a new `ComConf_ComSignal_<Name>`).
+7. **Build.** `autosar_build`; compile/link errors usually mean a renamed/removed symbolic name or a
+   callout (FUNCTION-NAME) not implemented in `Source/`. `autosar_trace` the symbol to its config.
+8. **Report.** List each change as `path` (DEFINITION-REF) old → new, its config class, the
+   validation result, generator/build status, and impacted callers.
+
+## Failure handling
+- ECUC-UNKNOWN-DEF everywhere → wrong release/vendor defs loaded; check `paramDefs`.
+- ECUC-REF-UNRESOLVED → the System/SWC ARXML is not in `input`; add it rather than ignoring.
+- `ecuc_edit` rejected a value → it violates the def; do not `force` unless the user confirms the
+  def is wrong for their vendor release, and say so.
+- Backend tools (`autosar_trace`, `autosar_config_lookup`) report NOTES such as "data source
+  predates the feature, re-ingest it": relay them; the graph needs a re-ingest of the code data source.