Sync Implementation Project

Syncing an installation project to the reference

This repository is the reference project. Real buildings run installation projects — separate .project files, in other repositories, each wired to its own I/O, its own rooms, its own equipment. They share the function blocks and data types; they do not share logic.

A sync moves the shared half and leaves the other half exactly as it was:

The two qualified rows are where the real work is. Both are append-or-migrate only, both are checked afterwards, and neither ever changes what the building does.

The dividing line is structural, not a naming convention: anything filed under a device node belongs to the installation; anything at project level is shared library code. The planner applies that rule plus the declared kind, so a site's own FB_VIRTUAL_BOOL_MQTT under VIRTUAL/ is left alone and a site's PLC_PRG_MAIN is never touched.

The names on this page are the installation's, not the reference's

The reference project renamed its objects to the convention in docs/CodingStyle.md: MqttVariables is GVL_MQTT there, PersistentVars is GVL_PERSISTENT, PLC_PRG_MAIN is PRG_MAIN. An installation keeps its own spelling until it is migrated, which is exactly why the names above are still the old ones — they name objects this skill promises never to rewrite.

Consequence for a sync across that boundary: a synced block now refers to GVL_MQTT, so the installation's GVL has to be renamed in the same window or every synced block fails with Identifier 'GVL_MQTT' not defined. Use the rename task for it (see the codesys-loop skill), against the installation project, before syncing the blocks. That is a breaking, one-off migration and it belongs to the major release, not to a routine sync.

Before anything else

An installation project is a building's running control program. Two rules, and neither is negotiable:

• Never download. codesys.ps1 download refuses a -Project override outright. Do not work around it. This skill changes files on disk and nothing else.
• Never sync in place. The installation project may not be under source control. Work on a copy in .ai/sync/, and only replace the original once the copy has built cleanly, passed the logic-unchanged check, and the user has said in so many words to replace it.

Read codesys-loop first if you have not — the tasks below are its tasks, with -Project pointed elsewhere. Its warnings apply here too, especially: a clean build does not mean checked, and an edit can report success without taking effect.

A sync is two passes, not one. Pass one brings the blocks across (§1–§7). Pass two brings the installation onto the way the reference now configures those blocks (§6c) — a refactor the compiler cannot ask for, because the old style still works. Skipping pass two produces a project that builds clean, passes every check, and has not caught up. Plan for both from the start.

The loop

Each CODESYS task boots the IDE, so budget 60–120 seconds per step. Everything lands in .ai/, which is gitignored.

1. Toolchain and working copy

./tools/ai/codesys.ps1 doctor
$impl = 'C:\path\to\SiteA.project'
./.claude/skills/sync-implementation-project/scripts/Working-Copy.ps1 new -Target $impl

The copy lands at .ai/sync/<stem>/<stem>.project. Everything from here on targets the copy, except the info in step 2, which reads the original read-only to describe what is actually deployed.

2. Describe both projects

$copy = '.ai\sync\SiteA\SiteA.project'
./tools/ai/codesys.ps1 info -Full -Output .ai\sync\reference.json
./tools/ai/codesys.ps1 info -Full -Project $copy -Output .ai\sync\before.json

info opens a project read-only with VersionUpdateFlags.NoUpdates, so looking at an older installation project never converts it as a side effect. -Full includes source text, which the planner needs to work out dependencies.

The report carries: the IDE version that read it, every library reference, every device with its id and version, and every code-bearing object with a hash of its declaration, implementation and members. That hash is what "this block differs from the reference" means here — not a text diff, not the XML.

3. Does the installation project still build as it is?

./tools/ai/codesys.ps1 verify -Baseline -Project $copy

This is the version-compatibility gate, and it is the one that matters. The compiler version a project stores is not reachable from the scripting API — a reflection sweep over the application object finds nothing, so do not go looking again. Building it with the installed IDE answers the question directly: if the project needs a compiler version, device description or library this install does not have, the build says so by name.

It also records the baseline, so the post-sync build reports only what the sync caused. Reports for a foreign project are stem-qualified (baseline.SiteA.json), so this cannot overwrite the reference project's own baseline.

If this build is not clean, stop. A sync onto a project that was already broken cannot be assessed, because every later message is ambiguous.

4. Plan

py .claude/skills/sync-implementation-project/scripts/plan_sync.py `
   --reference .ai/sync/reference.json `
   --implementation .ai/sync/before.json `
   --out .ai/sync/plan.json --emit-edits .ai/sync/edits

The plan prints a compatibility verdict and five lists: what to update, what was pulled in as a dependency, what is already identical, what belongs to the installation, and what needs a human. Exit codes: 0 clean, 2 incompatible, 3 something needs a decision.

Read it before running anything else, and show the user the update list and the left-alone list. This is the point where a misclassification is cheap to catch and expensive to miss.

Two behaviours worth knowing:

• Dependencies are pulled in automatically. If an updated block references a type the installation has never had — E_MQTT_ENTITY is the real example — the type is added too, transitively. Without that the sync produces Identifier 'E_MQTT_ENTITY' not defined and nothing in the plan explains why.
• Unreferenced new blocks are not. A block the installation never used is dead code there; adding it is a scope decision. --add-missing includes them if the user asks for that.

--emit-edits additionally writes .ai/sync/edits/ with the global-variable members the synced blocks need and the installation lacks. The shared/logic split is not clean at the GVL boundary: MqttVariables holds a building's instance declarations and shared infrastructure the blocks read, such as the MQTT_TOPIC_LEN / MQTT_SUFFIX_LEN string-length constants. Without them every synced block fails with Identifier 'MqttVariables.MQTT_TOPIC_LEN' not defined and the GVL is the last place anyone looks, because the GVL is on the do-not-touch list.

The generated edit is an append with an idempotence sentinel — nothing existing is rewritten, so no instance declaration can be lost, and re-running does not declare anything twice. check_logic_unchanged.py re-verifies that append-only property line by line afterwards. Anything beyond an append is a human's call.

5. Lift the blocks out of the reference

$plan = Get-Content .ai/sync/plan.json -Raw | ConvertFrom-Json
Remove-Item .ai\sync\candidates -Recurse -Force -ErrorAction SilentlyContinue
./tools/ai/codesys.ps1 export -Only $plan.export -Output .ai\sync\candidates\shared.xml

-Only exports exactly those objects and errors out by name if one is not found, rather than quietly exporting less than asked. The export carries folder structure, which the import needs.

6. Verify the sync on a sandbox

./tools/ai/codesys.ps1 verify -Project $copy -Candidates .ai\sync\candidates `
    -ImportFolders -ImportConflict replace -Edits none

All four flags are load-bearing:

• -ImportConflict replace — without a conflict policy the importer has no say in what happens when the object already exists, and what it does is add a second one. The installation keeps compiling its old block and the sync achieves nothing.
• -ImportFolders — a candidate exported from another project carries folders; without the flag the block lands at the project root beside the real one, is never compiled, and the build stays green while the sync has done nothing. The two flags fail the same way and are needed together.
• -Candidates keeps the sync's set separate from .ai/candidates, so a half-finished block edit cannot ride along into a building's project.
• -Edits none because this repo's edit spec targets the reference project.

verify sandboxes into .ai/work — the working copy is not written yet.

Read NEW vs baseline, not just the result line. Expect breakage here — see the next section, which is where most of the work in a real sync actually is.

6b. Call-site migrations

A block whose interface changed leaves the installation's programs calling something that no longer exists. On the first real sync of SiteA that was four errors in two programs: FB_OUTPUT_COVER_MQTT had replaced ConfigureFunctionBlock with FB_init parameters, and FB_MqttPublishQueue had replaced an EMPTY flag with HasMessage().

These have to be fixed for "all blocks updated" to mean anything — an un-buildable project is not a delivered sync. But they edit the installation's own code, so:

• Behaviour-preserving only. Same values, same conditions, different spelling. EMPTY becomes NOT HasMessage(), not "roughly equivalent". A timing moves from a runtime call to an FB_init argument at the same value.
• Never invent behaviour to satisfy a new parameter. If the new interface needs a value the installation never had, that is a question for the user.
• Every migration is reported by name and is listed in the check output.

Author them in .ai/sync/edits/migrations.json, which plan_sync.py folds into the generated edits.json — its own file, so re-running the planner cannot wipe it:

{ "edits": [
  { "pou": "PLC_PRG_MAIN",
    "replace_in_decl": [
      { "find": "FB_DO_COVER_001\t\t\t\t:FB_OUTPUT_COVER_MQTT;",
        "with": "FB_DO_COVER_001\t\t\t\t:FB_OUTPUT_COVER_MQTT(T#1S, T#20S);",
        "count": 1 } ] },
  { "pou": "PLC_PRG_MQTT", "member": "MQTT_PUBLISH",
    "replace_in_body": [
      { "find": "NOT(MqttVariables.fbMqttPublishQueue.EMPTY)",
        "with": "MqttVariables.fbMqttPublishQueue.HasMessage()", "count": 1 } ] }
] }

count is worth setting every time: it turns "I expected one call site and there were three" from a silent over-edit into a failure.

Never hand-type a find string. ST here is tab-aligned, and the tabs do not survive being read off a screen — the first attempt at the cover migration used seven tabs where the source had eleven, and replace_in_body refused it. Extract the exact substring from the -Full info report instead:

impl = <the member's "impl" text from before.json>
i = impl.find("FB_DO_COVER_001.ConfigureFunctionBlock")
find = impl[i:impl.find(");", i) + len(");\n\n")]
assert impl.count(find) == 1

A miss is an error, not a no-op, which is the one thing that makes this safe: a half-applied migration cannot pass as a success.

FB_init arguments: adding is safe, changing is not. Giving an instance that had no arguments a FB_init list works — CODESYS parses it from the declaration text, and the cover migration above is verified to land. Changing an argument an instance already has does not reach the compiler at all; the value lives in InputAssignments metadata that no script can touch. apply and verify print an ADVISORY when an edit changes an existing argument list. If you see one, that edit did nothing — do it in the IDE. CLAUDE.md has the full account.

6c. Configuration-style migrations — a green build is not "done"

This is the step most likely to be skipped, and skipping it is invisible.

The reference does not only change what is inside a block. It changes how a block is configured, and those refactors are deliberately backwards compatible — the old way keeps working. So the project compiles, NEW vs baseline reads 0, every check passes, and the installation is still written in the previous generation's style. Nothing fails. It just never catches up.

The case in this project is self-wiring. A block that carries the self-wiring prologue in its body and inherits FriendlyName from FB_MQTT_BASE configures itself from its declaration:

FB_DO_LIGHT_001  :FB_OUTPUT_BINARY_MQTT := (FriendlyName := 'Landing spots',
                                            EntityType := E_MQTT_ENTITY.Light);

…which replaces roughly thirty lines of InitMqtt / InitMqttDiscoveryAsLight in MAIN_INIT per instance. Detect and generate it:

py .claude/skills/sync-implementation-project/scripts/plan_declaration_migration.py `
   --implementation .ai/sync/after.json --out .ai/sync/decl/migrations.json

Run it after the block sync, against the post-sync inventory — the self-wiring prologue only exists in the project once the blocks have landed. Then verify and apply it as a second pass, exactly like §6b but with no candidates.

Three things it gets right that a careless hand edit does not:

• The friendly name comes from the Name := argument, never from the trailing comment. In SiteA, FB_DO_LIGHT_005 is commented // Hall and announces to Home Assistant as 'Landing'. Believe the code. Copy the name verbatim, including what looks like a typo — that site's pushbutton 002 announces as 'Kithcen' where the comment says Kitchen, and "fixing" it renames a live Home Assistant entity. Mention it; do not correct it.
• InitMqttDiscoveryAsLight becomes EntityType := E_MQTT_ENTITY.Light. A binary output's default platform is Switch. Drop the EntityType on a block that was announcing as a Light and you orphan its retained light/.../config topic and create a second, switch entity in Home Assistant. No compiler and no build catches that; only an MQTT snapshot diff does.
• An instance that is never called cyclically is refused. Self-wiring happens on the block's first cyclic call, so moving a never-called instance onto its declaration would silently remove it from Home Assistant, where the init action used to wire it regardless. It is left as an explicit call and reported.

The generated edits are ordinary replace_in_decl / replace_in_body rules — read them before applying, and note that the script appends to an existing migrations.json rather than overwriting your hand-written ones.

Then tidy the init action by hand. Deleting thirty statements leaves the section comments that headed them ((* Light 001 *), (* INIT COVERS STUFF *)) pointing at nothing. The script collapses the blank runs, because that is mechanical; it cannot tell which comments are now lies. Replace what is left with a short header saying where the wiring went, modelled on the reference's own MAIN_INIT — otherwise the next person reads an action full of headings for code that is not there and goes looking for it. A comments-only body_replace carrying the remaining executable statements across verbatim cannot change behaviour, and the before/after check still proves only that program moved.

Check the result over MQTT. This is the one migration where a clean build proves the least: it changes which discovery topics get published and under which platform. Snapshot the broker before and after with tools/ai/Mqtt-Snapshot.ps1 and read the GONE section — a discovery config that was retained before and is absent after is an entity Home Assistant still shows and nothing publishes to any more. See codesys-loop.

Generalising. The detector encodes one specific pattern because that is the one this reference uses. When the reference introduces the next configuration refactor, the sync will again compile clean and again be incomplete. The question to ask at the end of every sync is not "does it build" but "is the installation now written the way the reference is written?" — compare the reference's own PLC_PRG_MAIN declaration and init action against the installation's and see whether they are the same shape.

7. Apply to the working copy

./tools/ai/codesys.ps1 apply -Project $copy -Force -Candidates .ai\sync\candidates `
    -ImportFolders -ImportConflict replace -Edits none

Writes and saves the copy. apply refuses to save if the build fails, and injects no harness — so verify first, always.